diff --git a/3rdparty/ValveFileVDF/include/vdf_parser.hpp b/3rdparty/ValveFileVDF/vdf_parser.hpp similarity index 100% rename from 3rdparty/ValveFileVDF/include/vdf_parser.hpp rename to 3rdparty/ValveFileVDF/vdf_parser.hpp diff --git a/3rdparty/curl/bin/curl-config b/3rdparty/curl/bin/curl-config index 8ee211c..8ab73a9 100644 --- a/3rdparty/curl/bin/curl-config +++ b/3rdparty/curl/bin/curl-config @@ -25,13 +25,13 @@ # shellcheck disable=SC2006 -prefix='F:\SourceCode\curl\build\curl' +prefix='F:/SourceCode/XSteam/3rdparty/curl' # Used in 'libdir' # shellcheck disable=SC2034 exec_prefix="${prefix}" # shellcheck disable=SC2034 includedir="${prefix}/include" -cppflag_curl_staticlib='-DCURL_STATICLIB' +cppflag_curl_staticlib='' usage() { @@ -67,7 +67,7 @@ fi while test "$#" -gt 0; do case "$1" in --built-shared) - echo 'no' + echo 'yes' ;; --ca) @@ -75,7 +75,7 @@ while test "$#" -gt 0; do ;; --cc) - echo 'D:/Dev/msys64/mingw64/bin/cc.exe' + echo 'D:/Dev/Qt/Tools/mingw1120_64/bin/gcc.exe' ;; --prefix) @@ -83,14 +83,14 @@ while test "$#" -gt 0; do ;; --feature|--features) - for feature in alt-svc AsynchDNS HSTS HTTP2 HTTP3 HTTPS-proxy IDN IPv6 Largefile libz NTLM PSL SSL threadsafe TLS-SRP UnixSockets zstd ''; do + for feature in alt-svc AsynchDNS HTTP2 IDN IPv6 Largefile NTLM PSL threadsafe UnixSockets ''; do test -n "$feature" && echo "$feature" done ;; --protocols) # shellcheck disable=SC2043 - for protocol in DICT FILE FTP FTPS GOPHER GOPHERS HTTP HTTPS IMAP IMAPS IPFS IPNS LDAP LDAPS MQTT POP3 POP3S RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP; do + for protocol in DICT FILE FTP GOPHER HTTP IMAP IPFS IPNS LDAP LDAPS MQTT POP3 RTSP SCP SFTP SMB SMTP TELNET TFTP; do echo "$protocol" done ;; @@ -160,20 +160,20 @@ while test "$#" -gt 0; do else CURLLIBDIR='' fi - if test 'Xno' = 'Xno'; then - echo "${CURLLIBDIR}-lcurl -lidn2 -lws2_32 -lbcrypt -lssl -lcrypto -lz -lzstd -lnghttp2 -lnghttp3 -lwldap32 -lpsl -lssh2 -ladvapi32 -lcrypt32" + if test 'Xyes' = 'Xno'; then + echo "${CURLLIBDIR}-lcurl -lidn2 -lws2_32 -lbcrypt -lnghttp2 -lwldap32 -lpsl -lssh2 -ladvapi32 -lcrypt32" else echo "${CURLLIBDIR}-lcurl" fi ;; --ssl-backends) - echo 'OpenSSL v3+' + echo '' ;; --static-libs) if test 'Xyes' != 'Xno'; then - echo "${exec_prefix}/lib/libcurl.a -LD:/Dev/msys64/mingw64/bin/../lib -LD:/Dev/msys64/mingw64/lib -lidn2 -lws2_32 -lbcrypt -lssl -lcrypto -lz -lzstd -lnghttp2 -lnghttp3 -lwldap32 -lpsl -lssh2 -ladvapi32 -lcrypt32" + echo "${exec_prefix}/lib/libcurl.a -LD:/Dev/msys64/mingw64/bin/../lib -LD:/Dev/msys64/mingw64/lib -lidn2 -lws2_32 -lbcrypt -lnghttp2 -lwldap32 -lpsl -lssh2 -ladvapi32 -lcrypt32" else echo 'curl was built with static libraries disabled' >&2 exit 1 diff --git a/3rdparty/curl/bin/curl.exe b/3rdparty/curl/bin/curl.exe index d91c544..8aa504a 100644 Binary files a/3rdparty/curl/bin/curl.exe and b/3rdparty/curl/bin/curl.exe differ diff --git a/3rdparty/curl/bin/libcurl.dll b/3rdparty/curl/bin/libcurl.dll new file mode 100644 index 0000000..a97f91f Binary files /dev/null and b/3rdparty/curl/bin/libcurl.dll differ diff --git a/3rdparty/curl/lib/cmake/CURL/CURLConfig.cmake b/3rdparty/curl/lib/cmake/CURL/CURLConfig.cmake index b404d62..5937759 100644 --- a/3rdparty/curl/lib/cmake/CURL/CURLConfig.cmake +++ b/3rdparty/curl/lib/cmake/CURL/CURLConfig.cmake @@ -55,11 +55,11 @@ endif() option(CURL_USE_PKGCONFIG "Enable pkg-config to detect CURL dependencies" ${_curl_use_pkgconfig_default}) include(CMakeFindDependencyMacro) -if("ON") - find_dependency(OpenSSL "3") +if("") + find_dependency(OpenSSL "") endif() -if("ON") - find_dependency(ZLIB "1") +if("OFF") + find_dependency(ZLIB "") endif() include("${CMAKE_CURRENT_LIST_DIR}/CURLTargets.cmake") @@ -67,7 +67,7 @@ check_required_components("CURL") # Alias for either shared or static library if(NOT TARGET CURL::libcurl) - add_library(CURL::libcurl ALIAS CURL::libcurl_static) + add_library(CURL::libcurl ALIAS CURL::libcurl_shared) endif() # For compatibility with CMake's FindCURL.cmake diff --git a/3rdparty/curl/lib/cmake/CURL/CURLConfigVersion.cmake b/3rdparty/curl/lib/cmake/CURL/CURLConfigVersion.cmake index 0b1b332..0e749d5 100644 --- a/3rdparty/curl/lib/cmake/CURL/CURLConfigVersion.cmake +++ b/3rdparty/curl/lib/cmake/CURL/CURLConfigVersion.cmake @@ -58,11 +58,6 @@ else() endif() -# if the installed project requested no architecture check, don't perform the check -if("FALSE") - return() -endif() - # if the installed or the using project don't have CMAKE_SIZEOF_VOID_P set, ignore it: if("${CMAKE_SIZEOF_VOID_P}" STREQUAL "" OR "8" STREQUAL "") return() diff --git a/3rdparty/curl/lib/cmake/CURL/CURLTargets-release.cmake b/3rdparty/curl/lib/cmake/CURL/CURLTargets-release.cmake index c87e8ac..1c47f63 100644 --- a/3rdparty/curl/lib/cmake/CURL/CURLTargets-release.cmake +++ b/3rdparty/curl/lib/cmake/CURL/CURLTargets-release.cmake @@ -15,6 +15,16 @@ set_target_properties(CURL::libcurl_static PROPERTIES list(APPEND _cmake_import_check_targets CURL::libcurl_static ) list(APPEND _cmake_import_check_files_for_CURL::libcurl_static "${_IMPORT_PREFIX}/lib/libcurl.a" ) +# Import target "CURL::libcurl_shared" for configuration "Release" +set_property(TARGET CURL::libcurl_shared APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE) +set_target_properties(CURL::libcurl_shared PROPERTIES + IMPORTED_IMPLIB_RELEASE "${_IMPORT_PREFIX}/lib/libcurl.dll.a" + IMPORTED_LOCATION_RELEASE "${_IMPORT_PREFIX}/bin/libcurl.dll" + ) + +list(APPEND _cmake_import_check_targets CURL::libcurl_shared ) +list(APPEND _cmake_import_check_files_for_CURL::libcurl_shared "${_IMPORT_PREFIX}/lib/libcurl.dll.a" "${_IMPORT_PREFIX}/bin/libcurl.dll" ) + # Import target "CURL::curl" for configuration "Release" set_property(TARGET CURL::curl APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE) set_target_properties(CURL::curl PROPERTIES diff --git a/3rdparty/curl/lib/cmake/CURL/CURLTargets.cmake b/3rdparty/curl/lib/cmake/CURL/CURLTargets.cmake index 40979db..792ec6e 100644 --- a/3rdparty/curl/lib/cmake/CURL/CURLTargets.cmake +++ b/3rdparty/curl/lib/cmake/CURL/CURLTargets.cmake @@ -3,11 +3,11 @@ if("${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION}" LESS 2.8) message(FATAL_ERROR "CMake >= 2.8.0 required") endif() -if(CMAKE_VERSION VERSION_LESS "2.8.3") - message(FATAL_ERROR "CMake >= 2.8.3 required") +if(CMAKE_VERSION VERSION_LESS "2.8.12") + message(FATAL_ERROR "CMake >= 2.8.12 required") endif() cmake_policy(PUSH) -cmake_policy(VERSION 2.8.3...3.22) +cmake_policy(VERSION 2.8.12...3.28) #---------------------------------------------------------------- # Generated CMake target import file. #---------------------------------------------------------------- @@ -19,7 +19,7 @@ set(CMAKE_IMPORT_FILE_VERSION 1) set(_cmake_targets_defined "") set(_cmake_targets_not_defined "") set(_cmake_expected_targets "") -foreach(_cmake_expected_target IN ITEMS CURL::libcurl_static CURL::curl) +foreach(_cmake_expected_target IN ITEMS CURL::libcurl_static CURL::libcurl_shared CURL::curl) list(APPEND _cmake_expected_targets "${_cmake_expected_target}") if(TARGET "${_cmake_expected_target}") list(APPEND _cmake_targets_defined "${_cmake_expected_target}") @@ -61,16 +61,19 @@ add_library(CURL::libcurl_static STATIC IMPORTED) set_target_properties(CURL::libcurl_static PROPERTIES INTERFACE_COMPILE_DEFINITIONS "CURL_STATICLIB" INTERFACE_INCLUDE_DIRECTORIES "${_IMPORT_PREFIX}/include" - INTERFACE_LINK_LIBRARIES "\$;\$;\$;\$;\$;\$;D:/Dev/msys64/mingw64/lib/libzstd.dll.a;D:/Dev/msys64/mingw64/lib/libnghttp2.dll.a;D:/Dev/msys64/mingw64/lib/libnghttp3.dll.a;\$;D:/Dev/msys64/mingw64/lib/libpsl.dll.a;D:/Dev/msys64/mingw64/lib/libssh2.dll.a;\$;\$" + INTERFACE_LINK_LIBRARIES "\$;\$;\$;D:/Dev/msys64/mingw64/lib/libnghttp2.dll.a;\$;D:/Dev/msys64/mingw64/lib/libpsl.dll.a;D:/Dev/msys64/mingw64/lib/libssh2.dll.a;\$;\$" +) + +# Create imported target CURL::libcurl_shared +add_library(CURL::libcurl_shared SHARED IMPORTED) + +set_target_properties(CURL::libcurl_shared PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${_IMPORT_PREFIX}/include" ) # Create imported target CURL::curl add_executable(CURL::curl IMPORTED) -if(CMAKE_VERSION VERSION_LESS 2.8.12) - message(FATAL_ERROR "This file relies on consumers using CMake 2.8.12 or greater.") -endif() - # Load information for each installed configuration. file(GLOB _cmake_config_files "${CMAKE_CURRENT_LIST_DIR}/CURLTargets-*.cmake") foreach(_cmake_config_file IN LISTS _cmake_config_files) @@ -84,9 +87,12 @@ set(_IMPORT_PREFIX) # Loop over all imported files and verify that they actually exist foreach(_cmake_target IN LISTS _cmake_import_check_targets) - foreach(_cmake_file IN LISTS "_cmake_import_check_files_for_${_cmake_target}") - if(NOT EXISTS "${_cmake_file}") - message(FATAL_ERROR "The imported target \"${_cmake_target}\" references the file + if(CMAKE_VERSION VERSION_LESS "3.28" + OR NOT DEFINED _cmake_import_check_xcframework_for_${_cmake_target} + OR NOT IS_DIRECTORY "${_cmake_import_check_xcframework_for_${_cmake_target}}") + foreach(_cmake_file IN LISTS "_cmake_import_check_files_for_${_cmake_target}") + if(NOT EXISTS "${_cmake_file}") + message(FATAL_ERROR "The imported target \"${_cmake_target}\" references the file \"${_cmake_file}\" but this file does not exist. Possible reasons include: * The file was deleted, renamed, or moved to another location. @@ -95,8 +101,9 @@ but this file does not exist. Possible reasons include: \"${CMAKE_CURRENT_LIST_FILE}\" but not all the files it references. ") - endif() - endforeach() + endif() + endforeach() + endif() unset(_cmake_file) unset("_cmake_import_check_files_for_${_cmake_target}") endforeach() diff --git a/3rdparty/curl/lib/libcurl.a b/3rdparty/curl/lib/libcurl.a index 0afd2bf..8276ef4 100644 Binary files a/3rdparty/curl/lib/libcurl.a and b/3rdparty/curl/lib/libcurl.a differ diff --git a/3rdparty/curl/lib/libcurl.dll.a b/3rdparty/curl/lib/libcurl.dll.a new file mode 100644 index 0000000..62d0f1f Binary files /dev/null and b/3rdparty/curl/lib/libcurl.dll.a differ diff --git a/3rdparty/curl/lib/pkgconfig/libcurl.pc b/3rdparty/curl/lib/pkgconfig/libcurl.pc index 218a83f..f15db15 100644 --- a/3rdparty/curl/lib/pkgconfig/libcurl.pc +++ b/3rdparty/curl/lib/pkgconfig/libcurl.pc @@ -22,20 +22,20 @@ # ########################################################################### -prefix=F:\SourceCode\curl\build\curl +prefix=F:/SourceCode/XSteam/3rdparty/curl exec_prefix=${prefix} libdir=${exec_prefix}/lib includedir=${prefix}/include -supported_protocols="DICT FILE FTP FTPS GOPHER GOPHERS HTTP HTTPS IMAP IMAPS IPFS IPNS LDAP LDAPS MQTT POP3 POP3S RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP" -supported_features="alt-svc AsynchDNS HSTS HTTP2 HTTP3 HTTPS-proxy IDN IPv6 Largefile libz NTLM PSL SSL threadsafe TLS-SRP UnixSockets zstd" +supported_protocols="DICT FILE FTP GOPHER HTTP IMAP IPFS IPNS LDAP LDAPS MQTT POP3 RTSP SCP SFTP SMB SMTP TELNET TFTP" +supported_features="alt-svc AsynchDNS HTTP2 IDN IPv6 Largefile NTLM PSL threadsafe UnixSockets" Name: libcurl URL: https://curl.se/ Description: Library to transfer files with HTTP, FTP, etc. Version: 8.11.0-DEV -Requires: libidn2,openssl,zlib,libzstd,libnghttp2,libnghttp3,libpsl,libssh2 -Requires.private: libidn2,openssl,zlib,libzstd,libnghttp2,libnghttp3,libpsl,libssh2 -Libs: -L${libdir} -lcurl -lidn2 -lws2_32 -lbcrypt -lssl -lcrypto -lz -lzstd -lnghttp2 -lnghttp3 -lwldap32 -lpsl -lssh2 -ladvapi32 -lcrypt32 -Libs.private: -LD:/Dev/msys64/mingw64/bin/../lib -LD:/Dev/msys64/mingw64/lib -lidn2 -lws2_32 -lbcrypt -lssl -lcrypto -lz -lzstd -lnghttp2 -lnghttp3 -lwldap32 -lpsl -lssh2 -ladvapi32 -lcrypt32 -Cflags: -I${includedir} -DCURL_STATICLIB +Requires: +Requires.private: libidn2,libnghttp2,libpsl,libssh2 +Libs: -L${libdir} -lcurl +Libs.private: -LD:/Dev/msys64/mingw64/bin/../lib -LD:/Dev/msys64/mingw64/lib -lidn2 -lws2_32 -lbcrypt -lnghttp2 -lwldap32 -lpsl -lssh2 -ladvapi32 -lcrypt32 +Cflags: -I${includedir} Cflags.private: -DCURL_STATICLIB diff --git a/3rdparty/curl/share/man/man1/curl-config.1 b/3rdparty/curl/share/man/man1/curl-config.1 new file mode 100644 index 0000000..1ffa683 --- /dev/null +++ b/3rdparty/curl/share/man/man1/curl-config.1 @@ -0,0 +1,82 @@ +.\" generated by cd2nroff 0.1 from curl-config.md +.TH curl-config 1 "2024-10-11" curl-config +.SH NAME +curl\-config \- Get information about a libcurl installation +.SH SYNOPSIS +\fBcurl\-config [options]\fP +.SH DESCRIPTION +\fBcurl\-config\fP +displays information about the curl and libcurl installation. +.SH OPTIONS +.IP --ca +Displays the built\-in path to the CA cert bundle this libcurl uses. +.IP --cc +Displays the compiler used to build libcurl. +.IP --cflags +Set of compiler options (CFLAGS) to use when compiling files that use +libcurl. Currently that is only the include path to the curl include files. +.IP "--checkfor [version]" +Specify the oldest possible libcurl version string you want, and this script +returns 0 if the current installation is new enough or it returns 1 and +outputs a text saying that the current version is not new enough. (Added in +7.15.4) +.IP --configure +Displays the arguments given to configure when building curl. +.IP --feature +Lists what particular main features the installed libcurl was built with. At +the time of writing, this list may include SSL, KRB4 or IPv6. Do not assume +any particular order. The keywords are separated by newlines. There may be +none, one, or several keywords in the list. +.IP --help +Displays the available options. +.IP --libs +Shows the complete set of libs and other linker options you need in order to +link your application with libcurl. +.IP --prefix +This is the prefix used when libcurl was installed. Libcurl is then installed +in $prefix/lib and its header files are installed in $prefix/include and so +on. The prefix is set with "configure \--prefix". +.IP --protocols +Lists what particular protocols the installed libcurl was built to support. At +the time of writing, this list may include HTTP, HTTPS, FTP, FTPS, FILE, +TELNET, LDAP, DICT and many more. Do not assume any particular order. The +protocols are listed using uppercase and are separated by newlines. There may +be none, one, or several protocols in the list. (Added in 7.13.0) +.IP --ssl-backends +Lists the SSL backends that were enabled when libcurl was built. It might be +no, one or several names. If more than one name, they appear comma\-separated. +(Added in 7.58.0) +.IP --static-libs +Shows the complete set of libs and other linker options you need in order to +link your application with libcurl statically. (Added in 7.17.1) +.IP --version +Outputs version information about the installed libcurl. +.IP --vernum +Outputs version information about the installed libcurl, in numerical mode. +This shows the version number, in hexadecimal, using 8 bits for each part: +major, minor, and patch numbers. This makes libcurl 7.7.4 appear as 070704 and +libcurl 12.13.14 appear as 0c0d0e... Note that the initial zero might be +omitted. (This option was broken in the 7.15.0 release.) +.SH EXAMPLES +What linker options do I need when I link with libcurl? +.nf + $ curl-config --libs +.fi +What compiler options do I need when I compile using libcurl functions? +.nf + $ curl-config --cflags +.fi +How do I know if libcurl was built with SSL support? +.nf + $ curl-config --feature | grep SSL +.fi +What\(aqs the installed libcurl version? +.nf + $ curl-config --version +.fi +How do I build a single file with a one\-line command? +.nf + $ `curl-config --cc --cflags` -o example source.c `curl-config --libs` +.fi +.SH SEE ALSO +.BR curl (1) diff --git a/3rdparty/curl/share/man/man1/curl.1 b/3rdparty/curl/share/man/man1/curl.1 index 6faab0c..dfcd46b 100644 --- a/3rdparty/curl/share/man/man1/curl.1 +++ b/3rdparty/curl/share/man/man1/curl.1 @@ -24,7 +24,7 @@ .\" .\" DO NOT EDIT. Generated by the curl project managen manpage generator. .\" -.TH curl 1 "2024-09-25" "curl 8.11.0" "curl Manual" +.TH curl 1 "2024-10-11" "curl 8.11.0" "curl Manual" .SH NAME curl \- transfer a URL .SH SYNOPSIS diff --git a/3rdparty/curl/share/man/man1/mk-ca-bundle.1 b/3rdparty/curl/share/man/man1/mk-ca-bundle.1 new file mode 100644 index 0000000..eabe565 --- /dev/null +++ b/3rdparty/curl/share/man/man1/mk-ca-bundle.1 @@ -0,0 +1,81 @@ +.\" generated by cd2nroff 0.1 from mk-ca-bundle.md +.TH mk-ca-bundle 1 "2024-10-11" mk-ca-bundle +.SH NAME +mk\-ca\-bundle \- convert Mozilla\(aqs certificate bundle to PEM format +.SH SYNOPSIS +mk\-ca\-bundle [options] [output] +.SH DESCRIPTION +This tool downloads the \fIcertdata.txt\fP file from Mozilla\(aqs source tree over +HTTPS, then parses it and extracts the included certificates into PEM format. +By default, only CA root certificates trusted to issue SSL server +authentication certificates are extracted. These are then processed with the +OpenSSL command line tool to produce the final ca\-bundle output file. + +The default \fIoutput\fP name is \fBca\-bundle.crt\fP. By setting it to \(aq\-\(aq (a single +dash) you get the output sent to STDOUT instead of a file. + +The PEM format this scripts uses for output makes the result readily available +for use by just about all OpenSSL or GnuTLS powered applications, such as curl +and others. +.SH OPTIONS +The following options are supported: +.IP -b +backup an existing version of \fIoutput\fP +.IP "-d [name]" +specify which Mozilla tree to pull \fIcertdata.txt\fP from (or a custom URL). +Valid names are: \fBaurora\fP, \fBbeta\fP, \fBcentral\fP, \fBMozilla\fP, \fBnss\fP, +\fBrelease\fP (default). They are shortcuts for which source tree to get the +certificate data from. +.IP -f +force rebuild even if \fIcertdata.txt\fP is current (Added in version 1.17) +.IP -i +print version info about used modules +.IP -k +Allow insecure data transfer. By default (since 1.27) this command fails if +the HTTPS transfer fails. This overrides that decision (and opens for +man\-in\-the\-middle attacks). +.IP -l +print license info about \fIcertdata.txt\fP +.IP -m +(Added in 1.26) Include meta data comments in the output. The meta data is +specific information about each certificate that is stored in the original +file as comments and using this option makes those comments get passed on to +the output file. The meta data is not parsed in any way by mk\-ca\-bundle. +.IP -n +Do not download \fIcertdata.txt\fP \- use the existing. +.IP "-p [purposes]:[levels]" +list of Mozilla trust purposes and levels for certificates to include in +output. Takes the form of a comma separated list of purposes, a colon, and a +comma separated list of levels. The default is to include all certificates +trusted to issue SSL Server certificates (\fISERVER_AUTH:TRUSTED_DELEGATOR\fP). + +Valid purposes are: \fBALL\fP, \fBDIGITAL_SIGNATURE\fP, \fBNON_REPUDIATION\fP, +\fBKEY_ENCIPHERMENT\fP, \fBDATA_ENCIPHERMENT\fP, \fBKEY_AGREEMENT\fP, +\fBKEY_CERT_SIGN\fP, \fBCRL_SIGN\fP, \fBSERVER_AUTH\fP (default), \fBCLIENT_AUTH\fP, +\fBCODE_SIGNING\fP, \fBEMAIL_PROTECTION\fP, \fBIPSEC_END_SYSTEM\fP, +\fBIPSEC_TUNNEL\fP, \fBIPSEC_USER\fP, \fBTIME_STAMPING\fP, \fBSTEP_UP_APPROVED\fP + +Valid trust levels are: \fBALL\fP, \fBTRUSTED_DELEGATOR\fP (default), \fBNOT_TRUSTED\fP, +\fBMUST_VERIFY_TRUST\fP, \fBTRUSTED\fP +.IP -q +be really quiet (no progress output at all) +.IP -t +include plain text listing of certificates +.IP "-s [algorithms]" +A comma separated list of signature algorithms with which to hash/fingerprint +each certificate and output when run in plain text mode. + +Valid algorithms are: +ALL, NONE, MD5 (default), SHA1, SHA256, SHA384, SHA512 +.IP -u +unlink (remove) \fIcertdata.txt\fP after processing +.IP -v +be verbose and print out processed certificate authorities +.SH EXIT STATUS +Returns 0 on success. Returns 1 if it fails to download data. +.SH FILE FORMAT +The file format used by Mozilla for this trust information is documented here: + +https://p11\-glue.freedesktop.org/doc/storing\-trust\-policy/storing\-trust\-existing.html +.SH SEE ALSO +.BR curl (1) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_ACTIVESOCKET.3 b/3rdparty/curl/share/man/man3/CURLINFO_ACTIVESOCKET.3 new file mode 100644 index 0000000..39c3313 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_ACTIVESOCKET.3 @@ -0,0 +1,63 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_ACTIVESOCKET.md +.TH CURLINFO_ACTIVESOCKET 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_ACTIVESOCKET \- get the active socket +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_ACTIVESOCKET, + curl_socket_t *socket); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_socket_t to receive the most recently active socket +used for the transfer connection by this curl session. If the socket is no +longer valid, \fICURL_SOCKET_BAD\fP is returned. When you are finished working +with the socket, you must call \fIcurl_easy_cleanup(3)\fP as usual on the easy +handle and let libcurl close the socket and cleanup other resources associated +with the handle. This option returns the active socket only after the transfer +is complete, and is typically used in combination with +\fICURLOPT_CONNECT_ONLY(3)\fP, which skips the transfer phase. + +\fICURLINFO_ACTIVESOCKET(3)\fP was added as a replacement for +\fICURLINFO_LASTSOCKET(3)\fP since that one is not working on all platforms. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_socket_t sockfd; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Do not do the transfer - only connect to host */ + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); + res = curl_easy_perform(curl); + if(res != CURLE_OK) { + printf("Error: %s\\n", curl_easy_strerror(res)); + curl_easy_cleanup(curl); + return 1; + } + + /* Extract the socket from the curl handle */ + res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); + if(!res && sockfd != CURL_SOCKET_BAD) { + /* operate on sockfd */ + } + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.45.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_LASTSOCKET (3), +.BR CURLOPT_CONNECT_ONLY (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_APPCONNECT_TIME.3 b/3rdparty/curl/share/man/man3/CURLINFO_APPCONNECT_TIME.3 new file mode 100644 index 0000000..64f22d7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_APPCONNECT_TIME.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_APPCONNECT_TIME.md +.TH CURLINFO_APPCONNECT_TIME 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_APPCONNECT_TIME \- get the time until the SSL/SSH handshake is completed +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME, + double *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the time, in seconds, it took from the +start until the SSL/SSH connect/handshake to the remote host was completed. +This time is most often close to the \fICURLINFO_PRETRANSFER_TIME(3)\fP time, except +for cases such as HTTP multiplexing where the pretransfer time can be delayed +due to waits in line for the stream and more. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double connect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME, &connect); + if(CURLE_OK == res) { + printf("Time: %.1f", connect); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_APPCONNECT_TIME_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_APPCONNECT_TIME_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_APPCONNECT_TIME_T.3 new file mode 100644 index 0000000..f9bd2ef --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_APPCONNECT_TIME_T.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_APPCONNECT_TIME_T.md +.TH CURLINFO_APPCONNECT_TIME_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_APPCONNECT_TIME_T \- time until the SSL/SSH handshake completed +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME_T, + curl_off_t *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t to receive the time, in microseconds, it took +from the start until the SSL/SSH connect/handshake to the remote host was +completed. This time is most often close to the \fICURLINFO_PRETRANSFER_TIME_T(3)\fP +time, except for cases such as HTTP multiplexing where the pretransfer time +can be delayed due to waits in line for the stream and more. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t connect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME_T, &connect); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000, + (long)(connect % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.61.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_APPCONNECT_TIME (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CAINFO.3 b/3rdparty/curl/share/man/man3/CURLINFO_CAINFO.3 new file mode 100644 index 0000000..862d7a7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CAINFO.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CAINFO.md +.TH CURLINFO_CAINFO 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CAINFO \- get the default built\-in CA certificate path +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CAINFO, char **path); +.fi +.SH DESCRIPTION +Pass a pointer to a char pointer to receive the pointer to a null\-terminated +string holding the default built\-in path used for the \fICURLOPT_CAINFO(3)\fP +option unless set by the user. + +Note that in a situation where libcurl has been built to support multiple TLS +libraries, this option might return a string even if the specific TLS library +currently set to be used does not support \fICURLOPT_CAINFO(3)\fP. + +This is a path identifying a single file containing CA certificates. + +The \fBpath\fP pointer is set to NULL if there is no default path. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + char *cainfo = NULL; + curl_easy_getinfo(curl, CURLINFO_CAINFO, &cainfo); + if(cainfo) { + printf("default ca info path: %s\\n", cainfo); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.84.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CAPATH (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CAPATH.3 b/3rdparty/curl/share/man/man3/CURLINFO_CAPATH.3 new file mode 100644 index 0000000..682a18a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CAPATH.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CAPATH.md +.TH CURLINFO_CAPATH 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CAPATH \- get the default built\-in CA path string +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CAPATH, char **path); +.fi +.SH DESCRIPTION +Pass a pointer to a char pointer to receive the pointer to a null\-terminated +string holding the default built\-in path used for the \fICURLOPT_CAPATH(3)\fP +option unless set by the user. + +Note that in a situation where libcurl has been built to support multiple TLS +libraries, this option might return a string even if the specific TLS library +currently set to be used does not support \fICURLOPT_CAPATH(3)\fP. + +This is a path identifying a directory. + +The \fBpath\fP pointer is set to NULL if there is no default path. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + char *capath = NULL; + curl_easy_getinfo(curl, CURLINFO_CAPATH, &capath); + if(capath) { + printf("default ca path: %s\\n", capath); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.84.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CAINFO (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CERTINFO.3 b/3rdparty/curl/share/man/man3/CURLINFO_CERTINFO.3 new file mode 100644 index 0000000..f5bffe5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CERTINFO.3 @@ -0,0 +1,84 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CERTINFO.md +.TH CURLINFO_CERTINFO 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CERTINFO \- get the TLS certificate chain +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CERTINFO, + struct curl_certinfo **chainp); +.fi +.SH DESCRIPTION +Pass a pointer to a \fIstruct curl_certinfo \fP* and it is set to point to a +struct that holds info about the server\(aqs certificate chain, assuming you had +\fICURLOPT_CERTINFO(3)\fP enabled when the request was made. + +.nf +struct curl_certinfo { + int num_of_certs; + struct curl_slist **certinfo; +}; +.fi + +The \fIcertinfo\fP struct member is an array of linked lists of certificate +information. The \fInum_of_certs\fP struct member is the number of certificates +which is the number of elements in the array. Each certificate\(aqs list has +items with textual information in the format "name:content" such as +\&"Subject:Foo", "Issuer:Bar", etc. The items in each list varies depending on +the SSL backend and the certificate. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, Schannel and Secure Transport +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); + + /* connect to any HTTPS site, trusted or not */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); + + curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L); + + res = curl_easy_perform(curl); + + if(!res) { + int i; + struct curl_certinfo *ci; + res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci); + + if(!res) { + printf("%d certs!\\n", ci->num_of_certs); + + for(i = 0; i < ci->num_of_certs; i++) { + struct curl_slist *slist; + + for(slist = ci->certinfo[i]; slist; slist = slist->next) + printf("%s\\n", slist->data); + } + } + } + curl_easy_cleanup(curl); + } +} +.fi + +See also the \fIcertinfo.c\fP example. +.SH HISTORY +GnuTLS support added in 7.42.0. Schannel support added in 7.50.0. Secure +Transport support added in 7.79.0. mbedTLS support added in 8.9.0. +.SH AVAILABILITY +Added in curl 7.19.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CAPATH (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CONDITION_UNMET.3 b/3rdparty/curl/share/man/man3/CURLINFO_CONDITION_UNMET.3 new file mode 100644 index 0000000..9434825 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CONDITION_UNMET.3 @@ -0,0 +1,61 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CONDITION_UNMET.md +.TH CURLINFO_CONDITION_UNMET 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CONDITION_UNMET \- get info on unmet time conditional or 304 HTTP response. +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONDITION_UNMET, + long *unmet); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the number 1 if the condition provided in +the previous request did not match (see \fICURLOPT_TIMECONDITION(3)\fP). Alas, +if this returns a 1 you know that the reason you did not get data in return is +because it did not fulfill the condition. The long this argument points to +gets a zero stored if the condition instead was met. This can also return 1 if +the server responded with a 304 HTTP status code, for example after sending a +custom "If\-Match\-*" header. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* January 1, 2020 is 1577833200 */ + curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); + + /* If-Modified-Since the above time stamp */ + curl_easy_setopt(curl, CURLOPT_TIMECONDITION, + (long)CURL_TIMECOND_IFMODSINCE); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the time condition */ + long unmet; + res = curl_easy_getinfo(curl, CURLINFO_CONDITION_UNMET, &unmet); + if(!res) { + printf("The time condition was %sfulfilled\\n", unmet?"NOT":""); + } + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_TIMECONDITION (3), +.BR CURLOPT_TIMEVALUE (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CONNECT_TIME.3 b/3rdparty/curl/share/man/man3/CURLINFO_CONNECT_TIME.3 new file mode 100644 index 0000000..dc21c11 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CONNECT_TIME.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CONNECT_TIME.md +.TH CURLINFO_CONNECT_TIME 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CONNECT_TIME \- get the time until connect +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONNECT_TIME, double *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the total time in seconds from the start +until the connection to the remote host (or proxy) was completed. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double connect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME, &connect); + if(CURLE_OK == res) { + printf("Time: %.1f", connect); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.4.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CONNECT_TIME_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CONNECT_TIME_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_CONNECT_TIME_T.3 new file mode 100644 index 0000000..89377c6 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CONNECT_TIME_T.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CONNECT_TIME_T.md +.TH CURLINFO_CONNECT_TIME_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CONNECT_TIME_T \- get the time until connect +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONNECT_TIME_T, + curl_off_t *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t to receive the total time in microseconds from +the start until the connection to the remote host (or proxy) was completed. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t connect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME_T, &connect); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000, + (long)(connect % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.61.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CONNECT_TIME (3), +.BR CURLOPT_CONNECTTIMEOUT (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CONN_ID.3 b/3rdparty/curl/share/man/man3/CURLINFO_CONN_ID.3 new file mode 100644 index 0000000..1193727 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CONN_ID.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CONN_ID.md +.TH CURLINFO_CONN_ID 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CONN_ID \- get the ID of the last connection used by the handle +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONN_ID, + curl_off_t *conn_id); +.fi +.SH DESCRIPTION +Pass a pointer to a \fIcurl_off_t\fP to receive the connection identifier last +used by the handle. Stores \-1 if there was no connection used. + +The connection id is unique among all connections using the same +connection cache. This is implicitly the case for all connections in the +same multi handle. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + curl_off_t conn_id; + res = curl_easy_getinfo(curl, CURLINFO_CONN_ID, &conn_id); + if(!res) { + printf("Connection used: %" CURL_FORMAT_CURL_OFF_T "\\n", conn_id); + } + } + } +} +.fi +.SH AVAILABILITY +Added in curl 8.2.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_XFER_ID (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 b/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 new file mode 100644 index 0000000..bf24e1b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CONTENT_LENGTH_DOWNLOAD.md +.TH CURLINFO_CONTENT_LENGTH_DOWNLOAD 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CONTENT_LENGTH_DOWNLOAD \- get content\-length of download +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_DOWNLOAD, + double *content_length); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the content\-length of the download. This +is the value read from the Content\-Length: field. Since 7.19.4, this returns +-1 if the size is not known. + +\fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP is a newer replacement that returns a more +sensible variable type. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + double cl; + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD, &cl); + if(!res) { + printf("Size: %.0f\\n", cl); + } + } + } +} +.fi +.SH DEPRECATED +Deprecated since 7.55.0. +.SH AVAILABILITY +Added in curl 7.6.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CONTENT_LENGTH_UPLOAD (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 new file mode 100644 index 0000000..6df032a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md +.TH CURLINFO_CONTENT_LENGTH_DOWNLOAD_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CONTENT_LENGTH_DOWNLOAD_T \- get content\-length of download +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_DOWNLOAD_T, + curl_off_t *content_length); +.fi +.SH DESCRIPTION +Pass a pointer to a \fIcurl_off_t\fP to receive the content\-length of the +download. This is the value read from the Content\-Length: field. Stores \-1 if +the size is not known. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + curl_off_t cl; + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD_T, &cl); + if(!res) { + printf("Download size: %" CURL_FORMAT_CURL_OFF_T "\\n", cl); + } + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.55.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CONTENT_LENGTH_UPLOAD_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_UPLOAD.3 b/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_UPLOAD.3 new file mode 100644 index 0000000..53d4d2f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_UPLOAD.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CONTENT_LENGTH_UPLOAD.md +.TH CURLINFO_CONTENT_LENGTH_UPLOAD 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CONTENT_LENGTH_UPLOAD \- get the specified size of the upload +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_UPLOAD, + double *content_length); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the specified size of the upload. Since +7.19.4, this returns \-1 if the size is not known. + +\fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP is a newer replacement that returns a +more sensible variable type. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the upload */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + double cl; + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_UPLOAD, &cl); + if(!res) { + printf("Size: %.0f\\n", cl); + } + } + } +} +.fi +.SH DEPRECATED +Deprecated since 7.55.0. +.SH AVAILABILITY +Added in curl 7.6.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 new file mode 100644 index 0000000..c344148 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CONTENT_LENGTH_UPLOAD_T.md +.TH CURLINFO_CONTENT_LENGTH_UPLOAD_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CONTENT_LENGTH_UPLOAD_T \- get the specified size of the upload +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_UPLOAD_T, + curl_off_t *content_length); +.fi +.SH DESCRIPTION +Pass a pointer to a \fIcurl_off_t\fP to receive the specified size of the +upload. Stores \-1 if the size is not known. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the upload */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + curl_off_t cl; + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_UPLOAD_T, &cl); + if(!res) { + printf("Upload size: %" CURL_FORMAT_CURL_OFF_T "\\n", cl); + } + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.55.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_TYPE.3 b/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_TYPE.3 new file mode 100644 index 0000000..7191688 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_CONTENT_TYPE.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_CONTENT_TYPE.md +.TH CURLINFO_CONTENT_TYPE 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_CONTENT_TYPE \- get Content\-Type +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_TYPE, char **ct); +.fi +.SH DESCRIPTION +Pass a pointer to a char pointer to receive the content\-type of the downloaded +object. This is the value read from the Content\-Type: field. If you get NULL, +it means that the server did not send a valid Content\-Type header or that the +protocol used does not support this. + +The \fBct\fP pointer is set to NULL or pointing to private memory. You MUST +NOT free it \- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the +corresponding CURL handle. + +The modern way to get this header from a response is to instead use the +\fIcurl_easy_header(3)\fP function. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract the content-type */ + char *ct = NULL; + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct); + if(!res && ct) { + printf("Content-Type: %s\\n", ct); + } + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HEADERFUNCTION (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_header (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_COOKIELIST.3 b/3rdparty/curl/share/man/man3/CURLINFO_COOKIELIST.3 new file mode 100644 index 0000000..07ad8be --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_COOKIELIST.3 @@ -0,0 +1,63 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_COOKIELIST.md +.TH CURLINFO_COOKIELIST 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_COOKIELIST \- get all known cookies +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_COOKIELIST, + struct curl_slist **cookies); +.fi +.SH DESCRIPTION +Pass a pointer to a \(aqstruct curl_slist *\(aq to receive a linked\-list of all +cookies curl knows (expired ones, too). Do not forget to call +\fIcurl_slist_free_all(3)\fP on the list after it has been used. If there are no +cookies (cookies for the handle have not been enabled or simply none have been +received) the \(aqstruct curl_slist *\(aq is made a NULL pointer. + +Since 7.43.0 cookies that were imported in the Set\-Cookie format without a +domain name are not exported by this option. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable the cookie engine */ + curl_easy_setopt(curl, CURLOPT_COOKIEFILE, ""); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract all known cookies */ + struct curl_slist *cookies = NULL; + res = curl_easy_getinfo(curl, CURLINFO_COOKIELIST, &cookies); + if(!res && cookies) { + /* a linked list of cookies in cookie file format */ + struct curl_slist *each = cookies; + while(each) { + printf("%s\\n", each->data); + each = each->next; + } + /* we must free these cookies when we are done */ + curl_slist_free_all(cookies); + } + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.14.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_COOKIELIST (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_EFFECTIVE_METHOD.3 b/3rdparty/curl/share/man/man3/CURLINFO_EFFECTIVE_METHOD.3 new file mode 100644 index 0000000..3bd3af2 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_EFFECTIVE_METHOD.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_EFFECTIVE_METHOD.md +.TH CURLINFO_EFFECTIVE_METHOD 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_EFFECTIVE_METHOD \- get the last used HTTP method +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_EFFECTIVE_METHOD, + char **methodp); +.fi +.SH DESCRIPTION +Pass in a pointer to a char pointer and get the last used effective HTTP +method. + +In cases when you have asked libcurl to follow redirects, the method may not be +the same method the first request would use. + +The \fBmethodp\fP pointer is NULL or points to private memory. You MUST NOT +free \- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the +corresponding CURL handle. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data"); + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *method = NULL; + curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_METHOD, &method); + if(method) + printf("Redirected to method: %s\\n", method); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.72.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CUSTOMREQUEST (3), +.BR CURLOPT_FOLLOWLOCATION (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_EFFECTIVE_URL.3 b/3rdparty/curl/share/man/man3/CURLINFO_EFFECTIVE_URL.3 new file mode 100644 index 0000000..3c2a974 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_EFFECTIVE_URL.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_EFFECTIVE_URL.md +.TH CURLINFO_EFFECTIVE_URL 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_EFFECTIVE_URL \- get the last used URL +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_EFFECTIVE_URL, char **urlp); +.fi +.SH DESCRIPTION +Pass in a pointer to a char pointer and get the last used effective URL. + +In cases when you have asked libcurl to follow redirects, it may not be the same +value you set with \fICURLOPT_URL(3)\fP. + +The \fBurlp\fP pointer is NULL or points to private memory. You MUST NOT free +- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *url = NULL; + curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_URL, &url); + if(url) + printf("Redirect to: %s\\n", url); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FOLLOWLOCATION (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_FILETIME.3 b/3rdparty/curl/share/man/man3/CURLINFO_FILETIME.3 new file mode 100644 index 0000000..c0849b7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_FILETIME.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_FILETIME.md +.TH CURLINFO_FILETIME 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_FILETIME \- get the remote time of the retrieved document +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FILETIME, long *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the remote time of the retrieved document +in number of seconds since January 1 1970 in the GMT/UTC time zone. If you get +-1, it can be because of many reasons (it might be unknown, the server might +hide it or the server does not support the command that tells document time +etc) and the time of the document is unknown. + +You must ask libcurl to collect this information before the transfer is made, +by using the \fICURLOPT_FILETIME(3)\fP option or you unconditionally get a \-1 back. + +Consider \fICURLINFO_FILETIME_T(3)\fP instead to be able to extract dates beyond the +year 2038 on systems using 32\-bit longs (Windows). +.SH PROTOCOLS +This functionality affects ftp, http and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* Ask for filetime */ + curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + long filetime = 0; + res = curl_easy_getinfo(curl, CURLINFO_FILETIME, &filetime); + if((CURLE_OK == res) && (filetime >= 0)) { + time_t file_time = (time_t)filetime; + printf("filetime: %s", ctime(&file_time)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.5 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FILETIME (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_FILETIME_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_FILETIME_T.3 new file mode 100644 index 0000000..5403a04 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_FILETIME_T.3 @@ -0,0 +1,57 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_FILETIME_T.md +.TH CURLINFO_FILETIME_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_FILETIME_T \- get the remote time of the retrieved document +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FILETIME_T, + curl_off_t *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t to receive the remote time of the retrieved +document in number of seconds since January 1 1970 in the GMT/UTC time zone. +If you get \-1, it can be because of many reasons (it might be unknown, the +server might hide it or the server does not support the command that tells +document time etc) and the time of the document is unknown. + +You must ask libcurl to collect this information before the transfer is made, +by using the \fICURLOPT_FILETIME(3)\fP option or you unconditionally get a \-1 back. + +This option is an alternative to \fICURLINFO_FILETIME(3)\fP to allow systems with 32 +bit long variables to extract dates outside of the 32\-bit timestamp range. +.SH PROTOCOLS +This functionality affects ftp, http and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* Ask for filetime */ + curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + curl_off_t filetime; + res = curl_easy_getinfo(curl, CURLINFO_FILETIME_T, &filetime); + if((CURLE_OK == res) && (filetime >= 0)) { + time_t file_time = (time_t)filetime; + printf("filetime: %s", ctime(&file_time)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.59.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FILETIME (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_FTP_ENTRY_PATH.3 b/3rdparty/curl/share/man/man3/CURLINFO_FTP_ENTRY_PATH.3 new file mode 100644 index 0000000..a539ba0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_FTP_ENTRY_PATH.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_FTP_ENTRY_PATH.md +.TH CURLINFO_FTP_ENTRY_PATH 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_FTP_ENTRY_PATH \- get entry path in FTP server +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FTP_ENTRY_PATH, char **path); +.fi +.SH DESCRIPTION +Pass a pointer to a char pointer to receive a pointer to a string holding the +path of the entry path. That is the initial path libcurl ended up in when +logging on to the remote FTP server. This stores a NULL as pointer if +something is wrong. + +The \fBpath\fP pointer is NULL or points to private memory. You MUST NOT free +- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract the entry path */ + char *ep = NULL; + res = curl_easy_getinfo(curl, CURLINFO_FTP_ENTRY_PATH, &ep); + if(!res && ep) { + printf("Entry path was: %s\\n", ep); + } + } + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +Works for SFTP since 7.21.4 +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_HEADER_SIZE.3 b/3rdparty/curl/share/man/man3/CURLINFO_HEADER_SIZE.3 new file mode 100644 index 0000000..2f53ad1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_HEADER_SIZE.3 @@ -0,0 +1,46 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_HEADER_SIZE.md +.TH CURLINFO_HEADER_SIZE 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_HEADER_SIZE \- get size of retrieved headers +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HEADER_SIZE, long *sizep); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the total size of all the headers +received. Measured in number of bytes. + +The total includes the size of any received headers suppressed by +\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long size; + res = curl_easy_getinfo(curl, CURLINFO_HEADER_SIZE, &size); + if(!res) + printf("Header size: %ld bytes\\n", size); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.4.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_REQUEST_SIZE (3), +.BR CURLINFO_SIZE_DOWNLOAD (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_HTTPAUTH_AVAIL.3 b/3rdparty/curl/share/man/man3/CURLINFO_HTTPAUTH_AVAIL.3 new file mode 100644 index 0000000..e92f3d3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_HTTPAUTH_AVAIL.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_HTTPAUTH_AVAIL.md +.TH CURLINFO_HTTPAUTH_AVAIL 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_HTTPAUTH_AVAIL \- get available HTTP authentication methods +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTPAUTH_AVAIL, long *authp); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive a bitmask indicating the authentication +method(s) available according to the previous response. The meaning of the +bits is explained in the \fICURLOPT_HTTPAUTH(3)\fP option for \fIcurl_easy_setopt(3)\fP. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract the available authentication types */ + long auth; + res = curl_easy_getinfo(curl, CURLINFO_HTTPAUTH_AVAIL, &auth); + if(!res) { + if(!auth) + printf("No auth available, perhaps no 401?\\n"); + else { + printf("%s%s%s%s\\n", + auth & CURLAUTH_BASIC ? "Basic ":"", + auth & CURLAUTH_DIGEST ? "Digest ":"", + auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"", + auth % CURLAUTH_NTLM ? "NTLM ":""); + } + } + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.8 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_PROXYAUTH_AVAIL (3), +.BR CURLOPT_HTTPAUTH (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_HTTP_CONNECTCODE.3 b/3rdparty/curl/share/man/man3/CURLINFO_HTTP_CONNECTCODE.3 new file mode 100644 index 0000000..c630921 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_HTTP_CONNECTCODE.3 @@ -0,0 +1,46 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_HTTP_CONNECTCODE.md +.TH CURLINFO_HTTP_CONNECTCODE 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_HTTP_CONNECTCODE \- get the CONNECT response code +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_CONNECTCODE, long *p); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the last received HTTP proxy response code +to a CONNECT request. The returned value is zero if no such response code was +available. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* typically CONNECT is used to do HTTPS over HTTP proxies */ + curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long code; + res = curl_easy_getinfo(curl, CURLINFO_HTTP_CONNECTCODE, &code); + if(!res && code) + printf("The CONNECT response code: %03ld\\n", code); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.7 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RESPONSE_CODE (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_HTTP_VERSION.3 b/3rdparty/curl/share/man/man3/CURLINFO_HTTP_VERSION.3 new file mode 100644 index 0000000..e2617ae --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_HTTP_VERSION.3 @@ -0,0 +1,42 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_HTTP_VERSION.md +.TH CURLINFO_HTTP_VERSION 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_HTTP_VERSION \- get the http version used in the connection +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_VERSION, long *p); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the version used in the last http +connection done using this handle. The returned value is +CURL_HTTP_VERSION_1_0, CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, +CURL_HTTP_VERSION_3 or 0 if the version cannot be determined. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long http_version; + curl_easy_getinfo(curl, CURLINFO_HTTP_VERSION, &http_version); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.50.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RESPONSE_CODE (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_LASTSOCKET.3 b/3rdparty/curl/share/man/man3/CURLINFO_LASTSOCKET.3 new file mode 100644 index 0000000..0accd5a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_LASTSOCKET.3 @@ -0,0 +1,63 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_LASTSOCKET.md +.TH CURLINFO_LASTSOCKET 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_LASTSOCKET \- get the last socket used +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LASTSOCKET, long *socket); +.fi +.SH DESCRIPTION +Deprecated since 7.45.0. Use \fICURLINFO_ACTIVESOCKET(3)\fP instead. + +Pass a pointer to a long to receive the last socket used by this curl +session. If the socket is no longer valid, \-1 is returned. When you finish +working with the socket, you must call \fIcurl_easy_cleanup(3)\fP as usual and +let libcurl close the socket and cleanup other resources associated with the +handle. This is typically used in combination with +\fICURLOPT_CONNECT_ONLY(3)\fP. + +NOTE: this API is deprecated since it is not working on win64 where the SOCKET +type is 64 bits large while its \(aqlong\(aq is 32 bits. Use the +\fICURLINFO_ACTIVESOCKET(3)\fP instead, if possible. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + long sockfd; /* does not work on win64! */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Do not do the transfer - only connect to host */ + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); + res = curl_easy_perform(curl); + if(res != CURLE_OK) { + printf("Error: %s\\n", curl_easy_strerror(res)); + curl_easy_cleanup(curl); + return 1; + } + + /* Extract the socket from the curl handle */ + res = curl_easy_getinfo(curl, CURLINFO_LASTSOCKET, &sockfd); + if(!res && sockfd != -1) { + /* operate on sockfd */ + } + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.15.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_ACTIVESOCKET (3), +.BR CURLOPT_CONNECT_ONLY (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_LOCAL_IP.3 b/3rdparty/curl/share/man/man3/CURLINFO_LOCAL_IP.3 new file mode 100644 index 0000000..565713f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_LOCAL_IP.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_LOCAL_IP.md +.TH CURLINFO_LOCAL_IP 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_LOCAL_IP \- get local IP address of last connection +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LOCAL_IP, char **ip); +.fi +.SH DESCRIPTION +Pass a pointer to a char pointer to receive the pointer to a null\-terminated +string holding the IP address of the local end of most recent connection done +with this \fBcurl\fP handle. This string may be IPv6 when that is enabled. Note +that you get a pointer to a memory area that is reused at next request so you +need to copy the string if you want to keep the information. + +The \fBip\fP pointer is NULL or points to private memory. You MUST NOT free \- it +gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding CURL +handle. +.SH PROTOCOLS +This functionality affects quic and tcp +.SH EXAMPLE +.nf +int main(void) +{ + char *ip; + CURLcode res; + CURL *curl = curl_easy_init(); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the transfer */ + res = curl_easy_perform(curl); + /* Check for errors */ + if((res == CURLE_OK) && + !curl_easy_getinfo(curl, CURLINFO_LOCAL_IP, &ip) && ip) { + printf("Local IP: %s\\n", ip); + } + + /* always cleanup */ + curl_easy_cleanup(curl); +} +.fi +.SH AVAILABILITY +Added in curl 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_LOCAL_PORT (3), +.BR CURLINFO_PRIMARY_IP (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_LOCAL_PORT.3 b/3rdparty/curl/share/man/man3/CURLINFO_LOCAL_PORT.3 new file mode 100644 index 0000000..1177a71 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_LOCAL_PORT.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_LOCAL_PORT.md +.TH CURLINFO_LOCAL_PORT 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_LOCAL_PORT \- get the latest local port number +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LOCAL_PORT, long *portp); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the local port number of the most recent +connection done with this \fBcurl\fP handle. + +If the connection was done using QUIC, the port number is a UDP port number, +otherwise it is a TCP port number. +.SH PROTOCOLS +This functionality affects quic and tcp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl; + CURLcode res; + + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + + if(CURLE_OK == res) { + long port; + res = curl_easy_getinfo(curl, CURLINFO_LOCAL_PORT, &port); + + if(CURLE_OK == res) { + printf("We used local port: %ld\\n", port); + } + } + curl_easy_cleanup(curl); + } + return 0; +} +.fi +.SH AVAILABILITY +Added in curl 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_LOCAL_IP (3), +.BR CURLINFO_PRIMARY_PORT (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_NAMELOOKUP_TIME.3 b/3rdparty/curl/share/man/man3/CURLINFO_NAMELOOKUP_TIME.3 new file mode 100644 index 0000000..0a0ae26 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_NAMELOOKUP_TIME.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_NAMELOOKUP_TIME.md +.TH CURLINFO_NAMELOOKUP_TIME 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_NAMELOOKUP_TIME \- get the name lookup time +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NAMELOOKUP_TIME, + double *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the total time in seconds from the start +until the name resolving was completed. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double namelookup; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_NAMELOOKUP_TIME, &namelookup); + if(CURLE_OK == res) { + printf("Time: %.1f", namelookup); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.4.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_NAMELOOKUP_TIME_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_NAMELOOKUP_TIME_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_NAMELOOKUP_TIME_T.3 new file mode 100644 index 0000000..45bfa8f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_NAMELOOKUP_TIME_T.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_NAMELOOKUP_TIME_T.md +.TH CURLINFO_NAMELOOKUP_TIME_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_NAMELOOKUP_TIME_T \- get the name lookup time in microseconds +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NAMELOOKUP_TIME_T, + curl_off_t *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t to receive the total time in microseconds +from the start until the name resolving was completed. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t namelookup; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_NAMELOOKUP_TIME_T, &namelookup); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", namelookup / 1000000, + (long)(namelookup % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.61.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_NAMELOOKUP_TIME (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_NUM_CONNECTS.3 b/3rdparty/curl/share/man/man3/CURLINFO_NUM_CONNECTS.3 new file mode 100644 index 0000000..f1c65e8 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_NUM_CONNECTS.3 @@ -0,0 +1,46 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_NUM_CONNECTS.md +.TH CURLINFO_NUM_CONNECTS 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_NUM_CONNECTS \- get number of created connections +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NUM_CONNECTS, long *nump); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive how many new connections libcurl had to +create to achieve the previous transfer (only the successful connects are +counted). Combined with \fICURLINFO_REDIRECT_COUNT(3)\fP you are able to know how +many times libcurl successfully reused existing connection(s) or not. See the +connection options of \fIcurl_easy_setopt(3)\fP to see how libcurl tries to make +persistent connections to save time. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long connects; + res = curl_easy_getinfo(curl, CURLINFO_NUM_CONNECTS, &connects); + if(!res) + printf("It needed %ld connects\\n", connects); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.12.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_OS_ERRNO.3 b/3rdparty/curl/share/man/man3/CURLINFO_OS_ERRNO.3 new file mode 100644 index 0000000..eb054f1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_OS_ERRNO.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_OS_ERRNO.md +.TH CURLINFO_OS_ERRNO 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_OS_ERRNO \- get errno number from last connect failure +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_OS_ERRNO, long *errnop); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the errno variable from a connect failure. +Note that the value is only set on failure, it is not reset upon a successful +operation. The number is OS and system specific. + +libcurl network\-related errors that may have a saved errno are: +CURLE_COULDNT_CONNECT, CURLE_FAILED_INIT, CURLE_INTERFACE_FAILED, +CURLE_OPERATION_TIMEDOUT, CURLE_RECV_ERROR, CURLE_SEND_ERROR. + +Since 8.8.0 libcurl clears the easy handle\(aqs saved errno before performing the +transfer. Prior versions did not clear the saved errno, which means if a saved +errno is retrieved it could be from a previous transfer on the same handle. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res != CURLE_OK) { + long error; + res = curl_easy_getinfo(curl, CURLINFO_OS_ERRNO, &error); + if(!res && error) { + printf("Errno: %ld\\n", error); + } + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.12.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_POSTTRANSFER_TIME_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_POSTTRANSFER_TIME_T.3 new file mode 100644 index 0000000..12a7d58 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_POSTTRANSFER_TIME_T.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_POSTTRANSFER_TIME_T.md +.TH CURLINFO_POSTTRANSFER_TIME_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_POSTTRANSFER_TIME_T \- get the time until the last byte is sent +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_POSTTRANSFER_TIME_T, + curl_off_t *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t to receive the time, in microseconds, +it took from the start until the last byte is sent by libcurl. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + curl_off_t posttransfer; + res = curl_easy_getinfo(curl, CURLINFO_POSTTRANSFER_TIME_T, + &posttransfer); + if(CURLE_OK == res) { + printf("Request sent after: %" CURL_FORMAT_CURL_OFF_T ".%06ld us", + posttransfer / 1000000, (long)(posttransfer % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 8.10.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_PRETRANSFER_TIME_T (3), +.BR CURLOPT_TIMEOUT (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_PRETRANSFER_TIME.3 b/3rdparty/curl/share/man/man3/CURLINFO_PRETRANSFER_TIME.3 new file mode 100644 index 0000000..1d677d1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_PRETRANSFER_TIME.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_PRETRANSFER_TIME.md +.TH CURLINFO_PRETRANSFER_TIME 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_PRETRANSFER_TIME \- get the time until the file transfer start +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRETRANSFER_TIME, + double *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the time, in seconds, it took from the +start until the file transfer is just about to begin. + +This time\-stamp includes all pre\-transfer commands and negotiations that are +specific to the particular protocol(s) involved. It includes the sending of +the protocol\-specific instructions that trigger a transfer. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double pretransfer; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_PRETRANSFER_TIME, &pretransfer); + if(CURLE_OK == res) { + printf("Time: %.1f", pretransfer); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.4.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CONNECT_TIME_T (3), +.BR CURLINFO_PRETRANSFER_TIME_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_PRETRANSFER_TIME_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_PRETRANSFER_TIME_T.3 new file mode 100644 index 0000000..c78df32 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_PRETRANSFER_TIME_T.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_PRETRANSFER_TIME_T.md +.TH CURLINFO_PRETRANSFER_TIME_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_PRETRANSFER_TIME_T \- get the time until the file transfer start +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRETRANSFER_TIME_T, + curl_off_t *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t to receive the time, in microseconds, it took +from the start until the file transfer is just about to begin. + +This time\-stamp includes all pre\-transfer commands and negotiations that are +specific to the particular protocol(s) involved. It includes the sending of +the protocol\-specific instructions that trigger a transfer. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t pretransfer; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_PRETRANSFER_TIME_T, &pretransfer); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld\\n", + pretransfer / 1000000, + (long)(pretransfer % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.61.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CONNECT_TIME (3), +.BR CURLINFO_PRETRANSFER_TIME_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_PRIMARY_IP.3 b/3rdparty/curl/share/man/man3/CURLINFO_PRIMARY_IP.3 new file mode 100644 index 0000000..3669573 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_PRIMARY_IP.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_PRIMARY_IP.md +.TH CURLINFO_PRIMARY_IP 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_PRIMARY_IP \- get IP address of last connection +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIMARY_IP, char **ip); +.fi +.SH DESCRIPTION +Pass a pointer to a char pointer to receive the pointer to a null\-terminated +string holding the IP address of the most recent connection done with this +\fBcurl\fP handle. This string may be IPv6 when that is enabled. Note that you +get a pointer to a memory area that is reused at next request so you need to +copy the string if you want to keep the information. + +The \fBip\fP pointer is NULL or points to private memory. You MUST NOT free \- +it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + char *ip; + CURLcode res; + CURL *curl = curl_easy_init(); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the transfer */ + res = curl_easy_perform(curl); + /* Check for errors */ + if((res == CURLE_OK) && + !curl_easy_getinfo(curl, CURLINFO_PRIMARY_IP, &ip) && ip) { + printf("IP: %s\\n", ip); + } + + /* always cleanup */ + curl_easy_cleanup(curl); +} +.fi +.SH AVAILABILITY +Added in curl 7.19.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_LOCAL_IP (3), +.BR CURLINFO_LOCAL_PORT (3), +.BR CURLINFO_PRIMARY_PORT (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_PRIMARY_PORT.3 b/3rdparty/curl/share/man/man3/CURLINFO_PRIMARY_PORT.3 new file mode 100644 index 0000000..9be7163 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_PRIMARY_PORT.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_PRIMARY_PORT.md +.TH CURLINFO_PRIMARY_PORT 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_PRIMARY_PORT \- get the latest destination port number +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIMARY_PORT, long *portp); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the destination port of the most recent +connection done with this \fBcurl\fP handle. + +This is the destination port of the actual TCP or UDP connection libcurl used. +If a proxy was used for the most recent transfer, this is the port number of +the proxy, if no proxy was used it is the port number of the most recently +accessed URL. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long port; + res = curl_easy_getinfo(curl, CURLINFO_PRIMARY_PORT, &port); + if(!res) + printf("Connected to remote port: %ld\\n", port); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_LOCAL_PORT (3), +.BR CURLINFO_PRIMARY_IP (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_PRIVATE.3 b/3rdparty/curl/share/man/man3/CURLINFO_PRIVATE.3 new file mode 100644 index 0000000..f42a358 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_PRIVATE.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_PRIVATE.md +.TH CURLINFO_PRIVATE 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_PRIVATE \- get the private pointer +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIVATE, char **private); +.fi +.SH DESCRIPTION +Pass a pointer to a char pointer to receive the pointer to the private data +associated with the curl handle (set with the \fICURLOPT_PRIVATE(3)\fP). +Please note that for internal reasons, the value is returned as a char +pointer, although effectively being a \(aqvoid *\(aq. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + void *pointer = (void *)0x2345454; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* set the private pointer */ + curl_easy_setopt(curl, CURLOPT_PRIVATE, pointer); + res = curl_easy_perform(curl); + + /* extract the private pointer again */ + res = curl_easy_getinfo(curl, CURLINFO_PRIVATE, &pointer); + + if(res) + printf("error: %s\\n", curl_easy_strerror(res)); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_PRIVATE (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_PROTOCOL.3 b/3rdparty/curl/share/man/man3/CURLINFO_PROTOCOL.3 new file mode 100644 index 0000000..e60a37a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_PROTOCOL.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_PROTOCOL.md +.TH CURLINFO_PROTOCOL 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_PROTOCOL \- get the protocol used in the connection +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROTOCOL, long *p); +.fi +.SH DESCRIPTION +This option is deprecated. We strongly recommend using +\fICURLINFO_SCHEME(3)\fP instead, because this option cannot return all +possible protocols! + +Pass a pointer to a long to receive the version used in the last http +connection. The returned value is set to one of the CURLPROTO_* values: + +.nf +CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_FTP, CURLPROTO_FTPS, +CURLPROTO_GOPHER, CURLPROTO_HTTP, CURLPROTO_HTTPS, CURLPROTO_IMAP, +CURLPROTO_IMAPS, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_POP3, +CURLPROTO_POP3S, CURLPROTO_RTMP, CURLPROTO_RTMPE, CURLPROTO_RTMPS, +CURLPROTO_RTMPT, CURLPROTO_RTMPTE, CURLPROTO_RTMPTS, CURLPROTO_RTSP, +CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_SMB, CURLPROTO_SMBS, CURLPROTO_SMTP, +CURLPROTO_SMTPS, CURLPROTO_TELNET, CURLPROTO_TFTP, CURLPROTO_MQTT +.fi +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long protocol; + curl_easy_getinfo(curl, CURLINFO_PROTOCOL, &protocol); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH DEPRECATED +Deprecated since 7.85.0. +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RESPONSE_CODE (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_PROXYAUTH_AVAIL.3 b/3rdparty/curl/share/man/man3/CURLINFO_PROXYAUTH_AVAIL.3 new file mode 100644 index 0000000..84c7886 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_PROXYAUTH_AVAIL.3 @@ -0,0 +1,57 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_PROXYAUTH_AVAIL.md +.TH CURLINFO_PROXYAUTH_AVAIL 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_PROXYAUTH_AVAIL \- get available HTTP proxy authentication methods +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXYAUTH_AVAIL, + long *authp); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive a bitmask indicating the authentication +method(s) available according to the previous response. The meaning of the +bits is explained in the \fICURLOPT_PROXYAUTH(3)\fP option for \fIcurl_easy_setopt(3)\fP. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80"); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract the available proxy authentication types */ + long auth; + res = curl_easy_getinfo(curl, CURLINFO_PROXYAUTH_AVAIL, &auth); + if(!res) { + if(!auth) + printf("No proxy auth available, perhaps no 407?\\n"); + else { + printf("%s%s%s%s\\n", + auth & CURLAUTH_BASIC ? "Basic ":"", + auth & CURLAUTH_DIGEST ? "Digest ":"", + auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"", + auth % CURLAUTH_NTLM ? "NTLM ":""); + } + } + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.8 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_HTTPAUTH_AVAIL (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_PROXY_ERROR.3 b/3rdparty/curl/share/man/man3/CURLINFO_PROXY_ERROR.3 new file mode 100644 index 0000000..a150dd0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_PROXY_ERROR.3 @@ -0,0 +1,86 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_PROXY_ERROR.md +.TH CURLINFO_PROXY_ERROR 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_PROXY_ERROR \- get the detailed (SOCKS) proxy error +.SH SYNOPSIS +.nf +#include + +typedef enum { + CURLPX_OK, + CURLPX_BAD_ADDRESS_TYPE, + CURLPX_BAD_VERSION, + CURLPX_CLOSED, + CURLPX_GSSAPI, + CURLPX_GSSAPI_PERMSG, + CURLPX_GSSAPI_PROTECTION, + CURLPX_IDENTD, + CURLPX_IDENTD_DIFFER, + CURLPX_LONG_HOSTNAME, + CURLPX_LONG_PASSWD, + CURLPX_LONG_USER, + CURLPX_NO_AUTH, + CURLPX_RECV_ADDRESS, + CURLPX_RECV_AUTH, + CURLPX_RECV_CONNECT, + CURLPX_RECV_REQACK, + CURLPX_REPLY_ADDRESS_TYPE_NOT_SUPPORTED, + CURLPX_REPLY_COMMAND_NOT_SUPPORTED, + CURLPX_REPLY_CONNECTION_REFUSED, + CURLPX_REPLY_GENERAL_SERVER_FAILURE, + CURLPX_REPLY_HOST_UNREACHABLE, + CURLPX_REPLY_NETWORK_UNREACHABLE, + CURLPX_REPLY_NOT_ALLOWED, + CURLPX_REPLY_TTL_EXPIRED, + CURLPX_REPLY_UNASSIGNED, + CURLPX_REQUEST_FAILED, + CURLPX_RESOLVE_HOST, + CURLPX_SEND_AUTH, + CURLPX_SEND_CONNECT, + CURLPX_SEND_REQUEST, + CURLPX_UNKNOWN_FAIL, + CURLPX_UNKNOWN_MODE, + CURLPX_USER_REJECTED, + CURLPX_LAST /* never use */ +} CURLproxycode; + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXY_ERROR, long *detail); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive a detailed error code when the most recent +transfer returned a \fBCURLE_PROXY\fP error. That error code matches the +\fBCURLproxycode\fP set. + +The error code is zero (\fBCURLPX_OK\fP) if no response code was available. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://127.0.0.1"); + res = curl_easy_perform(curl); + if(res == CURLE_PROXY) { + long proxycode; + res = curl_easy_getinfo(curl, CURLINFO_PROXY_ERROR, &proxycode); + if(!res && proxycode) + printf("The detailed proxy error: %ld\\n", proxycode); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.73.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RESPONSE_CODE (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3), +.BR libcurl-errors (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_PROXY_SSL_VERIFYRESULT.3 b/3rdparty/curl/share/man/man3/CURLINFO_PROXY_SSL_VERIFYRESULT.3 new file mode 100644 index 0000000..fef07f9 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_PROXY_SSL_VERIFYRESULT.3 @@ -0,0 +1,59 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_PROXY_SSL_VERIFYRESULT.md +.TH CURLINFO_PROXY_SSL_VERIFYRESULT 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_PROXY_SSL_VERIFYRESULT \- get the result of the proxy certificate verification +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXY_SSL_VERIFYRESULT, + long *result); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the result of the certificate verification +that was requested (using the \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP +option. This is only used for HTTPS proxies. + +0 is a positive result. Non\-zero is an error. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + long verifyresult; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443"); + + res = curl_easy_perform(curl); + if(res) { + printf("error: %s\\n", curl_easy_strerror(res)); + curl_easy_cleanup(curl); + return 1; + } + + res = curl_easy_getinfo(curl, CURLINFO_PROXY_SSL_VERIFYRESULT, + &verifyresult); + if(!res) { + printf("The peer verification said %s\\n", + (verifyresult ? "bad" : "fine")); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_SSL_VERIFYRESULT (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_QUEUE_TIME_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_QUEUE_TIME_T.3 new file mode 100644 index 0000000..2c62d61 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_QUEUE_TIME_T.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_QUEUE_TIME_T.md +.TH CURLINFO_QUEUE_TIME_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_QUEUE_TIME_T \- time this transfer was queued +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_QUEUE_TIME_T, + curl_off_t *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t to receive the time, in microseconds, this +transfer was held in a waiting queue before it started "for real". A transfer +might be put in a queue if after getting started, it cannot create a new +connection etc due to set conditions and limits imposed by the application. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t queue; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_QUEUE_TIME_T, &queue); + if(CURLE_OK == res) { + printf("Queued: %" CURL_FORMAT_CURL_OFF_T ".%06ld us", queue / 1000000, + (long)(queue % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 8.6.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_STARTTRANSFER_TIME_T (3), +.BR CURLOPT_TIMEOUT (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_COUNT.3 b/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_COUNT.3 new file mode 100644 index 0000000..f6423ce --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_COUNT.3 @@ -0,0 +1,43 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_REDIRECT_COUNT.md +.TH CURLINFO_REDIRECT_COUNT 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_REDIRECT_COUNT \- get the number of redirects +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_COUNT, + long *countp); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the total number of redirections that were +actually followed. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long redirects; + curl_easy_getinfo(curl, CURLINFO_REDIRECT_COUNT, &redirects); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.7 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_REDIRECT_URL (3), +.BR CURLOPT_FOLLOWLOCATION (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_TIME.3 b/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_TIME.3 new file mode 100644 index 0000000..61d60dd --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_TIME.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_REDIRECT_TIME.md +.TH CURLINFO_REDIRECT_TIME 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_REDIRECT_TIME \- get the time for all redirection steps +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_TIME, + double *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the total time, in seconds, it took for +all redirection steps include name lookup, connect, pretransfer and transfer +before final transaction was started. \fICURLINFO_REDIRECT_TIME(3)\fP contains +the complete execution time for multiple redirections. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double redirect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_REDIRECT_TIME, &redirect); + if(CURLE_OK == res) { + printf("Time: %.1f", redirect); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.7 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_REDIRECT_COUNT (3), +.BR CURLINFO_REDIRECT_TIME_T (3), +.BR CURLINFO_REDIRECT_URL (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_TIME_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_TIME_T.3 new file mode 100644 index 0000000..c28dd1d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_TIME_T.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_REDIRECT_TIME_T.md +.TH CURLINFO_REDIRECT_TIME_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_REDIRECT_TIME_T \- get the time for all redirection steps +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_TIME_T, + curl_off_t *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t to receive the total time, in microseconds, it +took for all redirection steps include name lookup, connect, pretransfer and +transfer before final transaction was started. +\fICURLINFO_REDIRECT_TIME_T(3)\fP holds the complete execution time for +multiple redirections. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t redirect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_REDIRECT_TIME_T, &redirect); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", redirect / 1000000, + (long)(redirect % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.61.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_REDIRECT_COUNT (3), +.BR CURLINFO_REDIRECT_TIME (3), +.BR CURLINFO_REDIRECT_URL (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_URL.3 b/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_URL.3 new file mode 100644 index 0000000..cecc0bd --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_REDIRECT_URL.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_REDIRECT_URL.md +.TH CURLINFO_REDIRECT_URL 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_REDIRECT_URL \- get the URL a redirect would go to +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_URL, char **urlp); +.fi +.SH DESCRIPTION +Pass a pointer to a char pointer to receive the URL a redirect \fIwould\fP take +you to if you would enable \fICURLOPT_FOLLOWLOCATION(3)\fP. This can come handy if +you think using the built\-in libcurl redirect logic is not good enough for you +but you would still prefer to avoid implementing all the magic of figuring out +the new URL. + +This URL is also set if the \fICURLOPT_MAXREDIRS(3)\fP limit prevented a redirect to +happen (since 7.54.1). +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *url = NULL; + curl_easy_getinfo(curl, CURLINFO_REDIRECT_URL, &url); + if(url) + printf("Redirect to: %s\\n", url); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.18.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_REDIRECT_COUNT (3), +.BR CURLINFO_REDIRECT_TIME_T (3), +.BR CURLOPT_FOLLOWLOCATION (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_REFERER.3 b/3rdparty/curl/share/man/man3/CURLINFO_REFERER.3 new file mode 100644 index 0000000..64d4d2a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_REFERER.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_REFERER.md +.TH CURLINFO_REFERER 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_REFERER \- get the used referrer request header +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REFERER, char **hdrp); +.fi +.SH DESCRIPTION +Pass in a pointer to a char pointer and get the referrer header used in the +most recent request. + +The \fBhdrp\fP pointer is NULL or points to private memory you MUST NOT free \- +it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_REFERER, "https://example.org/referrer"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *hdr = NULL; + curl_easy_getinfo(curl, CURLINFO_REFERER, &hdr); + if(hdr) + printf("Referrer header: %s\\n", hdr); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.76.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_REFERER (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_header (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_REQUEST_SIZE.3 b/3rdparty/curl/share/man/man3/CURLINFO_REQUEST_SIZE.3 new file mode 100644 index 0000000..72cb612 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_REQUEST_SIZE.3 @@ -0,0 +1,44 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_REQUEST_SIZE.md +.TH CURLINFO_REQUEST_SIZE 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_REQUEST_SIZE \- get size of sent request +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REQUEST_SIZE, long *sizep); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the total size of the issued +requests. This is so far only for HTTP requests. Note that this may be more +than one request if \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long req; + res = curl_easy_getinfo(curl, CURLINFO_REQUEST_SIZE, &req); + if(!res) + printf("Request size: %ld bytes\\n", req); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.4.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_HEADER_SIZE (3), +.BR CURLINFO_SIZE_DOWNLOAD_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_RESPONSE_CODE.3 b/3rdparty/curl/share/man/man3/CURLINFO_RESPONSE_CODE.3 new file mode 100644 index 0000000..e1189ec --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_RESPONSE_CODE.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_RESPONSE_CODE.md +.TH CURLINFO_RESPONSE_CODE 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_RESPONSE_CODE \- get the last response code +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RESPONSE_CODE, long *codep); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the last received HTTP, FTP, SMTP or LDAP +(OpenLDAP only) response code. This option was previously known as +CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. The stored value is zero if +no server response code has been received. + +Note that a proxy\(aqs CONNECT response should be read with +\fICURLINFO_HTTP_CONNECTCODE(3)\fP and not this. +.SH PROTOCOLS +This functionality affects ftp, http, ldap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long response_code; + curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &response_code); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH NOTES +The former name, CURLINFO_HTTP_CODE, was added in 7.4.1. Support for SMTP +responses added in 7.25.0, for OpenLDAP in 7.81.0. +.SH AVAILABILITY +Added in curl 7.10.8 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_HTTP_CONNECTCODE (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_RETRY_AFTER.3 b/3rdparty/curl/share/man/man3/CURLINFO_RETRY_AFTER.3 new file mode 100644 index 0000000..a5509f0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_RETRY_AFTER.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_RETRY_AFTER.md +.TH CURLINFO_RETRY_AFTER 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_RETRY_AFTER \- returns the Retry\-After retry delay +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RETRY_AFTER, + curl_off_t *retry); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t variable to receive the number of seconds the +HTTP server suggests the client should wait until the next request is +issued. The information from the "Retry\-After:" header. + +While the HTTP header might contain a fixed date string, the +\fICURLINFO_RETRY_AFTER(3)\fP always returns the number of seconds to wait \- +or zero if there was no header or the header could not be parsed. +.SH DEFAULT +Zero if there was no header. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + curl_off_t wait = 0; + curl_easy_getinfo(curl, CURLINFO_RETRY_AFTER, &wait); + if(wait) + printf("Wait for %" CURL_FORMAT_CURL_OFF_T " seconds\\n", wait); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.66.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HEADERFUNCTION (3), +.BR CURLOPT_STDERR (3), +.BR curl_easy_header (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_RTSP_CLIENT_CSEQ.3 b/3rdparty/curl/share/man/man3/CURLINFO_RTSP_CLIENT_CSEQ.3 new file mode 100644 index 0000000..eb1f7af --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_RTSP_CLIENT_CSEQ.3 @@ -0,0 +1,42 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_RTSP_CLIENT_CSEQ.md +.TH CURLINFO_RTSP_CLIENT_CSEQ 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_RTSP_CLIENT_CSEQ \- get the next RTSP client CSeq +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_CLIENT_CSEQ, + long *cseq); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the next CSeq that is expected to be used +by the application. +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long cseq; + curl_easy_getinfo(curl, CURLINFO_RTSP_CLIENT_CSEQ, &cseq); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RTSP_CSEQ_RECV (3), +.BR CURLINFO_RTSP_SERVER_CSEQ (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_RTSP_CSEQ_RECV.3 b/3rdparty/curl/share/man/man3/CURLINFO_RTSP_CSEQ_RECV.3 new file mode 100644 index 0000000..f04e993 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_RTSP_CSEQ_RECV.3 @@ -0,0 +1,42 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_RTSP_CSEQ_RECV.md +.TH CURLINFO_RTSP_CSEQ_RECV 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_RTSP_CSEQ_RECV \- get the recently received CSeq +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_CSEQ_RECV, long *cseq); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the most recently received CSeq from the +server. If your application encounters a \fICURLE_RTSP_CSEQ_ERROR\fP then you +may wish to troubleshoot and/or fix the CSeq mismatch by peeking at this +value. +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long cseq; + curl_easy_getinfo(curl, CURLINFO_RTSP_CSEQ_RECV, &cseq); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RTSP_SERVER_CSEQ (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_RTSP_SERVER_CSEQ.3 b/3rdparty/curl/share/man/man3/CURLINFO_RTSP_SERVER_CSEQ.3 new file mode 100644 index 0000000..85084da --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_RTSP_SERVER_CSEQ.3 @@ -0,0 +1,46 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_RTSP_SERVER_CSEQ.md +.TH CURLINFO_RTSP_SERVER_CSEQ 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_RTSP_SERVER_CSEQ \- get the next RTSP server CSeq +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_SERVER_CSEQ, + long *cseq); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the next CSeq that is expected to be used +by the application. + +Listening for server initiated requests is not implemented! + +Applications wishing to resume an RTSP session on another connection should +retrieve this info before closing the active connection. +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long cseq; + curl_easy_getinfo(curl, CURLINFO_RTSP_SERVER_CSEQ, &cseq); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RTSP_CSEQ_RECV (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_RTSP_SESSION_ID.3 b/3rdparty/curl/share/man/man3/CURLINFO_RTSP_SESSION_ID.3 new file mode 100644 index 0000000..d9c8d0a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_RTSP_SESSION_ID.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_RTSP_SESSION_ID.md +.TH CURLINFO_RTSP_SESSION_ID 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_RTSP_SESSION_ID \- get RTSP session ID +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_SESSION_ID, char **id); +.fi +.SH DESCRIPTION +Pass a pointer to a char pointer to receive a pointer to a string holding the +most recent RTSP Session ID. + +Applications wishing to resume an RTSP session on another connection should +retrieve this info before closing the active connection. + +The \fBid\fP pointer is NULL or points to private memory. You MUST NOT free \- +it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *id; + curl_easy_getinfo(curl, CURLINFO_RTSP_SESSION_ID, &id); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RTSP_CSEQ_RECV (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_SCHEME.3 b/3rdparty/curl/share/man/man3/CURLINFO_SCHEME.3 new file mode 100644 index 0000000..68251c4 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_SCHEME.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_SCHEME.md +.TH CURLINFO_SCHEME 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_SCHEME \- get the URL scheme (sometimes called protocol) used in the connection +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SCHEME, char **scheme); +.fi +.SH DESCRIPTION +Pass a pointer to a char pointer to receive the pointer to a null\-terminated +string holding the URL scheme used for the most recent connection done with +this CURL \fBhandle\fP. + +The \fBscheme\fP pointer is NULL or points to private memory. You MUST NOT +free \- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. + +The returned scheme might be upper or lowercase. Do comparisons case +insensitively. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *scheme = NULL; + curl_easy_getinfo(curl, CURLINFO_SCHEME, &scheme); + if(scheme) + printf("scheme: %s\\n", scheme); /* scheme: HTTP */ + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_EFFECTIVE_URL (3), +.BR CURLINFO_PROTOCOL (3), +.BR CURLINFO_RESPONSE_CODE (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_SIZE_DOWNLOAD.3 b/3rdparty/curl/share/man/man3/CURLINFO_SIZE_DOWNLOAD.3 new file mode 100644 index 0000000..7e0fede --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_SIZE_DOWNLOAD.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_SIZE_DOWNLOAD.md +.TH CURLINFO_SIZE_DOWNLOAD 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_SIZE_DOWNLOAD \- get the number of downloaded bytes +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_DOWNLOAD, double *dlp); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the total amount of bytes that were +downloaded. The amount is only for the latest transfer and gets reset again +for each new transfer. This counts actual payload data, what\(aqs also commonly +called body. All meta and header data is excluded and not included in this +number. + +\fICURLINFO_SIZE_DOWNLOAD_T(3)\fP is a newer replacement that returns a more +sensible variable type. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + double dl; + res = curl_easy_getinfo(curl, CURLINFO_SIZE_DOWNLOAD, &dl); + if(!res) { + printf("Downloaded %.0f bytes\\n", dl); + } + } + } +} +.fi +.SH DEPRECATED +Deprecated since 7.55.0. +.SH AVAILABILITY +Added in curl 7.4.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_SIZE_DOWNLOAD_T (3), +.BR CURLINFO_SIZE_UPLOAD_T (3), +.BR CURLOPT_MAXFILESIZE (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_SIZE_DOWNLOAD_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_SIZE_DOWNLOAD_T.3 new file mode 100644 index 0000000..5a0b1e3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_SIZE_DOWNLOAD_T.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_SIZE_DOWNLOAD_T.md +.TH CURLINFO_SIZE_DOWNLOAD_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_SIZE_DOWNLOAD_T \- get the number of downloaded bytes +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_DOWNLOAD_T, + curl_off_t *dlp); +.fi +.SH DESCRIPTION +Pass a pointer to a \fIcurl_off_t\fP to receive the total amount of bytes that +were downloaded. The amount is only for the latest transfer and gets reset +again for each new transfer. This counts actual payload data, what\(aqs also +commonly called body. All meta and header data is excluded from this amount. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + curl_off_t dl; + res = curl_easy_getinfo(curl, CURLINFO_SIZE_DOWNLOAD_T, &dl); + if(!res) { + printf("Downloaded %" CURL_FORMAT_CURL_OFF_T " bytes\\n", dl); + } + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.55.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_SIZE_DOWNLOAD (3), +.BR CURLINFO_SIZE_UPLOAD_T (3), +.BR CURLOPT_MAXFILESIZE (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_SIZE_UPLOAD.3 b/3rdparty/curl/share/man/man3/CURLINFO_SIZE_UPLOAD.3 new file mode 100644 index 0000000..d6a2522 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_SIZE_UPLOAD.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_SIZE_UPLOAD.md +.TH CURLINFO_SIZE_UPLOAD 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_SIZE_UPLOAD \- get the number of uploaded bytes +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_UPLOAD, + double *uploadp); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the total amount of bytes that were +uploaded. + +\fICURLINFO_SIZE_UPLOAD_T(3)\fP is a newer replacement that returns a more +sensible variable type. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + double ul; + res = curl_easy_getinfo(curl, CURLINFO_SIZE_UPLOAD, &ul); + if(!res) { + printf("Uploaded %.0f bytes\\n", ul); + } + } + } +} +.fi +.SH DEPRECATED +Deprecated since 7.55.0. +.SH AVAILABILITY +Added in curl 7.4.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_SIZE_DOWNLOAD_T (3), +.BR CURLINFO_SIZE_UPLOAD_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_SIZE_UPLOAD_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_SIZE_UPLOAD_T.3 new file mode 100644 index 0000000..db526a1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_SIZE_UPLOAD_T.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_SIZE_UPLOAD_T.md +.TH CURLINFO_SIZE_UPLOAD_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_SIZE_UPLOAD_T \- get the number of uploaded bytes +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_UPLOAD_T, + curl_off_t *uploadp); +.fi +.SH DESCRIPTION +Pass a pointer to a \fIcurl_off_t\fP to receive the total amount of bytes that +were uploaded. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + curl_off_t ul; + res = curl_easy_getinfo(curl, CURLINFO_SIZE_UPLOAD_T, &ul); + if(!res) { + printf("Uploaded %" CURL_FORMAT_CURL_OFF_T " bytes\\n", ul); + } + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.55.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_SIZE_DOWNLOAD_T (3), +.BR CURLINFO_SIZE_UPLOAD (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_SPEED_DOWNLOAD.3 b/3rdparty/curl/share/man/man3/CURLINFO_SPEED_DOWNLOAD.3 new file mode 100644 index 0000000..10ce21f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_SPEED_DOWNLOAD.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_SPEED_DOWNLOAD.md +.TH CURLINFO_SPEED_DOWNLOAD 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_SPEED_DOWNLOAD \- get download speed +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_DOWNLOAD, + double *speed); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the average download speed that curl +measured for the complete download. Measured in bytes/second. + +\fICURLINFO_SPEED_DOWNLOAD_T(3)\fP is a newer replacement that returns a more +sensible variable type. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + double speed; + res = curl_easy_getinfo(curl, CURLINFO_SPEED_DOWNLOAD, &speed); + if(!res) { + printf("Download speed %.0f bytes/sec\\n", speed); + } + } + } +} +.fi +.SH DEPRECATED +Deprecated since 7.55.0. +.SH AVAILABILITY +Added in curl 7.4.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_SIZE_UPLOAD_T (3), +.BR CURLINFO_SPEED_UPLOAD (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_SPEED_DOWNLOAD_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_SPEED_DOWNLOAD_T.3 new file mode 100644 index 0000000..9dd05a5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_SPEED_DOWNLOAD_T.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_SPEED_DOWNLOAD_T.md +.TH CURLINFO_SPEED_DOWNLOAD_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_SPEED_DOWNLOAD_T \- get download speed +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_DOWNLOAD_T, + curl_off_t *speed); +.fi +.SH DESCRIPTION +Pass a pointer to a \fIcurl_off_t\fP to receive the average download speed +that curl measured for the complete download. Measured in bytes/second. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + curl_off_t speed; + res = curl_easy_getinfo(curl, CURLINFO_SPEED_DOWNLOAD_T, &speed); + if(!res) { + printf("Download speed %" CURL_FORMAT_CURL_OFF_T " bytes/sec\\n", + speed); + } + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.55.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_SIZE_UPLOAD_T (3), +.BR CURLINFO_SPEED_UPLOAD_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_SPEED_UPLOAD.3 b/3rdparty/curl/share/man/man3/CURLINFO_SPEED_UPLOAD.3 new file mode 100644 index 0000000..0836c20 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_SPEED_UPLOAD.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_SPEED_UPLOAD.md +.TH CURLINFO_SPEED_UPLOAD 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_SPEED_UPLOAD \- get upload speed +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_UPLOAD, double *speed); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the average upload speed that curl +measured for the complete upload. Measured in bytes/second. + +\fICURLINFO_SPEED_UPLOAD_T(3)\fP is a newer replacement that returns a more +sensible variable type. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + double speed; + res = curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD, &speed); + if(!res) { + printf("Upload speed %.0f bytes/sec\\n", speed); + } + } + } +} +.fi +.SH DEPRECATED +Deprecated since 7.55.0. +.SH AVAILABILITY +Added in curl 7.4.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_SPEED_DOWNLOAD_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_SPEED_UPLOAD_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_SPEED_UPLOAD_T.3 new file mode 100644 index 0000000..48dc738 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_SPEED_UPLOAD_T.3 @@ -0,0 +1,46 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_SPEED_UPLOAD_T.md +.TH CURLINFO_SPEED_UPLOAD_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_SPEED_UPLOAD_T \- get upload speed +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_UPLOAD_T, + curl_off_t *speed); +.fi +.SH DESCRIPTION +Pass a pointer to a \fIcurl_off_t\fP to receive the average upload speed that +curl measured for the complete upload. Measured in bytes/second. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + curl_off_t speed; + res = curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD_T, &speed); + if(!res) { + printf("Upload speed %" CURL_FORMAT_CURL_OFF_T " bytes/sec\\n", speed); + } + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.55.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_SPEED_DOWNLOAD_T (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_SSL_ENGINES.3 b/3rdparty/curl/share/man/man3/CURLINFO_SSL_ENGINES.3 new file mode 100644 index 0000000..fcf2b7d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_SSL_ENGINES.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_SSL_ENGINES.md +.TH CURLINFO_SSL_ENGINES 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_SSL_ENGINES \- get an slist of OpenSSL crypto\-engines +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SSL_ENGINES, + struct curl_slist **engine_list); +.fi +.SH DESCRIPTION +Pass the address of a \(aqstruct curl_slist *\(aq to receive a linked\-list of +OpenSSL crypto\-engines supported. Note that engines are normally implemented +in separate dynamic libraries. Hence not all the returned engines may be +available at runtime. \fBNOTE:\fP you must call \fIcurl_slist_free_all(3)\fP +on the list pointer once you are done with it, as libcurl does not free this +data for you. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_slist *engines; + res = curl_easy_getinfo(curl, CURLINFO_SSL_ENGINES, &engines); + if((res == CURLE_OK) && engines) { + /* we have a list, free it when done using it */ + curl_slist_free_all(engines); + } + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.12.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_SSLENGINE (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_SSL_VERIFYRESULT.3 b/3rdparty/curl/share/man/man3/CURLINFO_SSL_VERIFYRESULT.3 new file mode 100644 index 0000000..9251898 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_SSL_VERIFYRESULT.3 @@ -0,0 +1,58 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_SSL_VERIFYRESULT.md +.TH CURLINFO_SSL_VERIFYRESULT 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_SSL_VERIFYRESULT \- get the result of the certificate verification +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SSL_VERIFYRESULT, + long *result); +.fi +.SH DESCRIPTION +Pass a pointer to a long to receive the result of the server SSL certificate +verification that was requested (using the \fICURLOPT_SSL_VERIFYPEER(3)\fP +option). + +0 is a positive result. Non\-zero is an error. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + long verifyresult; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + res = curl_easy_perform(curl); + if(res) { + printf("error: %s\\n", curl_easy_strerror(res)); + curl_easy_cleanup(curl); + return 1; + } + + res = curl_easy_getinfo(curl, CURLINFO_SSL_VERIFYRESULT, + &verifyresult); + if(!res) { + printf("The peer verification said %s\\n", + (verifyresult ? "bad" : "fine")); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.5 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_PROXY_SSL_VERIFYRESULT (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_STARTTRANSFER_TIME.3 b/3rdparty/curl/share/man/man3/CURLINFO_STARTTRANSFER_TIME.3 new file mode 100644 index 0000000..c5d5605 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_STARTTRANSFER_TIME.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_STARTTRANSFER_TIME.md +.TH CURLINFO_STARTTRANSFER_TIME 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_STARTTRANSFER_TIME \- get the time until the first byte is received +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_STARTTRANSFER_TIME, + double *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the time, in seconds, it took from the +start until the first byte is received by libcurl. This includes +\fICURLINFO_PRETRANSFER_TIME(3)\fP and also the time the server needs to +calculate the result. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double start; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_STARTTRANSFER_TIME, &start); + if(CURLE_OK == res) { + printf("Time: %.1f", start); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_STARTTRANSFER_TIME_T (3), +.BR CURLOPT_TIMEOUT (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_STARTTRANSFER_TIME_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_STARTTRANSFER_TIME_T.3 new file mode 100644 index 0000000..80d48cc --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_STARTTRANSFER_TIME_T.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_STARTTRANSFER_TIME_T.md +.TH CURLINFO_STARTTRANSFER_TIME_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_STARTTRANSFER_TIME_T \- get the time until the first byte is received +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_STARTTRANSFER_TIME_T, + curl_off_t *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t to receive the time, in microseconds, +it took from the +start until the first byte is received by libcurl. This includes +\fICURLINFO_PRETRANSFER_TIME_T(3)\fP and also the time the server needs to +calculate the result. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t start; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_STARTTRANSFER_TIME_T, &start); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", start / 1000000, + (long)(start % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.61.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_STARTTRANSFER_TIME (3), +.BR CURLOPT_TIMEOUT (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_TLS_SESSION.3 b/3rdparty/curl/share/man/man3/CURLINFO_TLS_SESSION.3 new file mode 100644 index 0000000..2e9d988 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_TLS_SESSION.3 @@ -0,0 +1,60 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_TLS_SESSION.md +.TH CURLINFO_TLS_SESSION 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_TLS_SESSION \- get TLS session info +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION, + struct curl_tlssessioninfo **session); +.fi +.SH DESCRIPTION +\fBThis option has been superseded\fP by \fICURLINFO_TLS_SSL_PTR(3)\fP which +was added in 7.48.0. The only reason you would use this option instead is if +you could be using a version of libcurl earlier than 7.48.0. + +This option is exactly the same as \fICURLINFO_TLS_SSL_PTR(3)\fP except in the +case of OpenSSL. If the session \fIbackend\fP is CURLSSLBACKEND_OPENSSL the +session \fIinternals\fP pointer varies depending on the option: + +\fICURLINFO_TLS_SESSION(3)\fP OpenSSL session \fIinternals\fP is \fBSSL_CTX \fP*. + +\fICURLINFO_TLS_SSL_PTR(3)\fP OpenSSL session \fIinternals\fP is \fBSSL \fP*. + +You can obtain an \fBSSL_CTX\fP pointer from an SSL pointer using OpenSSL +function \fISSL_get_SSL_CTX(3)\fP. Therefore unless you need compatibility +with older versions of libcurl use \fICURLINFO_TLS_SSL_PTR(3)\fP. Refer to +that document for more information. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_tlssessioninfo *tls; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res) + printf("error: %s\\n", curl_easy_strerror(res)); + curl_easy_getinfo(curl, CURLINFO_TLS_SESSION, &tls); + curl_easy_cleanup(curl); + } +} +.fi +.SH DEPRECATED +Deprecated since 7.48.0 +.SH AVAILABILITY +Added in curl 7.34.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_TLS_SSL_PTR (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_TLS_SSL_PTR.3 b/3rdparty/curl/share/man/man3/CURLINFO_TLS_SSL_PTR.3 new file mode 100644 index 0000000..d032b05 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_TLS_SSL_PTR.3 @@ -0,0 +1,140 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_TLS_SSL_PTR.md +.TH CURLINFO_TLS_SSL_PTR 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR \- get TLS session info +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR, + struct curl_tlssessioninfo **session); + +/* if you need compatibility with libcurl < 7.48.0 use + CURLINFO_TLS_SESSION instead: */ + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION, + struct curl_tlssessioninfo **session); +.fi +.SH DESCRIPTION +Pass a pointer to a \fIstruct curl_tlssessioninfo \fP*. The pointer is initialized +to refer to a \fIstruct curl_tlssessioninfo \fP* that contains an enum indicating +the SSL library used for the handshake and a pointer to the respective +internal TLS session structure of this underlying SSL library. + +This option may be useful for example to extract certificate information in a +format convenient for further processing, such as manual validation. Refer to +the \fBLIMITATIONS\fP section. + +.nf +struct curl_tlssessioninfo { + curl_sslbackend backend; + void *internals; +}; +.fi + +The \fIbackend\fP struct member is one of the defines in the CURLSSLBACKEND_* +series: CURLSSLBACKEND_NONE (when built without TLS support), +CURLSSLBACKEND_WOLFSSL, CURLSSLBACKEND_SECURETRANSPORT, CURLSSLBACKEND_GNUTLS, +CURLSSLBACKEND_MBEDTLS, CURLSSLBACKEND_NSS, CURLSSLBACKEND_OPENSSL or +CURLSSLBACKEND_SCHANNEL. (Note that the OpenSSL +forks are all reported as just OpenSSL here.) + +The \fIinternals\fP struct member points to a TLS library specific pointer for +the active ("in use") SSL connection, with the following underlying types: +.IP GnuTLS +\fBgnutls_session_t\fP +.IP OpenSSL +\fICURLINFO_TLS_SESSION(3)\fP: \fBSSL_CTX \fP* + +\fICURLINFO_TLS_SSL_PTR(3)\fP: \fBSSL \fP* +Since 7.48.0 the \fIinternals\fP member can point to these other SSL backends +as well: +.IP mbedTLS +\fBmbedTLS_ssl_context \fP* +.IP "Secure Channel" +\fBCtxtHandle \fP* +.IP "Secure Transport" +\fBSSLContext \fP* +.IP wolfSSL +\fBSSL \fP* +.PP +If the \fIinternals\fP pointer is NULL then either the SSL backend is not +supported, an SSL session has not yet been established or the connection is no +longer associated with the easy handle (e.g. \fIcurl_easy_perform(3)\fP has +returned). +.SH LIMITATIONS +This option has some limitations that could make it unsafe when it comes to +the manual verification of certificates. + +This option only retrieves the first in\-use SSL session pointer for your easy +handle, however your easy handle may have more than one in\-use SSL session if +using FTP over SSL. That is because the FTP protocol has a control channel and +a data channel and one or both may be over SSL. Currently there is no way to +retrieve a second in\-use SSL session associated with an easy handle. + +This option has not been thoroughly tested with clear text protocols that can +be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with +\fICURLOPT_USE_SSL(3)\fP. Though you can to retrieve the SSL pointer, it is possible +that before you can do that, data (including auth) may have already been sent +over a connection after it was upgraded. + +Renegotiation. If unsafe renegotiation or renegotiation in a way that the +certificate is allowed to change is allowed by your SSL library this may occur +and the certificate may change, and data may continue to be sent or received +after renegotiation but before you are able to get the (possibly) changed SSL +pointer, with the (possibly) changed certificate information. + +Instead of using this option to poll for certificate changes use +\fICURLOPT_SSL_CTX_FUNCTION(3)\fP to set a verification callback, if supported. +That is safer and does not suffer from any of the problems above. + +How are you using this option? Are you affected by any of these limitations? +Please let us know by making a comment at +https://github.com/curl/curl/issues/685 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +BearSSL, GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +#include +#include + +CURL *curl; +static size_t wf(void *ptr, size_t size, size_t nmemb, void *stream) +{ + const struct curl_tlssessioninfo *info = NULL; + CURLcode res = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info); + if(info && !res) { + if(CURLSSLBACKEND_OPENSSL == info->backend) { + printf("OpenSSL ver. %s\\n", SSL_get_version((SSL*)info->internals)); + } + } + return size * nmemb; +} + +int main(int argc, char **argv) +{ + CURLcode res; + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } + return res; +} +.fi +.SH HISTORY +This option supersedes \fICURLINFO_TLS_SESSION(3)\fP which was added in 7.34.0. +This option is exactly the same as that option except in the case of OpenSSL. +.SH AVAILABILITY +Added in curl 7.48.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_TLS_SESSION (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_TOTAL_TIME.3 b/3rdparty/curl/share/man/man3/CURLINFO_TOTAL_TIME.3 new file mode 100644 index 0000000..9191bdd --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_TOTAL_TIME.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_TOTAL_TIME.md +.TH CURLINFO_TOTAL_TIME 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_TOTAL_TIME \- get total time of previous transfer +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TOTAL_TIME, double *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a double to receive the total time in seconds for the +previous transfer, including name resolving, TCP connect etc. The double +represents the time in seconds, including fractions. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double total; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME, &total); + if(CURLE_OK == res) { + printf("Time: %.1f", total); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.4.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_TOTAL_TIME_T (3), +.BR CURLOPT_TIMEOUT (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_TOTAL_TIME_T.3 b/3rdparty/curl/share/man/man3/CURLINFO_TOTAL_TIME_T.3 new file mode 100644 index 0000000..c25bb9c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_TOTAL_TIME_T.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_TOTAL_TIME_T.md +.TH CURLINFO_TOTAL_TIME_T 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_TOTAL_TIME_T \- get total time of previous transfer in microseconds +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TOTAL_TIME_T, + curl_off_t *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t to receive the total time in microseconds +for the previous transfer, including name resolving, TCP connect etc. +The curl_off_t represents the time in microseconds. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t total; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME_T, &total); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", total / 1000000, + (long)(total % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.61.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_TOTAL_TIME (3), +.BR CURLOPT_TIMEOUT (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_USED_PROXY.3 b/3rdparty/curl/share/man/man3/CURLINFO_USED_PROXY.3 new file mode 100644 index 0000000..2da1ab5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_USED_PROXY.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_USED_PROXY.md +.TH CURLINFO_USED_PROXY 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_USED_PROXY \- whether the transfer used a proxy +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_USED_PROXY, + long *authp); +.fi +.SH DESCRIPTION +Pass a pointer to a long. It gets set to zero set if no proxy was used in the +previous transfer or a non\-zero value if a proxy was used. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(int argc, char *argv[]) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80"); + curl_easy_setopt(curl, CURLOPT_NOPROXY, "example.com"); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract the available proxy authentication types */ + long used; + res = curl_easy_getinfo(curl, CURLINFO_USED_PROXY, &used); + if(!res) { + printf("The proxy was %sused\\n", used ? "": "NOT "); + } + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 8.7.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_NOPROXY (3), +.BR CURLOPT_PROXY (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLINFO_XFER_ID.3 b/3rdparty/curl/share/man/man3/CURLINFO_XFER_ID.3 new file mode 100644 index 0000000..b2b348d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLINFO_XFER_ID.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLINFO_XFER_ID.md +.TH CURLINFO_XFER_ID 3 "2024-10-11" libcurl +.SH NAME +CURLINFO_XFER_ID \- get the ID of a transfer +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_XFER_ID, + curl_off_t *xfer_id); +.fi +.SH DESCRIPTION +Pass a pointer to a \fIcurl_off_t\fP to receive the identifier of the +current/last transfer done with the handle. Stores \-1 if no transfer +has been started yet for the handle. + +The transfer id is unique among all transfers performed using the same +connection cache. This is implicitly the case for all transfers in the +same multi handle. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + curl_off_t xfer_id; + res = curl_easy_getinfo(curl, CURLINFO_XFER_ID, &xfer_id); + if(!res) { + printf("Transfer ID: %" CURL_FORMAT_CURL_OFF_T "\\n", xfer_id); + } + } + } +} +.fi +.SH AVAILABILITY +Added in curl 8.2.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CONN_ID (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 b/3rdparty/curl/share/man/man3/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 new file mode 100644 index 0000000..e7a51d1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 @@ -0,0 +1,40 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md +.TH CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE \- chunk length threshold for pipelining +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, + long size); +.fi +.SH DESCRIPTION +No function since pipelining was removed in 7.62.0. + +Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is +currently processing a chunked (Transfer\-encoding: chunked) request with a +current chunk length larger than \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP, +that pipeline is not considered for additional requests, even if it is shorter +than \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. +.SH DEFAULT +0, which means that penalization is inactive. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *m = curl_multi_init(); + long maxchunk = 10000; + curl_multi_setopt(m, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, maxchunk); +} +.fi +.SH AVAILABILITY +Added in curl 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE (3), +.BR CURLMOPT_MAX_PIPELINE_LENGTH (3), +.BR CURLMOPT_PIPELINING (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 b/3rdparty/curl/share/man/man3/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 new file mode 100644 index 0000000..210700d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 @@ -0,0 +1,39 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md +.TH CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE \- size threshold for pipelining penalty +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, + long size); +.fi +.SH DESCRIPTION +No function since pipelining was removed in 7.62.0. + +Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is +currently processing a request with a Content\-Length larger than this +\fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP, that pipeline is not considered +for additional requests, even if it is shorter than +\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. +.SH DEFAULT +0, which means that the size penalization is inactive. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *m = curl_multi_init(); + long maxlength = 10000; + curl_multi_setopt(m, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, maxlength); +} +.fi +.SH AVAILABILITY +Added in curl 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE (3), +.BR CURLMOPT_PIPELINING (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_MAXCONNECTS.3 b/3rdparty/curl/share/man/man3/CURLMOPT_MAXCONNECTS.3 new file mode 100644 index 0000000..d31b906 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_MAXCONNECTS.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_MAXCONNECTS.md +.TH CURLMOPT_MAXCONNECTS 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_MAXCONNECTS \- size of connection cache +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAXCONNECTS, long max); +.fi +.SH DESCRIPTION +Pass a long indicating the \fBmax\fP. The set number is used as the maximum +amount of simultaneously open connections that libcurl may keep in its +connection cache after completed use. By default libcurl enlarges the size for +each added easy handle to make it fit 4 times the number of added easy +handles. + +By setting this option, you can prevent the cache size from growing beyond the +limit set by you. + +When the cache is full, curl closes the oldest one in the cache to prevent the +number of open connections from increasing. + +This option is for the multi handle\(aqs use only, when using the easy interface +you should instead use the \fICURLOPT_MAXCONNECTS(3)\fP option. + +See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP for limiting the number of active +connections. + +Changing this value when there are transfers in progress is possible, and the +new value is then used the next time checks are performed. Lowering the value +does however not close down any active transfers, it simply does not allow new +ones to get made. +.SH DEFAULT +See DESCRIPTION +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *m = curl_multi_init(); + /* only keep 10 connections in the cache */ + curl_multi_setopt(m, CURLMOPT_MAXCONNECTS, 10L); +} +.fi +.SH AVAILABILITY +Added in curl 7.16.3 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_MAX_HOST_CONNECTIONS (3), +.BR CURLOPT_MAXCONNECTS (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_MAX_CONCURRENT_STREAMS.3 b/3rdparty/curl/share/man/man3/CURLMOPT_MAX_CONCURRENT_STREAMS.3 new file mode 100644 index 0000000..2b0291d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_MAX_CONCURRENT_STREAMS.3 @@ -0,0 +1,38 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_MAX_CONCURRENT_STREAMS.md +.TH CURLMOPT_MAX_CONCURRENT_STREAMS 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_MAX_CONCURRENT_STREAMS \- max concurrent streams for http2 +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_CONCURRENT_STREAMS, + long max); +.fi +.SH DESCRIPTION +Pass a long indicating the \fBmax\fP. The set number is used as the maximum +number of concurrent streams libcurl should support on connections done using +HTTP/2 or HTTP/3. + +Valid values range from 1 to 2147483647 (2^31 \- 1) and defaults to 100. The +value passed here would be honored based on other system resources properties. +.SH DEFAULT +100 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *m = curl_multi_init(); + /* max concurrent streams 200 */ + curl_multi_setopt(m, CURLMOPT_MAX_CONCURRENT_STREAMS, 200L); +} +.fi +.SH AVAILABILITY +Added in curl 7.67.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_MAXCONNECTS (3), +.BR CURLOPT_MAXCONNECTS (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_MAX_HOST_CONNECTIONS.3 b/3rdparty/curl/share/man/man3/CURLMOPT_MAX_HOST_CONNECTIONS.3 new file mode 100644 index 0000000..c76c5a8 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_MAX_HOST_CONNECTIONS.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_MAX_HOST_CONNECTIONS.md +.TH CURLMOPT_MAX_HOST_CONNECTIONS 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_MAX_HOST_CONNECTIONS \- max number of connections to a single host +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS, + long max); +.fi +.SH DESCRIPTION +Pass a long to indicate \fBmax\fP. The set number is used as the maximum amount +of simultaneously open connections to a single host (a host being the same as +a hostname + port number pair). For each new session to a host, libcurl might +open a new connection up to the limit set by \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. +When the limit is reached, new sessions are kept pending until a connection +becomes available. + +The default \fBmax\fP value is 0, unlimited. This set limit is also used for +proxy connections, and then the proxy is considered to be the host for which +this limit counts. + +When more transfers are added to the multi handle than what can be performed +due to the set limit, they are queued up waiting for their chance. When that +happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout is inclusive of the waiting time, +meaning that if you set a too narrow timeout in such a case the transfer might +never even start before it times out. + +Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP timeout is +however treated as a per\-connect timeout. + +Changing this value when there are transfers in progress is possible, and the +new value is then used the next time checks are performed. Lowering the value +does however not close down any active transfers, it simply does not allow new +ones to get made. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *m = curl_multi_init(); + /* do no more than 2 connections per host */ + curl_multi_setopt(m, CURLMOPT_MAX_HOST_CONNECTIONS, 2L); +} +.fi +.SH AVAILABILITY +Added in curl 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_MAXCONNECTS (3), +.BR CURLMOPT_MAX_TOTAL_CONNECTIONS (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_MAX_PIPELINE_LENGTH.3 b/3rdparty/curl/share/man/man3/CURLMOPT_MAX_PIPELINE_LENGTH.3 new file mode 100644 index 0000000..8a2b7a0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_MAX_PIPELINE_LENGTH.3 @@ -0,0 +1,44 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_MAX_PIPELINE_LENGTH.md +.TH CURLMOPT_MAX_PIPELINE_LENGTH 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_MAX_PIPELINE_LENGTH \- maximum number of requests in a pipeline +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_PIPELINE_LENGTH, + long max); +.fi +.SH DESCRIPTION +No function since pipelining was removed in 7.62.0. + +Pass a long. The set \fBmax\fP number is used as the maximum amount of +outstanding requests in an HTTP/1.1 pipeline. This option is only used for +HTTP/1.1 pipelining, not for HTTP/2 multiplexing. + +When this limit is reached, libcurl creates another connection to the same +host (see \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP), or queue the request until one +.nf +of the pipelines to the host is ready to accept a request. Thus, the total +.fi +\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. +.SH DEFAULT +5 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *m = curl_multi_init(); + /* set a more conservative pipe length */ + curl_multi_setopt(m, CURLMOPT_MAX_PIPELINE_LENGTH, 3L); +} +.fi +.SH AVAILABILITY +Added in curl 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_MAX_HOST_CONNECTIONS (3), +.BR CURLMOPT_PIPELINING (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 b/3rdparty/curl/share/man/man3/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 new file mode 100644 index 0000000..8c9775c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_MAX_TOTAL_CONNECTIONS.md +.TH CURLMOPT_MAX_TOTAL_CONNECTIONS 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_MAX_TOTAL_CONNECTIONS \- max simultaneously open connections +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_TOTAL_CONNECTIONS, + long amount); +.fi +.SH DESCRIPTION +Pass a long for the \fBamount\fP. The set number is used as the maximum number +of simultaneously open connections in total using this multi handle. For each +new session, libcurl might open a new connection up to the limit set by +\fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. When the limit is reached, new +sessions are held pending until there are available connections. If +\fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl can try multiplexing if the +host is capable of it. + +When more transfers are added to the multi handle than what can be performed +due to the set limit, they get queued up waiting for their chance. When that +happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout is counted inclusive of the +waiting time, meaning that if you set a too narrow timeout in such a case the +transfer might never even start before it times out. + +Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP +timeout is however treated as a per\-connect timeout. +.SH DEFAULT +0, which means that there is no limit. It is then simply controlled by the +number of easy handles added. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *m = curl_multi_init(); + /* never do more than 15 connections */ + curl_multi_setopt(m, CURLMOPT_MAX_TOTAL_CONNECTIONS, 15L); +} +.fi +.SH AVAILABILITY +Added in curl 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_MAXCONNECTS (3), +.BR CURLMOPT_MAX_HOST_CONNECTIONS (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_PIPELINING.3 b/3rdparty/curl/share/man/man3/CURLMOPT_PIPELINING.3 new file mode 100644 index 0000000..9834b1f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_PIPELINING.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_PIPELINING.md +.TH CURLMOPT_PIPELINING 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_PIPELINING \- enable HTTP multiplexing +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING, long bitmask); +.fi +.SH DESCRIPTION +Pass in the correct value in the \fBbitmask\fP parameter to instruct libcurl to +enable multiplexing for this multi handle. + +With multiplexing enabled, libcurl attempts to do multiple transfers over the +same connection when doing parallel transfers to the same hosts. +.IP "CURLPIPE_NOTHING (0)" +Make no attempts at multiplexing. +.IP "CURLPIPE_HTTP1 (1)" +This bit is deprecated and has no effect since version 7.62.0. +.IP "CURLPIPE_MULTIPLEX (2)" +If this bit is set, libcurl tries to multiplex the new transfer over an +existing connection if possible. This requires HTTP/2 or HTTP/3. +.SH DEFAULT +\fBCURLPIPE_MULTIPLEX\fP +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *m = curl_multi_init(); + /* try HTTP/2 multiplexing */ + curl_multi_setopt(m, CURLMOPT_PIPELINING, CURLPIPE_MULTIPLEX); +} +.fi +.SH HISTORY +The multiplex support bit was added in 7.43.0. HTTP/1 Pipelining support was +disabled in 7.62.0. + +Since 7.62.0, \fBCURLPIPE_MULTIPLEX\fP is enabled by default. + +Before that, default was \fBCURLPIPE_NOTHING\fP. +.SH AVAILABILITY +Added in curl 7.16.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE (3), +.BR CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE (3), +.BR CURLMOPT_MAXCONNECTS (3), +.BR CURLMOPT_MAX_HOST_CONNECTIONS (3), +.BR CURLMOPT_MAX_PIPELINE_LENGTH (3), +.BR CURLMOPT_PIPELINING_SITE_BL (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_PIPELINING_SERVER_BL.3 b/3rdparty/curl/share/man/man3/CURLMOPT_PIPELINING_SERVER_BL.3 new file mode 100644 index 0000000..24d7b46 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_PIPELINING_SERVER_BL.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_PIPELINING_SERVER_BL.md +.TH CURLMOPT_PIPELINING_SERVER_BL 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_PIPELINING_SERVER_BL \- pipelining server block list +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SERVER_BL, + char **servers); +.fi +.SH DESCRIPTION +No function since pipelining was removed in 7.62.0. + +Pass a \fBservers\fP array of char *, ending with a NULL entry. This is a list +of server types prefixes (in the Server: HTTP header) that are blocked from +pipelining, i.e server types that are known to not support HTTP +pipelining. The array is copied by libcurl. + +Note that the comparison matches if the Server: header begins with the string +in the block list, i.e "Server: Ninja 1.2.3" and "Server: Ninja 1.4.0" can +both be blocked by having "Ninja" in the list. + +Pass a NULL pointer to clear the block list. +.SH DEFAULT +NULL, which means that there is no block list. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +static char *server_block_list[] = +{ + "Microsoft-IIS/6.0", + "nginx/0.8.54", + NULL +}; +int main(void) +{ + CURLM *m = curl_multi_init(); + curl_multi_setopt(m, CURLMOPT_PIPELINING_SERVER_BL, server_block_list); +} +.fi +.SH AVAILABILITY +Added in curl 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_PIPELINING (3), +.BR CURLMOPT_PIPELINING_SITE_BL (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_PIPELINING_SITE_BL.3 b/3rdparty/curl/share/man/man3/CURLMOPT_PIPELINING_SITE_BL.3 new file mode 100644 index 0000000..d1825ef --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_PIPELINING_SITE_BL.3 @@ -0,0 +1,45 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_PIPELINING_SITE_BL.md +.TH CURLMOPT_PIPELINING_SITE_BL 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_PIPELINING_SITE_BL \- pipelining host block list +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SITE_BL, + char **hosts); +.fi +.SH DESCRIPTION +No function since pipelining was removed in 7.62.0. + +Pass a \fBhosts\fP array of char *, ending with a NULL entry. This is a list +of sites that are blocked from pipelining, i.e sites that are known to not +support HTTP pipelining. The array is copied by libcurl. + +Pass a NULL pointer to clear the block list. +.SH DEFAULT +NULL, which means that there is no block list. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +static char *site_block_list[] = +{ + "www.haxx.se", + "www.example.com:1234", + NULL +}; + +int main(void) +{ + CURLM *m = curl_multi_init(); + curl_multi_setopt(m, CURLMOPT_PIPELINING_SITE_BL, site_block_list); +} +.fi +.SH AVAILABILITY +Added in curl 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_PIPELINING (3), +.BR CURLMOPT_PIPELINING_SERVER_BL (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_PUSHDATA.3 b/3rdparty/curl/share/man/man3/CURLMOPT_PUSHDATA.3 new file mode 100644 index 0000000..639c2c2 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_PUSHDATA.3 @@ -0,0 +1,66 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_PUSHDATA.md +.TH CURLMOPT_PUSHDATA 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_PUSHDATA \- pointer to pass to push callback +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHDATA, void *pointer); +.fi +.SH DESCRIPTION +Set a \fIpointer\fP to pass as the last argument to the +\fICURLMOPT_PUSHFUNCTION(3)\fP callback. The pointer is not touched or used by +libcurl itself, only passed on to the callback function. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +#include + +/* only allow pushes for filenames starting with "push-" */ +int push_callback(CURL *parent, + CURL *easy, + size_t num_headers, + struct curl_pushheaders *headers, + void *clientp) +{ + char *headp; + int *transfers = (int *)clientp; + FILE *out; + headp = curl_pushheader_byname(headers, ":path"); + if(headp && !strncmp(headp, "/push-", 6)) { + fprintf(stderr, "The PATH is %s\\n", headp); + + /* save the push here */ + out = fopen("pushed-stream", "wb"); + + /* write to this file */ + curl_easy_setopt(easy, CURLOPT_WRITEDATA, out); + + (*transfers)++; /* one more */ + + return CURL_PUSH_OK; + } + return CURL_PUSH_DENY; +} + +int main(void) +{ + int counter; + CURLM *multi = curl_multi_init(); + curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback); + curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter); +} +.fi +.SH AVAILABILITY +Added in curl 7.44.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_PIPELINING (3), +.BR CURLMOPT_PUSHFUNCTION (3), +.BR CURLOPT_PIPEWAIT (3), +.BR RFC 7540 diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_PUSHFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLMOPT_PUSHFUNCTION.3 new file mode 100644 index 0000000..552107b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_PUSHFUNCTION.3 @@ -0,0 +1,116 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_PUSHFUNCTION.md +.TH CURLMOPT_PUSHFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_PUSHFUNCTION \- callback that approves or denies server pushes +.SH SYNOPSIS +.nf +#include + +int curl_push_callback(CURL *parent, + CURL *easy, + size_t num_headers, + struct curl_pushheaders *headers, + void *clientp); + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION, + curl_push_callback func); +.fi +.SH DESCRIPTION +This callback gets called when a new HTTP/2 stream is being pushed by the +server (using the PUSH_PROMISE frame). If no push callback is set, all offered +pushes are denied automatically. +.SH CALLBACK DESCRIPTION +The callback gets its arguments like this: + +\fIparent\fP is the handle of the stream on which this push arrives. The new +handle has been duplicated from the parent, meaning that it has gotten all its +options inherited. It is then up to the application to alter any options if +desired. + +\fIeasy\fP is a newly created handle that represents this upcoming transfer. + +\fInum_headers\fP is the number of name+value pairs that was received and can +be accessed + +\fIheaders\fP is a handle used to access push headers using the accessor +functions described below. This only accesses and provides the PUSH_PROMISE +headers, the normal response headers are provided in the header callback as +usual. + +\fIclientp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP + +If the callback returns CURL_PUSH_OK, the new easy handle is added to the +multi handle, the callback must not do that by itself. + +The callback can access PUSH_PROMISE headers with two accessor +functions. These functions can only be used from within this callback and they +can only access the PUSH_PROMISE headers: \fIcurl_pushheader_byname(3)\fP and +\fIcurl_pushheader_bynum(3)\fP. The normal response headers are passed to the +header callback for pushed streams just as for normal streams. + +The header fields can also be accessed with \fIcurl_easy_header(3)\fP, +introduced in later libcurl versions. +.SH CALLBACK RETURN VALUE +.IP "CURL_PUSH_OK (0)" +The application has accepted the stream and it can now start receiving data, +the ownership of the CURL handle has been taken over by the application. +.IP "CURL_PUSH_DENY (1)" +The callback denies the stream and no data reaches the application, the easy +handle is destroyed by libcurl. +.IP "CURL_PUSH_ERROROUT (2)" +Returning this code rejects the pushed stream and returns an error back on the +parent stream making it get closed with an error. (Added in 7.72.0) +.IP * +All other return codes are reserved for future use. +.SH DEFAULT +NULL, no callback +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +#include + +/* only allow pushes for filenames starting with "push-" */ +int push_callback(CURL *parent, + CURL *easy, + size_t num_headers, + struct curl_pushheaders *headers, + void *clientp) +{ + char *headp; + int *transfers = (int *)clientp; + FILE *out; + headp = curl_pushheader_byname(headers, ":path"); + if(headp && !strncmp(headp, "/push-", 6)) { + fprintf(stderr, "The PATH is %s\\n", headp); + + /* save the push here */ + out = fopen("pushed-stream", "wb"); + + /* write to this file */ + curl_easy_setopt(easy, CURLOPT_WRITEDATA, out); + + (*transfers)++; /* one more */ + + return CURL_PUSH_OK; + } + return CURL_PUSH_DENY; +} + +int main(void) +{ + int counter; + CURLM *multi = curl_multi_init(); + curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback); + curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter); +} +.fi +.SH AVAILABILITY +Added in curl 7.44.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_PIPELINING (3), +.BR CURLMOPT_PUSHDATA (3), +.BR CURLOPT_PIPEWAIT (3), +.BR RFC 7540 diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_SOCKETDATA.3 b/3rdparty/curl/share/man/man3/CURLMOPT_SOCKETDATA.3 new file mode 100644 index 0000000..a10e672 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_SOCKETDATA.3 @@ -0,0 +1,61 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_SOCKETDATA.md +.TH CURLMOPT_SOCKETDATA 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_SOCKETDATA \- custom pointer passed to the socket callback +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETDATA, void *pointer); +.fi +.SH DESCRIPTION +A data \fIpointer\fP to pass to the socket callback set with the +\fICURLMOPT_SOCKETFUNCTION(3)\fP option. + +This pointer is not touched by libcurl but is only passed in as the socket +callback\(aqs \fBclientp\fP argument. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct priv { + void *ours; +}; + +static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp) +{ + struct priv *p = sockp; + printf("my ptr: %p\\n", p->ours); + + if(what == CURL_POLL_REMOVE) { + /* remove the socket from our collection */ + } + if(what & CURL_POLL_IN) { + /* wait for read on this socket */ + } + if(what & CURL_POLL_OUT) { + /* wait for write on this socket */ + } + + return 0; +} + +int main(void) +{ + struct priv setup; + CURLM *multi = curl_multi_init(); + /* ... use socket callback and custom pointer */ + curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb); + curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup); +} +.fi +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +Returns CURLM_OK. +.SH SEE ALSO +.BR CURLMOPT_SOCKETFUNCTION (3), +.BR CURLMOPT_TIMERFUNCTION (3), +.BR curl_multi_socket_action (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_SOCKETFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLMOPT_SOCKETFUNCTION.3 new file mode 100644 index 0000000..4bd0bfc --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_SOCKETFUNCTION.3 @@ -0,0 +1,107 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_SOCKETFUNCTION.md +.TH CURLMOPT_SOCKETFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_SOCKETFUNCTION \- callback informed about what to wait for +.SH SYNOPSIS +.nf +#include + +int socket_callback(CURL *easy, /* easy handle */ + curl_socket_t s, /* socket */ + int what, /* describes the socket */ + void *clientp, /* private callback pointer */ + void *socketp); /* private socket pointer */ + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +When the \fIcurl_multi_socket_action(3)\fP function is called, it uses this +callback to inform the application about updates in the socket (file +descriptor) status by doing none, one, or multiple calls to the +\fBsocket_callback\fP. The callback function gets status updates with changes +since the previous time the callback was called. If the given callback pointer +is set to NULL, no callback is called. + +libcurl then expects the application to monitor the sockets for the specific +activities and tell libcurl again when something happens on one of them. Tell +libcurl by calling \fIcurl_multi_socket_action(3)\fP. +.SH CALLBACK ARGUMENTS +\fIeasy\fP identifies the specific transfer for which this update is related. +Since this callback manages a whole multi handle, an application should not +make assumptions about which particular handle that is passed here. It might +even be an internal easy handle that the application did not add itself. + +\fIs\fP is the specific socket this function invocation concerns. If the +\fBwhat\fP argument is not CURL_POLL_REMOVE then it holds information about +what activity on this socket the application is supposed to +monitor. Subsequent calls to this callback might update the \fBwhat\fP bits +for a socket that is already monitored. + +The socket callback should return 0 on success, and \-1 on error. If this +callback returns error, \fBall\fP transfers currently in progress in this +multi handle are aborted and made to fail. + +\fBclientp\fP is set with \fICURLMOPT_SOCKETDATA(3)\fP. + +\fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or NULL. + +The \fBwhat\fP parameter informs the callback on the status of the given +socket. It can hold one of these values: +.IP CURL_POLL_IN +Wait for incoming data. For the socket to become readable. +.IP CURL_POLL_OUT +Wait for outgoing data. For the socket to become writable. +.IP CURL_POLL_INOUT +Wait for incoming and outgoing data. For the socket to become readable or +writable. +.IP CURL_POLL_REMOVE +The specified socket/file descriptor is no longer used by libcurl for any +active transfer. It might soon be added again. +.SH DEFAULT +NULL (no callback) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct priv { + void *ours; +}; + +static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp) +{ + struct priv *p = sockp; + printf("our ptr: %p\\n", p->ours); + + if(what == CURL_POLL_REMOVE) { + /* remove the socket from our collection */ + } + if(what & CURL_POLL_IN) { + /* wait for read on this socket */ + } + if(what & CURL_POLL_OUT) { + /* wait for write on this socket */ + } + + return 0; +} + +int main(void) +{ + struct priv setup; + CURLM *multi = curl_multi_init(); + /* ... use socket callback and custom pointer */ + curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb); + curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup); +} +.fi +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +Returns CURLM_OK. +.SH SEE ALSO +.BR CURLMOPT_SOCKETDATA (3), +.BR CURLMOPT_TIMERFUNCTION (3), +.BR curl_multi_socket_action (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_TIMERDATA.3 b/3rdparty/curl/share/man/man3/CURLMOPT_TIMERDATA.3 new file mode 100644 index 0000000..e4306f9 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_TIMERDATA.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_TIMERDATA.md +.TH CURLMOPT_TIMERDATA 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_TIMERDATA \- custom pointer to pass to timer callback +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERDATA, void *pointer); +.fi +.SH DESCRIPTION +A data \fBpointer\fP to pass to the timer callback set with the +\fICURLMOPT_TIMERFUNCTION(3)\fP option. + +This pointer is not touched by libcurl but is only be passed in to the timer +callback\(aqs \fBclientp\fP argument. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct priv { + void *custom; +}; + +static int timerfunc(CURLM *multi, long timeout_ms, void *clientp) +{ + struct priv *mydata = clientp; + printf("our ptr: %p\\n", mydata->custom); + + if(timeout_ms) { + /* this is the new single timeout to wait for */ + } + else { + /* delete the timeout, nothing to wait for now */ + } +} + +int main(void) +{ + struct priv mydata; + CURLM *multi = curl_multi_init(); + curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc); + curl_multi_setopt(multi, CURLMOPT_TIMERDATA, &mydata); +} +.fi +.SH AVAILABILITY +Added in curl 7.16.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_SOCKETFUNCTION (3), +.BR CURLMOPT_TIMERFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLMOPT_TIMERFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLMOPT_TIMERFUNCTION.3 new file mode 100644 index 0000000..0678bab --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLMOPT_TIMERFUNCTION.3 @@ -0,0 +1,86 @@ +.\" generated by cd2nroff 0.1 from CURLMOPT_TIMERFUNCTION.md +.TH CURLMOPT_TIMERFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLMOPT_TIMERFUNCTION \- callback to receive timeout values +.SH SYNOPSIS +.nf +#include + +int timer_callback(CURLM *multi, /* multi handle */ + long timeout_ms, /* timeout in number of ms */ + void *clientp); /* private callback pointer */ + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +Certain features, such as timeouts and retries, require you to call libcurl +even when there is no activity on the file descriptors. + +Your callback function \fBtimer_callback\fP should install a single +non\-repeating timer with an expire time of \fBtimeout_ms\fP milliseconds. When +that timer fires, call either \fIcurl_multi_socket_action(3)\fP or +\fIcurl_multi_perform(3)\fP, depending on which interface you use. + +If this callback is called when a timer is already running, this new expire +time \fIreplaces\fP the former timeout. The application should then effectively +cancel the old timeout and set a new timeout using this new expire time. + +A \fBtimeout_ms\fP value of \-1 passed to this callback means you should delete +the timer. All other values are valid expire times in number of milliseconds. + +The \fBtimer_callback\fP is called when the timeout expire time is changed. + +The \fBclientp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP. + +The timer callback should return 0 on success, and \-1 on error. If this +callback returns error, \fBall\fP transfers currently in progress in this multi +handle are aborted and made to fail. + +This callback can be used instead of, or in addition to, +\fIcurl_multi_timeout(3)\fP. + +\fBWARNING:\fP do not call libcurl directly from within the callback itself when +the \fBtimeout_ms\fP value is zero, since it risks triggering an unpleasant +recursive behavior that immediately calls another call to the callback with a +zero timeout... +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct priv { + void *custom; +}; + +static int timerfunc(CURLM *multi, long timeout_ms, void *clientp) +{ + struct priv *mydata = clientp; + printf("our ptr: %p\\n", mydata->custom); + + if(timeout_ms) { + /* this is the new single timeout to wait for */ + } + else { + /* delete the timeout, nothing to wait for now */ + } +} + +int main(void) +{ + struct priv mydata; + CURLM *multi = curl_multi_init(); + curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc); + curl_multi_setopt(multi, CURLMOPT_TIMERDATA, &mydata); +} +.fi +.SH AVAILABILITY +Added in curl 7.16.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_SOCKETFUNCTION (3), +.BR CURLMOPT_TIMERDATA (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_ABSTRACT_UNIX_SOCKET.3 b/3rdparty/curl/share/man/man3/CURLOPT_ABSTRACT_UNIX_SOCKET.3 new file mode 100644 index 0000000..6a43ebd --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_ABSTRACT_UNIX_SOCKET.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_ABSTRACT_UNIX_SOCKET.md +.TH CURLOPT_ABSTRACT_UNIX_SOCKET 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_ABSTRACT_UNIX_SOCKET \- abstract Unix domain socket +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ABSTRACT_UNIX_SOCKET, + char *path); +.fi +.SH DESCRIPTION +Enables the use of an abstract Unix domain socket instead of establishing a +TCP connection to a host. The parameter should be a char * to a +null\-terminated string holding the path of the socket. The path is set to +\fIpath\fP prefixed by a NULL byte. This is the convention for abstract +sockets, however it should be stressed that the path passed to this function +should not contain a leading NULL byte. + +On non\-supporting platforms, the abstract address is interpreted as an empty +string and fails gracefully, generating a runtime error. + +This option shares the same semantics as \fICURLOPT_UNIX_SOCKET_PATH(3)\fP in +which documentation more details can be found. Internally, these two options +share the same storage and therefore only one of them can be set per handle. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock"); + curl_easy_setopt(curl, CURLOPT_URL, "http://localhost/"); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.53.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_UNIX_SOCKET_PATH (3), +.BR unix (7) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_ACCEPTTIMEOUT_MS.3 b/3rdparty/curl/share/man/man3/CURLOPT_ACCEPTTIMEOUT_MS.3 new file mode 100644 index 0000000..d01b334 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_ACCEPTTIMEOUT_MS.3 @@ -0,0 +1,40 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_ACCEPTTIMEOUT_MS.md +.TH CURLOPT_ACCEPTTIMEOUT_MS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_ACCEPTTIMEOUT_MS \- timeout waiting for FTP server to connect back +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPTTIMEOUT_MS, long ms); +.fi +.SH DESCRIPTION +Pass a long telling libcurl the maximum number of milliseconds to wait for a +server to connect back to libcurl when an active FTP connection is used. +.SH DEFAULT +60000 milliseconds +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/path/file"); + + /* wait no more than 5 seconds for FTP server responses */ + curl_easy_setopt(curl, CURLOPT_ACCEPTTIMEOUT_MS, 5000L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.24.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CONNECTTIMEOUT_MS (3), +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_STDERR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_ACCEPT_ENCODING.3 b/3rdparty/curl/share/man/man3/CURLOPT_ACCEPT_ENCODING.3 new file mode 100644 index 0000000..5dc5bf0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_ACCEPT_ENCODING.3 @@ -0,0 +1,94 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_ACCEPT_ENCODING.md +.TH CURLOPT_ACCEPT_ENCODING 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_ACCEPT_ENCODING \- automatic decompression of HTTP downloads +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPT_ENCODING, char *enc); +.fi +.SH DESCRIPTION +Pass a char pointer argument specifying what encoding you would like. + +Sets the contents of the Accept\-Encoding: header sent in an HTTP request, and +enables decoding of a response when a Content\-Encoding: header is received. + +libcurl potentially supports several different compressed encodings depending +on what support that has been built\-in. + +To aid applications not having to bother about what specific algorithms this +particular libcurl build supports, libcurl allows a zero\-length string to be +set ("") to ask for an Accept\-Encoding: header to be used that contains all +built\-in supported encodings. + +Alternatively, you can specify exactly the encoding or list of encodings you +want in the response. The following encodings are supported: \fIidentity\fP, +meaning non\-compressed, \fIdeflate\fP which requests the server to compress its +response using the zlib algorithm, \fIgzip\fP which requests the gzip algorithm, +(since curl 7.57.0) \fIbr\fP which is brotli and (since curl 7.72.0) \fIzstd\fP which +is zstd. Provide them in the string as a comma\-separated list of accepted +encodings, like: \fB"br, gzip, deflate"\fP. + +Set \fICURLOPT_ACCEPT_ENCODING(3)\fP to NULL to explicitly disable it, which makes +libcurl not send an Accept\-Encoding: header and not decompress received +contents automatically. + +You can also opt to just include the Accept\-Encoding: header in your request +with \fICURLOPT_HTTPHEADER(3)\fP but then there is no automatic decompressing when +receiving data. + +This is a request, not an order; the server may or may not do it. This option +must be set (to any non\-NULL value) or else any unsolicited encoding done by +the server is ignored. + +Servers might respond with Content\-Encoding even without getting a +Accept\-Encoding: in the request. Servers might respond with a different +Content\-Encoding than what was asked for in the request. + +The Content\-Length: servers send for a compressed response is supposed to +indicate the length of the compressed content so when auto decoding is enabled +it may not match the sum of bytes reported by the write callbacks (although, +sending the length of the non\-compressed content is a common server mistake). + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. +.SH HISTORY +This option was called CURLOPT_ENCODING before 7.21.6 +.SH NOTES +The specific libcurl you are using must have been built with zlib to be able to +decompress gzip and deflate responses, with the brotli library to +decompress brotli responses and with the zstd library to decompress zstd +responses. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable all supported built-in compressions */ + curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, ""); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.21.6 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_HTTPHEADER (3), +.BR CURLOPT_HTTP_CONTENT_DECODING (3), +.BR CURLOPT_TRANSFER_ENCODING (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_ADDRESS_SCOPE.3 b/3rdparty/curl/share/man/man3/CURLOPT_ADDRESS_SCOPE.3 new file mode 100644 index 0000000..f4afc10 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_ADDRESS_SCOPE.3 @@ -0,0 +1,42 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_ADDRESS_SCOPE.md +.TH CURLOPT_ADDRESS_SCOPE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_ADDRESS_SCOPE \- scope id for IPv6 addresses +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ADDRESS_SCOPE, long scope); +.fi +.SH DESCRIPTION +Pass a long specifying the scope id value to use when connecting to IPv6 addresses. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +#include /* for if_nametoindex() */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + long my_scope_id; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + my_scope_id = if_nametoindex("eth0"); + curl_easy_setopt(curl, CURLOPT_ADDRESS_SCOPE, my_scope_id); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value. +.SH SEE ALSO +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_STDERR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_ALTSVC.3 b/3rdparty/curl/share/man/man3/CURLOPT_ALTSVC.3 new file mode 100644 index 0000000..e34bf27 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_ALTSVC.3 @@ -0,0 +1,78 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_ALTSVC.md +.TH CURLOPT_ALTSVC 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_ALTSVC \- alt\-svc cache filename +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC, char *filename); +.fi +.SH DESCRIPTION +Pass in a pointer to a \fIfilename\fP to instruct libcurl to use that file as +the Alt\-Svc cache to read existing cache contents from and possibly also write +it back to after a transfer, unless \fBCURLALTSVC_READONLYFILE\fP is set in +\fICURLOPT_ALTSVC_CTRL(3)\fP. + +Specify a blank filename ("") to make libcurl not load from a file at all. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL. The alt\-svc cache is not read nor written to file. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, CURLALTSVC_H1); + curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt"); + curl_easy_perform(curl); + } +} +.fi +.SH FILE FORMAT +A text based file with one line per alt\-svc entry and each line consists of +nine space\-separated fields. + +An example line could look like + +.nf +h2 www.example.com 8443 h3 second.example.com 443 "20190808 06:18:37" 1 0 +.fi + +The fields of that line are: +.IP h2 +ALPN id for the source origin +.IP www.example.comp +Hostname for the source origin +.IP 8443 +Port number for the source origin +.IP h3 +ALPN id for the destination host +.IP second.example.com +Hostname for the destination host +.IP 443 +Port number for the destination host +.IP 2019* +Expiration date and time of this entry within double quotes. The date format +is "YYYYMMDD HH:MM:SS" and the time zone is GMT. +.IP 1 +Boolean (1 or 0) if "persist" was set for this entry +.IP 0 +Integer priority value (not currently used) +.SH AVAILABILITY +Added in curl 7.64.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_ALTSVC_CTRL (3), +.BR CURLOPT_CONNECT_TO (3), +.BR CURLOPT_COOKIEFILE (3), +.BR CURLOPT_RESOLVE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_ALTSVC_CTRL.3 b/3rdparty/curl/share/man/man3/CURLOPT_ALTSVC_CTRL.3 new file mode 100644 index 0000000..03f37ab --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_ALTSVC_CTRL.3 @@ -0,0 +1,70 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_ALTSVC_CTRL.md +.TH CURLOPT_ALTSVC_CTRL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_ALTSVC_CTRL \- control alt\-svc behavior +.SH SYNOPSIS +.nf +#include + +#define CURLALTSVC_READONLYFILE (1<<2) +#define CURLALTSVC_H1 (1<<3) +#define CURLALTSVC_H2 (1<<4) +#define CURLALTSVC_H3 (1<<5) + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC_CTRL, long bitmask); +.fi +.SH DESCRIPTION +Populate the long \fIbitmask\fP with the correct set of features to instruct +libcurl how to handle Alt\-Svc for the transfers using this handle. + +libcurl only accepts Alt\-Svc headers over a Secure Transport, meaning +HTTPS. It also only completes a request to an alternative origin if that +origin is properly hosted over HTTPS. These requirements are there to make +sure both the source and the destination are legitimate. + +Alternative services are only used when setting up new connections. If there +exists an existing connection to the host in the connection pool, then that is +preferred. + +If \fICURLOPT_ALTSVC(3)\fP is set, \fICURLOPT_ALTSVC_CTRL(3)\fP gets a default value +corresponding to CURLALTSVC_H1 | CURLALTSVC_H2 | CURLALTSVC_H3 \- the HTTP/2 +and HTTP/3 bits are only set if libcurl was built with support for those +versions. + +Setting any bit enables the alt\-svc engine. +.IP CURLALTSVC_READONLYFILE +Do not write the alt\-svc cache back to the file specified with +\fICURLOPT_ALTSVC(3)\fP even if it gets updated. By default a file specified +with that option is read and written to as deemed necessary. +.IP CURLALTSVC_H1 +Accept alternative services offered over HTTP/1.1. +.IP CURLALTSVC_H2 +Accept alternative services offered over HTTP/2. This is only used if libcurl +was also built to actually support HTTP/2, otherwise this bit is ignored. +.IP CURLALTSVC_H3 +Accept alternative services offered over HTTP/3. This is only used if libcurl +was also built to actually support HTTP/3, otherwise this bit is ignored. +.SH DEFAULT +0 \- Alt\-Svc handling is disabled +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, (long)CURLALTSVC_H1); + curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt"); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.64.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_ALTSVC (3), +.BR CURLOPT_CONNECT_TO (3), +.BR CURLOPT_RESOLVE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_APPEND.3 b/3rdparty/curl/share/man/man3/CURLOPT_APPEND.3 new file mode 100644 index 0000000..c47cc0d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_APPEND.3 @@ -0,0 +1,42 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_APPEND.md +.TH CURLOPT_APPEND 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_APPEND \- append to the remote file +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_APPEND, long append); +.fi +.SH DESCRIPTION +A long parameter set to 1 tells the library to append to the remote file +instead of overwrite it. This is only useful when uploading to an FTP site. +.SH DEFAULT +0 (disabled) +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + curl_easy_setopt(curl, CURLOPT_APPEND, 1L); + + curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +This option was known as CURLOPT_FTPAPPEND up to 7.16.4 +.SH AVAILABILITY +Added in curl 7.17.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_DIRLISTONLY (3), +.BR CURLOPT_RESUME_FROM (3), +.BR CURLOPT_UPLOAD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_AUTOREFERER.3 b/3rdparty/curl/share/man/man3/CURLOPT_AUTOREFERER.3 new file mode 100644 index 0000000..ee3d033 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_AUTOREFERER.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_AUTOREFERER.md +.TH CURLOPT_AUTOREFERER 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_AUTOREFERER \- automatically update the referer header +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AUTOREFERER, long autorefer); +.fi +.SH DESCRIPTION +Pass a long parameter set to 1 to enable this. When enabled, libcurl +automatically sets the Referer: header field in HTTP requests to the full URL +when it follows a Location: redirect to a new destination. + +The automatic referer is set to the full previous URL even when redirects are +done cross\-origin or following redirects to insecure protocols. This is +considered a minor privacy leak by some. + +With \fICURLINFO_REFERER(3)\fP, applications can extract the actually used +referer header after the transfer. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* follow redirects */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + /* set Referer: automatically when following redirects */ + curl_easy_setopt(curl, CURLOPT_AUTOREFERER, 1L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_EFFECTIVE_URL (3), +.BR CURLINFO_REDIRECT_URL (3), +.BR CURLINFO_REFERER (3), +.BR CURLOPT_FOLLOWLOCATION (3), +.BR CURLOPT_REFERER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_AWS_SIGV4.3 b/3rdparty/curl/share/man/man3/CURLOPT_AWS_SIGV4.3 new file mode 100644 index 0000000..f06626a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_AWS_SIGV4.3 @@ -0,0 +1,95 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_AWS_SIGV4.md +.TH CURLOPT_AWS_SIGV4 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_AWS_SIGV4 \- V4 signature +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); +.fi +.SH DESCRIPTION +Provides AWS V4 signature authentication on HTTP(S) header. + +Pass a char pointer that is the collection of specific arguments are used for +creating outgoing authentication headers. The format of the \fIparam\fP option +is: +.IP provider1[:provider2[:region[:service]]] +.IP "provider1, provider2" +The providers arguments are used for generating some authentication parameters +such as "Algorithm", "date", "request type" and "signed headers". +.IP region +The argument is a geographic area of a resources collection. +It is extracted from the hostname specified in the URL if omitted. +.IP service +The argument is a function provided by a cloud. It is extracted from the +hostname specified in the URL if omitted. +.PP +NOTE: This call set \fICURLOPT_HTTPAUTH(3)\fP to CURLAUTH_AWS_SIGV4. Calling +\fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same as calling this with +\fB"aws:amz"\fP in parameter. + +Example with "Test:Try", when curl uses the algorithm, it generates +\fB"TEST\-HMAC\-SHA256"\fP for "Algorithm", \fB"x\-try\-date"\fP and \fB"X\-Try\-Date"\fP +for "date", \fB"test4_request"\fP for "request type", +\fB"SignedHeaders=content\-type;host;x\-try\-date"\fP for "signed headers" + +If you use just "test", instead of "test:try", test is used for every +generated string. + +Setting \fICURLOPT_HTTPAUTH(3)\fP with the CURLAUTH_AWS_SIGV4 bit set is the same as +setting this option with a \fB"aws:amz"\fP parameter. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, + "https://service.region.example.com/uri"); + curl_easy_setopt(curl, CURLOPT_AWS_SIGV4, "provider1:provider2"); + + /* service and region can also be set in CURLOPT_AWS_SIGV4 */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/uri"); + curl_easy_setopt(curl, CURLOPT_AWS_SIGV4, + "provider1:provider2:region:service"); + + curl_easy_setopt(curl, CURLOPT_USERPWD, "MY_ACCESS_KEY:MY_SECRET_KEY"); + curl_easy_perform(curl); + } +} +.fi +.SH NOTES +This option overrides the other auth types you might have set in +\fICURLOPT_HTTPAUTH(3)\fP which should be highlighted as this makes this auth method +special. This method cannot be combined with other auth types. + +A sha256 checksum of the request payload is used as input to the signature +calculation. For POST requests, this is a checksum of the provided +\fICURLOPT_POSTFIELDS(3)\fP. Otherwise, it is the checksum of an empty buffer. For +requests like PUT, you can provide your own checksum in an HTTP header named +\fBx\-provider2\-content\-sha256\fP. + +For \fBaws:s3\fP, a \fBx\-amz\-content\-sha256\fP header is added to every request if +not already present. For s3 requests with unknown payload, this header takes +the special value "UNSIGNED\-PAYLOAD". +.SH AVAILABILITY +Added in curl 7.75.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HEADEROPT (3), +.BR CURLOPT_HTTPAUTH (3), +.BR CURLOPT_HTTPHEADER (3), +.BR CURLOPT_PROXYAUTH (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_BUFFERSIZE.3 b/3rdparty/curl/share/man/man3/CURLOPT_BUFFERSIZE.3 new file mode 100644 index 0000000..7ca0c75 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_BUFFERSIZE.3 @@ -0,0 +1,63 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_BUFFERSIZE.md +.TH CURLOPT_BUFFERSIZE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_BUFFERSIZE \- receive buffer size +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_BUFFERSIZE, long size); +.fi +.SH DESCRIPTION +Pass a long specifying your preferred \fIsize\fP (in bytes) for the receive buffer +in libcurl. The main point of this would be that the write callback gets +called more often and with smaller chunks. Secondly, for some protocols, there +is a benefit of having a larger buffer for performance. + +This is just treated as a request, not an order. You cannot be guaranteed to +actually get the given size. + +This buffer size is by default \fICURL_MAX_WRITE_SIZE\fP (16kB). The maximum +buffer size allowed to be set is \fICURL_MAX_READ_SIZE\fP (10MB). The minimum +buffer size allowed to be set is 1024. + +DO NOT set this option on a handle that is currently used for an active +transfer as that may lead to unintended consequences. + +The maximum size was 512kB until 7.88.0. + +Starting in libcurl 8.7.0, there is just a single transfer buffer allocated +per multi handle. This buffer is used by all easy handles added to a multi +handle no matter how many parallel transfers there are. The buffer remains +allocated as long as there are active transfers. +.SH DEFAULT +CURL_MAX_WRITE_SIZE (16kB) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/foo.bin"); + + /* ask libcurl to allocate a larger receive buffer */ + curl_easy_setopt(curl, CURLOPT_BUFFERSIZE, 120000L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_MAXFILESIZE (3), +.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), +.BR CURLOPT_UPLOAD_BUFFERSIZE (3), +.BR CURLOPT_WRITEFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CAINFO.3 b/3rdparty/curl/share/man/man3/CURLOPT_CAINFO.3 new file mode 100644 index 0000000..82d3de0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CAINFO.3 @@ -0,0 +1,71 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CAINFO.md +.TH CURLOPT_CAINFO 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CAINFO \- path to Certificate Authority (CA) bundle +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAINFO, char *path); +.fi +.SH DESCRIPTION +Pass a char pointer to a null\-terminated string naming a file holding one or +more certificates to verify the peer with. + +If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the +server\(aqs certificate, \fICURLOPT_CAINFO(3)\fP need not even indicate an +accessible file. + +This option is by default set to the system path where libcurl\(aqs CA +certificate bundle is assumed to be stored, as established at build time. + +(iOS and macOS) When curl uses Secure Transport this option is supported. If +the option is not set, then curl uses the certificates in the system and user +Keychain to verify the peer. + +(Schannel) This option is supported for Schannel in Windows 7 or later but we +recommend not using it until Windows 8 since it works better starting then. +If the option is not set, then curl uses the certificates in the Windows\(aq +store of root certificates (the default for Schannel). + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. + +The default value for this can be figured out with \fICURLINFO_CAINFO(3)\fP. +.SH DEFAULT +Built\-in system specific. When curl is built with Secure Transport or +Schannel, this option is not set by default. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_CAINFO, "/etc/certs/cabundle.pem"); + curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +Schannel support added in libcurl 7.60. +.SH AVAILABILITY +Added in curl 7.4.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLINFO_CAINFO (3), +.BR CURLOPT_CAINFO_BLOB (3), +.BR CURLOPT_CAPATH (3), +.BR CURLOPT_CA_CACHE_TIMEOUT (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CAINFO_BLOB.3 b/3rdparty/curl/share/man/man3/CURLOPT_CAINFO_BLOB.3 new file mode 100644 index 0000000..d479bea --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CAINFO_BLOB.3 @@ -0,0 +1,66 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CAINFO_BLOB.md +.TH CURLOPT_CAINFO_BLOB 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CAINFO_BLOB \- Certificate Authority (CA) bundle in PEM format +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAINFO_BLOB, + struct curl_blob *stblob); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_blob structure, which contains information (pointer +and size) about a memory block with binary data of PEM encoded content holding +one or more certificates to verify the HTTPS server with. + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. + +If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the +server\(aqs certificate, \fICURLOPT_CAINFO_BLOB(3)\fP is not needed. + +This option overrides \fICURLOPT_CAINFO(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +BearSSL, OpenSSL, Schannel, Secure Transport, mbedTLS, rustls and wolfSSL +.SH EXAMPLE +.nf +#include + +int main(void) +{ + char *strpem; /* strpem must point to a PEM string */ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob blob; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + blob.data = strpem; + blob.len = strlen(strpem); + blob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_CAINFO_BLOB, &blob); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +This option is supported by the BearSSL (since 7.79.0), mbedTLS (since +7.81.0), Rustls (since 7.82.0), wolfSSL (since 8.2.0), OpenSSL, Secure +Transport and Schannel backends. +.SH AVAILABILITY +Added in curl 7.77.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_CAPATH (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CAPATH.3 b/3rdparty/curl/share/man/man3/CURLOPT_CAPATH.3 new file mode 100644 index 0000000..ad36847 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CAPATH.3 @@ -0,0 +1,63 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CAPATH.md +.TH CURLOPT_CAPATH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CAPATH \- directory holding CA certificates +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAPATH, char *capath); +.fi +.SH DESCRIPTION +Pass a char pointer to a null\-terminated string naming a directory holding +multiple CA certificates to verify the peer with. If libcurl is built against +OpenSSL, the certificate directory must be prepared using the OpenSSL c_rehash +utility. This makes sense only when used in combination with the +\fICURLOPT_SSL_VERIFYPEER(3)\fP option. + +The \fICURLOPT_CAPATH(3)\fP function apparently does not work in Windows due +to some limitation in OpenSSL. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. + +The default value for this can be figured out with \fICURLINFO_CAPATH(3)\fP. +.SH DEFAULT +A path detected at build time. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_CAPATH, "/etc/cert-dir"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.8 +.SH RETURN VALUE +CURLE_OK if supported; or an error such as: + +CURLE_NOT_BUILT_IN \- Not supported by the SSL backend + +CURLE_UNKNOWN_OPTION + +CURLE_OUT_OF_MEMORY +.SH SEE ALSO +.BR CURLINFO_CAPATH (3), +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_STDERR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CA_CACHE_TIMEOUT.3 b/3rdparty/curl/share/man/man3/CURLOPT_CA_CACHE_TIMEOUT.3 new file mode 100644 index 0000000..be8f90d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CA_CACHE_TIMEOUT.3 @@ -0,0 +1,65 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CA_CACHE_TIMEOUT.md +.TH CURLOPT_CA_CACHE_TIMEOUT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CA_CACHE_TIMEOUT \- life\-time for cached certificate stores +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CA_CACHE_TIMEOUT, long age); +.fi +.SH DESCRIPTION +Pass a long, this sets the timeout in seconds. This tells libcurl the maximum +time any cached CA certificate store it has in memory may be kept and reused +for new connections. Once the timeout has expired, a subsequent fetch +requiring a CA certificate has to reload it. + +Building a CA certificate store from a \fICURLOPT_CAINFO(3)\fP file is a slow +operation so curl may cache the generated certificate store internally to +speed up future connections. + +Set the timeout to zero to completely disable caching, or set to \-1 to retain +the cached store remain forever. By default, libcurl caches this info for 24 +hours. +.SH DEFAULT +86400 (24 hours) +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, Schannel and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* only reuse certificate stores for a short time */ + curl_easy_setopt(curl, CURLOPT_CA_CACHE_TIMEOUT, 60L); + + res = curl_easy_perform(curl); + + /* in this second request, the cache is not used if more than + sixty seconds passed since the previous connection */ + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +This option is supported by OpenSSL and its forks (since 7.87.0), Schannel +(since 8.5.0), wolfSSL (since 8.9.0) and GnuTLS (since 8.9.0). +.SH AVAILABILITY +Added in curl 7.87.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_CAINFO_BLOB (3), +.BR CURLOPT_CAPATH (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CERTINFO.3 b/3rdparty/curl/share/man/man3/CURLOPT_CERTINFO.3 new file mode 100644 index 0000000..7faba54 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CERTINFO.3 @@ -0,0 +1,73 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CERTINFO.md +.TH CURLOPT_CERTINFO 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CERTINFO \- request SSL certificate information +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CERTINFO, long certinfo); +.fi +.SH DESCRIPTION +Pass a long set to 1 to enable libcurl\(aqs certificate chain info gatherer. With +this enabled, libcurl extracts lots of information and data about the +certificates in the certificate chain used in the SSL connection. This data +may then be retrieved after a transfer using \fIcurl_easy_getinfo(3)\fP and +its option \fICURLINFO_CERTINFO(3)\fP. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, Schannel and Secure Transport +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); + + /* connect to any HTTPS site, trusted or not */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); + + curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L); + + res = curl_easy_perform(curl); + + if(!res) { + struct curl_certinfo *ci; + res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci); + + if(!res) { + int i; + printf("%d certs!\\n", ci->num_of_certs); + + for(i = 0; i < ci->num_of_certs; i++) { + struct curl_slist *slist; + + for(slist = ci->certinfo[i]; slist; slist = slist->next) + printf("%s\\n", slist->data); + } + } + } + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +Schannel support added in 7.50.0. Secure Transport support added in 7.79.0. +mbedTLS support added in 8.9.0. +.SH AVAILABILITY +Added in curl 7.19.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CAINFO (3), +.BR CURLINFO_CAPATH (3), +.BR CURLINFO_CERTINFO (3), +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CHUNK_BGN_FUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_CHUNK_BGN_FUNCTION.3 new file mode 100644 index 0000000..f09d912 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CHUNK_BGN_FUNCTION.3 @@ -0,0 +1,131 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CHUNK_BGN_FUNCTION.md +.TH CURLOPT_CHUNK_BGN_FUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CHUNK_BGN_FUNCTION \- callback before a transfer with FTP wildcard match +.SH SYNOPSIS +.nf +#include + +struct curl_fileinfo { + char *filename; + curlfiletype filetype; + time_t time; /* always zero! */ + unsigned int perm; + int uid; + int gid; + curl_off_t size; + long int hardlinks; + + struct { + /* If some of these fields is not NULL, it is a pointer to b_data. */ + char *time; + char *perm; + char *user; + char *group; + char *target; /* pointer to the target filename of a symlink */ + } strings; + + unsigned int flags; + + /* used internally */ + char *b_data; + size_t b_size; + size_t b_used; +}; + +long chunk_bgn_callback(const void *transfer_info, void *ptr, + int remains); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_BGN_FUNCTION, + chunk_bgn_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl before a part of the stream is +going to be transferred (if the transfer supports chunks). + +The \fItransfer_info\fP pointer points to a \fBcurl_fileinfo\fP struct with +details about the file that is about to get transferred. + +This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH(3)\fP +option for now. + +The target of transfer_info parameter is a "feature depended" structure. For +the FTP wildcard download, the target is \fBcurl_fileinfo\fP structure (see +\fIcurl/curl.h\fP). The parameter \fIptr\fP is a pointer given by +\fICURLOPT_CHUNK_DATA(3)\fP. The parameter remains contains number of chunks +remaining per the transfer. If the feature is not available, the parameter has +zero value. + +Return \fICURL_CHUNK_BGN_FUNC_OK\fP if everything is fine, +\fICURL_CHUNK_BGN_FUNC_SKIP\fP if you want to skip the concrete chunk or +\fICURL_CHUNK_BGN_FUNC_FAIL\fP to tell libcurl to stop if some error occurred. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +#include + +struct callback_data { + FILE *output; +}; + +static long file_is_coming(struct curl_fileinfo *finfo, + void *ptr, + int remains) +{ + struct callback_data *data = ptr; + printf("%3d %40s %10luB ", remains, finfo->filename, + (unsigned long)finfo->size); + + switch(finfo->filetype) { + case CURLFILETYPE_DIRECTORY: + printf(" DIR\\n"); + break; + case CURLFILETYPE_FILE: + printf("FILE "); + break; + default: + printf("OTHER\\n"); + break; + } + + if(finfo->filetype == CURLFILETYPE_FILE) { + /* do not transfer files >= 50B */ + if(finfo->size > 50) { + printf("SKIPPED\\n"); + return CURL_CHUNK_BGN_FUNC_SKIP; + } + + data->output = fopen(finfo->filename, "wb"); + if(!data->output) { + return CURL_CHUNK_BGN_FUNC_FAIL; + } + } + + return CURL_CHUNK_BGN_FUNC_OK; +} + +int main() +{ + /* data for callback */ + struct callback_data callback_info; + + CURL *curl = curl_easy_init(); + + /* callback is called before download of concrete file started */ + curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming); + curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info); +} +.fi +.SH AVAILABILITY +Added in curl 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CHUNK_END_FUNCTION (3), +.BR CURLOPT_WILDCARDMATCH (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CHUNK_DATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_CHUNK_DATA.3 new file mode 100644 index 0000000..7ffa048 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CHUNK_DATA.3 @@ -0,0 +1,81 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CHUNK_DATA.md +.TH CURLOPT_CHUNK_DATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CHUNK_DATA \- pointer passed to the FTP chunk callbacks +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_DATA, void *pointer); +.fi +.SH DESCRIPTION +Pass a \fIpointer\fP that is untouched by libcurl and passed as the ptr +argument to the \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP and +\fICURLOPT_CHUNK_END_FUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +#include + +struct callback_data { + FILE *output; +}; + +static long file_is_coming(struct curl_fileinfo *finfo, + void *ptr, + int remains) +{ + struct callback_data *data = ptr; + printf("%3d %40s %10luB ", remains, finfo->filename, + (unsigned long)finfo->size); + + switch(finfo->filetype) { + case CURLFILETYPE_DIRECTORY: + printf(" DIR\\n"); + break; + case CURLFILETYPE_FILE: + printf("FILE "); + break; + default: + printf("OTHER\\n"); + break; + } + + if(finfo->filetype == CURLFILETYPE_FILE) { + /* do not transfer files >= 50B */ + if(finfo->size > 50) { + printf("SKIPPED\\n"); + return CURL_CHUNK_BGN_FUNC_SKIP; + } + + data->output = fopen(finfo->filename, "wb"); + if(!data->output) { + return CURL_CHUNK_BGN_FUNC_FAIL; + } + } + + return CURL_CHUNK_BGN_FUNC_OK; +} + +int main() +{ + /* data for callback */ + struct callback_data callback_info; + + CURL *curl = curl_easy_init(); + + /* callback is called before download of concrete file started */ + curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming); + curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info); +} +.fi +.SH AVAILABILITY +Added in curl 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CHUNK_BGN_FUNCTION (3), +.BR CURLOPT_WILDCARDMATCH (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CHUNK_END_FUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_CHUNK_END_FUNCTION.3 new file mode 100644 index 0000000..b0dd15b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CHUNK_END_FUNCTION.3 @@ -0,0 +1,61 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CHUNK_END_FUNCTION.md +.TH CURLOPT_CHUNK_END_FUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CHUNK_END_FUNCTION \- callback after a transfer with FTP wildcard match +.SH SYNOPSIS +.nf +#include + +long chunk_end_callback(void *ptr); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_END_FUNCTION, + chunk_end_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This function gets called by libcurl as soon as a part of the stream has been +transferred (or skipped). + +Return \fICURL_CHUNK_END_FUNC_OK\fP if everything is fine or +\fBCURL_CHUNK_END_FUNC_FAIL\fP to tell the lib to stop if some error occurred. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +#include + +struct callback_data { + FILE *output; +}; + +static long file_is_downloaded(struct callback_data *data) +{ + if(data->output) { + fclose(data->output); + data->output = 0x0; + } + return CURL_CHUNK_END_FUNC_OK; +} + +int main() +{ + /* data for callback */ + struct callback_data callback_info; + + CURL *curl = curl_easy_init(); + + curl_easy_setopt(curl, CURLOPT_CHUNK_END_FUNCTION, file_is_downloaded); + curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info); +} +.fi +.SH AVAILABILITY +Added in curl 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CHUNK_BGN_FUNCTION (3), +.BR CURLOPT_WILDCARDMATCH (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CLOSESOCKETDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_CLOSESOCKETDATA.3 new file mode 100644 index 0000000..4c96a66 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CLOSESOCKETDATA.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CLOSESOCKETDATA.md +.TH CURLOPT_CLOSESOCKETDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CLOSESOCKETDATA \- pointer passed to the socket close callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETDATA, + void *pointer); +.fi +.SH DESCRIPTION +Pass a \fIpointer\fP that remains untouched by libcurl and passed as the first +argument in the closesocket callback set with +\fICURLOPT_CLOSESOCKETFUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct priv { + void *custom; +}; + +static int closesocket(void *clientp, curl_socket_t item) +{ + struct priv *my = clientp; + printf("our ptr: %p\\n", my->custom); + + printf("libcurl wants to close %d now\\n", (int)item); + return 0; +} + +int main(void) +{ + struct priv myown; + CURL *curl = curl_easy_init(); + + /* call this function to close sockets */ + curl_easy_setopt(curl, CURLOPT_CLOSESOCKETFUNCTION, closesocket); + curl_easy_setopt(curl, CURLOPT_CLOSESOCKETDATA, &myown); + + curl_easy_perform(curl); + curl_easy_cleanup(curl); +} +.fi +.SH AVAILABILITY +Added in curl 7.21.7 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CLOSESOCKETFUNCTION (3), +.BR CURLOPT_OPENSOCKETFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CLOSESOCKETFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_CLOSESOCKETFUNCTION.3 new file mode 100644 index 0000000..b63b360 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CLOSESOCKETFUNCTION.3 @@ -0,0 +1,65 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CLOSESOCKETFUNCTION.md +.TH CURLOPT_CLOSESOCKETFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CLOSESOCKETFUNCTION \- callback to socket close replacement +.SH SYNOPSIS +.nf +#include + +int closesocket_callback(void *clientp, curl_socket_t item); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETFUNCTION, + closesocket_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl instead of the \fIclose(3)\fP or +\fIclosesocket(3)\fP call when sockets are closed (not for any other file +descriptors). This is pretty much the reverse to the +\fICURLOPT_OPENSOCKETFUNCTION(3)\fP option. Return 0 to signal success and 1 +if there was an error. + +The \fIclientp\fP pointer is set with +\fICURLOPT_CLOSESOCKETDATA(3)\fP. \fIitem\fP is the socket libcurl wants to be +closed. +.SH DEFAULT +Use the standard socket close function. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct priv { + void *custom; +}; + +static int closesocket(void *clientp, curl_socket_t item) +{ + struct priv *my = clientp; + printf("our ptr: %p\\n", my->custom); + + printf("libcurl wants to close %d now\\n", (int)item); + return 0; +} + +int main(void) +{ + struct priv myown; + CURL *curl = curl_easy_init(); + + /* call this function to close sockets */ + curl_easy_setopt(curl, CURLOPT_CLOSESOCKETFUNCTION, closesocket); + curl_easy_setopt(curl, CURLOPT_CLOSESOCKETDATA, &myown); + + curl_easy_perform(curl); + curl_easy_cleanup(curl); +} +.fi +.SH AVAILABILITY +Added in curl 7.21.7 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CLOSESOCKETDATA (3), +.BR CURLOPT_OPENSOCKETFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CONNECTTIMEOUT.3 b/3rdparty/curl/share/man/man3/CURLOPT_CONNECTTIMEOUT.3 new file mode 100644 index 0000000..cc1febb --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CONNECTTIMEOUT.3 @@ -0,0 +1,67 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CONNECTTIMEOUT.md +.TH CURLOPT_CONNECTTIMEOUT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CONNECTTIMEOUT \- timeout for the connect phase +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT, long timeout); +.fi +.SH DESCRIPTION +Pass a long. It sets the maximum time in seconds that you allow the connection +phase to take. This timeout only limits the connection phase, it has no impact +once libcurl has connected. The connection phase includes the name resolve +(DNS) and all protocol handshakes and negotiations until there is an +established connection with the remote side. + +Set this option to zero to switch to the default built\-in connection timeout \- +300 seconds. See also the \fICURLOPT_TIMEOUT(3)\fP option. + +\fICURLOPT_CONNECTTIMEOUT_MS(3)\fP is the same function but set in milliseconds. + +If both \fICURLOPT_CONNECTTIMEOUT(3)\fP and \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP +are set, the value set last is used. + +The connection timeout is included in the general all\-covering +\fICURLOPT_TIMEOUT(3)\fP: + +With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 3 and \fICURLOPT_TIMEOUT(3)\fP set +to 5, the operation can never last longer than 5 seconds, and the connection +phase cannot last longer than 3 seconds. + +With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 4 and \fICURLOPT_TIMEOUT(3)\fP set +to 2, the operation can never last longer than 2 seconds. Including the +connection phase. + +This option may cause libcurl to use the SIGALRM signal to timeout system +calls on builds not using asynch DNS. In Unix\-like systems, this might cause +signals to be used unless \fICURLOPT_NOSIGNAL(3)\fP is set. +.SH DEFAULT +300 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* complete connection within 10 seconds */ + curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 10L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.7 +.SH RETURN VALUE +Returns CURLE_OK. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative +value or a value that when converted to milliseconds is too large. +.SH SEE ALSO +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CONNECTTIMEOUT_MS.3 b/3rdparty/curl/share/man/man3/CURLOPT_CONNECTTIMEOUT_MS.3 new file mode 100644 index 0000000..c7fc37f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CONNECTTIMEOUT_MS.3 @@ -0,0 +1,67 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CONNECTTIMEOUT_MS.md +.TH CURLOPT_CONNECTTIMEOUT_MS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CONNECTTIMEOUT_MS \- timeout for the connect phase +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT_MS, + long timeout); +.fi +.SH DESCRIPTION +Pass a long. It sets the maximum time in milliseconds that you allow the +connection phase to take. This timeout only limits the connection phase, it +has no impact once libcurl has connected. The connection phase includes the +name resolve (DNS) and all protocol handshakes and negotiations until there is +an established connection with the remote side. + +Set this option to zero to switch to the default built\-in connection timeout \- +300 seconds. See also the \fICURLOPT_TIMEOUT_MS(3)\fP option. + +\fICURLOPT_CONNECTTIMEOUT(3)\fP is the same function but set in seconds. + +If both \fICURLOPT_CONNECTTIMEOUT(3)\fP and \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP are set, +the value set last is used. + +The connection timeout is included in the general all\-covering +\fICURLOPT_TIMEOUT_MS(3)\fP: + +With \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP set to 3000 and \fICURLOPT_TIMEOUT_MS(3)\fP set to +5000, the operation can never last longer than 5000 milliseconds, and the +connection phase cannot last longer than 3000 milliseconds. + +With \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP set to 4000 and \fICURLOPT_TIMEOUT_MS(3)\fP set to +2000, the operation can never last longer than 2000 milliseconds. Including +the connection phase. + +This option may cause libcurl to use the SIGALRM signal to timeout system +calls on builds not using asynch DNS. In Unix\-like systems, this might cause +signals to be used unless \fICURLOPT_NOSIGNAL(3)\fP is set. +.SH DEFAULT +300000 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* complete connection within 10000 milliseconds */ + curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT_MS, 10000L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.2 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), +.BR CURLOPT_TIMEOUT_MS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CONNECT_ONLY.3 b/3rdparty/curl/share/man/man3/CURLOPT_CONNECT_ONLY.3 new file mode 100644 index 0000000..d69e088 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CONNECT_ONLY.3 @@ -0,0 +1,64 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CONNECT_ONLY.md +.TH CURLOPT_CONNECT_ONLY 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CONNECT_ONLY \- stop when connected to target server +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_ONLY, long only); +.fi +.SH DESCRIPTION +Pass a long. If the parameter equals 1, it tells the library to perform all +the required proxy authentication and connection setup, but no data transfer, +and then return. + +The option can be used to simply test a connection to a server, but is more +useful when used with the \fICURLINFO_ACTIVESOCKET(3)\fP option to +\fIcurl_easy_getinfo(3)\fP as the library can set up the connection and then +the application can obtain the most recently used socket for special data +transfers. + +Since 7.86.0, this option can be set to \(aq2\(aq and if HTTP or WebSocket are used, +libcurl performs the request and reads all response headers before handing +over control to the application. + +Transfers marked connect only do not reuse any existing connections and +connections marked connect only are not allowed to get reused. + +If the connect only transfer is done using the multi interface, the particular +easy handle must remain added to the multi handle for as long as the +application wants to use it. Once it has been removed with +\fIcurl_multi_remove_handle(3)\fP, \fIcurl_easy_send(3)\fP and +\fIcurl_easy_recv(3)\fP do not function. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); + ret = curl_easy_perform(curl); + if(ret == CURLE_OK) { + /* only connected! */ + } + } +} +.fi +.SH HISTORY +WS and WSS support added in 7.86.0. +.SH AVAILABILITY +Added in curl 7.15.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTPPROXYTUNNEL (3), +.BR CURLOPT_VERBOSE (3), +.BR curl_easy_recv (3), +.BR curl_easy_send (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CONNECT_TO.3 b/3rdparty/curl/share/man/man3/CURLOPT_CONNECT_TO.3 new file mode 100644 index 0000000..32b996f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CONNECT_TO.3 @@ -0,0 +1,96 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CONNECT_TO.md +.TH CURLOPT_CONNECT_TO 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CONNECT_TO \- connect to another host and port instead +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_TO, + struct curl_slist *connect_to); +.fi +.SH DESCRIPTION +Pass a pointer to a linked list of strings with "connect to" information to +use for establishing network connections with this handle. The linked list +should be a fully valid list of \fBstruct curl_slist\fP structs properly filled +in. Use \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to +clean up an entire list. + +Each single string should be written using the format +HOST:PORT:CONNECT\-TO\-HOST:CONNECT\-TO\-PORT where HOST is the host of the +request, PORT is the port of the request, CONNECT\-TO\-HOST is the hostname to +connect to, and CONNECT\-TO\-PORT is the port to connect to. + +The first string that matches the request\(aqs host and port is used. + +Dotted numerical IP addresses are supported for HOST and CONNECT\-TO\-HOST. +A numerical IPv6 address must be written within [brackets]. + +Any of the four values may be empty. When the HOST or PORT is empty, the host +or port always match (the request\(aqs host or port is ignored). When +CONNECT\-TO\-HOST or CONNECT\-TO\-PORT is empty, the "connect to" feature is +disabled for the host or port, and the request\(aqs host or port are used to +establish the network connection. + +This option is suitable to direct the request at a specific server, e.g. at a +specific cluster node in a cluster of servers. + +The "connect to" host and port are only used to establish the network +connection. They do NOT affect the host and port that are used for TLS/SSL +(e.g. SNI, certificate verification) or for the application protocols. + +In contrast to \fICURLOPT_RESOLVE(3)\fP, the option \fICURLOPT_CONNECT_TO(3)\fP does not +pre\-populate the DNS cache and therefore it does not affect future transfers +of other easy handles that have been added to the same multi handle. + +The "connect to" host and port are ignored if they are equal to the host and +the port in the request URL, because connecting to the host and the port in +the request URL is the default behavior. + +If an HTTP proxy is used for a request having a special "connect to" host or +port, and the "connect to" host or port differs from the request\(aqs host and +port, the HTTP proxy is automatically switched to tunnel mode for this +specific request. This is necessary because it is not possible to connect to a +specific host or port in normal (non\-tunnel) mode. + +When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl does not copy the +list so you \fBmust\fP keep it around until you no longer use this \fIhandle\fP for +a transfer before you call \fIcurl_slist_free_all(3)\fP on the list. + +Using this option multiple times makes the last set list override the previous +ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl; + struct curl_slist *connect_to = NULL; + connect_to = curl_slist_append(NULL, "example.com::server1.example.com:"); + + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_CONNECT_TO, connect_to); + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } + + curl_slist_free_all(connect_to); +} +.fi +.SH AVAILABILITY +Added in curl 7.49.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FOLLOWLOCATION (3), +.BR CURLOPT_HTTPPROXYTUNNEL (3), +.BR CURLOPT_RESOLVE (3), +.BR CURLOPT_URL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 new file mode 100644 index 0000000..855506f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 @@ -0,0 +1,95 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CONV_FROM_NETWORK_FUNCTION.md +.TH CURLOPT_CONV_FROM_NETWORK_FUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CONV_FROM_NETWORK_FUNCTION \- convert data from network to host encoding +.SH SYNOPSIS +.nf +#include + +CURLcode conv_callback(char *ptr, size_t length); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_NETWORK_FUNCTION, + conv_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +Applies to non\-ASCII platforms. \fIcurl_version_info(3)\fP returns the +\fBCURL_VERSION_CONV\fP feature bit set if this option is provided. + +The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. +The amount of data to convert is indicated by the \fIlength\fP parameter. The +converted data overlays the input data in the buffer pointed to by the ptr +parameter. \fICURLE_OK\fP must be returned upon successful conversion. A +CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, +should be returned if an error was encountered. + +\fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP converts to host encoding from the +network encoding. It is used when commands or ASCII data are received over the +network. + +If you set a callback pointer to NULL, or do not set it at all, the built\-in +libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl +was built, and no callback has been established, the conversion returns the +\fBCURLE_CONV_REQD\fP error code. + +If \fBHAVE_ICONV\fP is defined, \fBCURL_ICONV_CODESET_OF_HOST\fP must also be +defined. For example: + +.nf +#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" +.fi + +The iconv code in libcurl defaults the network and UTF8 codeset names as +follows: + +.nf +#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" + +#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" +.fi + +You need to override these definitions if they are different on your system. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +static CURLcode my_conv_from_ascii_to_ebcdic(char *buffer, size_t length) +{ + int rc = 0; + + /* in-place convert 'buffer' from ASCII to EBCDIC */ + + if(rc == 0) { + /* success */ + return CURLE_OK; + } + else { + return CURLE_CONV_FAILED; + } +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + + /* use platform-specific functions for codeset conversions */ + curl_easy_setopt(curl, CURLOPT_CONV_FROM_NETWORK_FUNCTION, + my_conv_from_ascii_to_ebcdic); +} +.fi +.SH DEPRECATED +Not available and deprecated since 7.82.0. + +Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was +built. +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CONV_FROM_UTF8_FUNCTION (3), +.BR CURLOPT_CONV_TO_NETWORK_FUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 new file mode 100644 index 0000000..bd53f6b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 @@ -0,0 +1,88 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CONV_FROM_UTF8_FUNCTION.md +.TH CURLOPT_CONV_FROM_UTF8_FUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CONV_FROM_UTF8_FUNCTION \- convert data from UTF8 to host encoding +.SH SYNOPSIS +.nf +#include + +CURLcode conv_callback(char *ptr, size_t length); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_UTF8_FUNCTION, + conv_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +Applies to non\-ASCII platforms. \fIcurl_version_info(3)\fP returns the +CURL_VERSION_CONV feature bit set if this option is provided. + +The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. +The amount of data to convert is indicated by the \fIlength\fP parameter. The +converted data overlays the input data in the buffer pointed to by the ptr +parameter. \fICURLE_OK\fP must be returned upon successful conversion. A +CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, +should be returned if an error was encountered. + +\fICURLOPT_CONV_FROM_UTF8_FUNCTION(3)\fP converts to host encoding from UTF8 +encoding. It is required only for SSL processing. + +If you set a callback pointer to NULL, or do not set it at all, the built\-in +libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl +was built, and no callback has been established, the conversion returns the +CURLE_CONV_REQD error code. + +If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. +For example: +.nf + #define CURL_ICONV_CODESET_OF_HOST "IBM-1047" +.fi + +The iconv code in libcurl defaults the network and UTF8 codeset names as +follows: +.nf +#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" + +#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" +.fi + +You need to override these definitions if they are different on your system. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +static CURLcode my_conv_from_utf8_to_ebcdic(char *buffer, size_t length) +{ + int rc = 0; + /* in-place convert 'buffer' from UTF-8 to EBCDIC */ + if(rc == 0) { + /* success */ + return CURLE_OK; + } + else { + return CURLE_CONV_FAILED; + } +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + curl_easy_setopt(curl, CURLOPT_CONV_FROM_UTF8_FUNCTION, + my_conv_from_utf8_to_ebcdic); +} +.fi +.SH DEPRECATED +Not available and deprecated since 7.82.0. + +Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was +built. +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CONV_FROM_NETWORK_FUNCTION (3), +.BR CURLOPT_CONV_TO_NETWORK_FUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 new file mode 100644 index 0000000..06c529a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 @@ -0,0 +1,91 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CONV_TO_NETWORK_FUNCTION.md +.TH CURLOPT_CONV_TO_NETWORK_FUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CONV_TO_NETWORK_FUNCTION \- convert data to network from host encoding +.SH SYNOPSIS +.nf +#include + +CURLcode conv_callback(char *ptr, size_t length); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_TO_NETWORK_FUNCTION, + conv_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +Applies to non\-ASCII platforms. \fIcurl_version_info(3)\fP returns the +CURL_VERSION_CONV feature bit set if this option is provided. + +The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. +The amount of data to convert is indicated by the \fIlength\fP parameter. The +converted data overlays the input data in the buffer pointed to by the ptr +parameter. \fICURLE_OK\fP must be returned upon successful conversion. A CURLcode +return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, should be +returned if an error was encountered. + +\fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP converts from host encoding to the +network encoding. It is used when commands or ASCII data are sent over the +network. + +If you set a callback pointer to NULL, or do not set it at all, the built\-in +libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl +was built, and no callback has been established, the conversion returns the +CURLE_CONV_REQD error code. + +If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. +For example: +.nf +define CURL_ICONV_CODESET_OF_HOST "IBM-1047" +.fi + +The iconv code in libcurl defaults the network and UTF8 codeset names as +follows: + +.nf +#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" + +#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" +.fi + +You need to override these definitions if they are different on your system. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +static CURLcode my_conv_from_ebcdic_to_ascii(char *buffer, size_t length) +{ + int rc = 0; + /* in-place convert 'buffer' from EBCDIC to ASCII */ + if(rc == 0) { + /* success */ + return CURLE_OK; + } + else { + return CURLE_CONV_FAILED; + } +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + + curl_easy_setopt(curl, CURLOPT_CONV_TO_NETWORK_FUNCTION, + my_conv_from_ebcdic_to_ascii); +} +.fi +.SH DEPRECATED +Not available and deprecated since 7.82.0. + +Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was +built. +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CONV_FROM_NETWORK_FUNCTION (3), +.BR CURLOPT_CONV_FROM_UTF8_FUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_COOKIE.3 b/3rdparty/curl/share/man/man3/CURLOPT_COOKIE.3 new file mode 100644 index 0000000..7e24a67 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_COOKIE.3 @@ -0,0 +1,73 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_COOKIE.md +.TH CURLOPT_COOKIE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_COOKIE \- HTTP Cookie header +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIE, char *cookie); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. It is used to set one +or more cookies in the HTTP request. The format of the string should be +NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie +should contain. + +To set multiple cookies, set them all using a single option concatenated like +this: "name1=content1; name2=content2;" etc. libcurl does not syntax check the +data but assumes the application gives it what it needs to send. + +This option sets the cookie header explicitly in the outgoing request(s). If +multiple requests are done due to authentication, followed redirections or +similar, they all get this cookie passed on. + +The cookies set by this option are separate from the internal cookie storage +held by the cookie engine and they are not be modified by it. If you enable +the cookie engine and either you have imported a cookie of the same name (e.g. +\(aqfoo\(aq) or the server has set one, it has no effect on the cookies you set +here. A request to the server sends both the \(aqfoo\(aq held by the cookie engine +and the \(aqfoo\(aq held by this option. To set a cookie that is instead held by the +cookie engine and can be modified by the server use \fICURLOPT_COOKIELIST(3)\fP. + +Since this custom cookie is appended to the Cookie: header in addition to any +cookies set by the cookie engine, there is a risk that the header ends up too +long and thereby getting the entire request rejected by the server. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. + +This option does not enable the cookie engine. Use \fICURLOPT_COOKIEFILE(3)\fP or +\fICURLOPT_COOKIEJAR(3)\fP to enable parsing and sending cookies automatically. +.SH DEFAULT +NULL, no cookies +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_COOKIE, "tool=curl; fun=yes;"); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLINFO_COOKIELIST (3), +.BR CURLOPT_COOKIEFILE (3), +.BR CURLOPT_COOKIEJAR (3), +.BR CURLOPT_COOKIELIST (3), +.BR CURLOPT_HTTPHEADER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_COOKIEFILE.3 b/3rdparty/curl/share/man/man3/CURLOPT_COOKIEFILE.3 new file mode 100644 index 0000000..ee0e229 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_COOKIEFILE.3 @@ -0,0 +1,76 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_COOKIEFILE.md +.TH CURLOPT_COOKIEFILE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_COOKIEFILE \- filename to read cookies from +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEFILE, char *filename); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. It should point to +the filename of your file holding cookie data to read. The cookie data can be +in either the old Netscape / Mozilla cookie data format or just regular HTTP +headers (Set\-Cookie style) dumped to a file. + +It also enables the cookie engine, making libcurl parse and send cookies on +subsequent requests with this handle. + +By passing the empty string ("") to this option, you enable the cookie engine +without reading any initial cookies. If you tell libcurl the filename is "\-" +(just a single minus sign), libcurl instead reads from stdin. + +This option only \fBreads\fP cookies. To make libcurl write cookies to file, +see \fICURLOPT_COOKIEJAR(3)\fP. + +If you read cookies from a plain HTTP headers file and it does not specify a +domain in the Set\-Cookie line, then the cookie is not sent since the cookie +domain cannot match the target URL\(aqs. To address this, set a domain in +Set\-Cookie line (doing that includes subdomains) or preferably: use the +Netscape format. + +The application does not have to keep the string around after setting this +option. + +If you use this option multiple times, you add more files to read cookies +from. Setting this option to NULL disables the cookie engine and clears the +list of files to read cookies from. +.SH SECURITY +This document previously mentioned how specifying a non\-existing file can also +enable the cookie engine. While true, we strongly advise against using that +method as it is too hard to be sure that files that stay that way in the long +run. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* get cookies from an existing file */ + curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "/tmp/cookies.txt"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH Cookie file format +The cookie file format and general cookie concepts in curl are described +online here: https://curl.se/docs/http\-cookies.html +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_COOKIE (3), +.BR CURLOPT_COOKIEJAR (3), +.BR CURLOPT_COOKIESESSION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_COOKIEJAR.3 b/3rdparty/curl/share/man/man3/CURLOPT_COOKIEJAR.3 new file mode 100644 index 0000000..fe02c6d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_COOKIEJAR.3 @@ -0,0 +1,67 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_COOKIEJAR.md +.TH CURLOPT_COOKIEJAR 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_COOKIEJAR \- filename to store cookies to +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEJAR, char *filename); +.fi +.SH DESCRIPTION +Pass a \fIfilename\fP as a char *, null\-terminated. This makes libcurl write all +internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP is +called. If no cookies are kept in memory at that time, no file is created. +Specify "\-" as filename to instead have the cookies written to stdout. Using +this option also enables cookies for this session, so if you for example +follow a redirect it makes matching cookies get sent accordingly. + +Note that libcurl does not read any cookies from the cookie jar specified with +this option. To read cookies from a file, use \fICURLOPT_COOKIEFILE(3)\fP. + +If the cookie jar file cannot be created or written to (when the +\fIcurl_easy_cleanup(3)\fP is called), libcurl does not and cannot report an error +for this. Using \fICURLOPT_VERBOSE(3)\fP or \fICURLOPT_DEBUGFUNCTION(3)\fP displays a +warning, but that is the only visible feedback you get about this possibly +lethal situation. + +Cookies are imported in the Set\-Cookie format without a domain name are not +exported by this option. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* export cookies to this file when closing the handle */ + curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "/tmp/cookies.txt"); + + res = curl_easy_perform(curl); + + /* close the handle, write the cookies! */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_COOKIE (3), +.BR CURLOPT_COOKIEFILE (3), +.BR CURLOPT_COOKIELIST (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_COOKIELIST.3 b/3rdparty/curl/share/man/man3/CURLOPT_COOKIELIST.3 new file mode 100644 index 0000000..58230e7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_COOKIELIST.3 @@ -0,0 +1,107 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_COOKIELIST.md +.TH CURLOPT_COOKIELIST 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_COOKIELIST \- add to or manipulate cookies held in memory +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST, + char *cookie); +.fi +.SH DESCRIPTION +Pass a char pointer to a \fIcookie\fP string. + +Such a cookie can be either a single line in Netscape / Mozilla format or just +regular HTTP\-style header (\fISet\-Cookie:\fP) format. This option also enables the +cookie engine. This adds that single cookie to the internal cookie store. + +We strongly advice against loading cookies from an HTTP header file, as that +is an inferior data exchange format. + +Exercise caution if you are using this option and multiple transfers may +occur. If you use the \fISet\-Cookie\fP format and the string does not specify a +domain, then the cookie is sent for any domain (even after redirects are +followed) and cannot be modified by a server\-set cookie. If a server sets a +cookie of the same name (or maybe you have imported one) then both are sent on +future transfers to that server, likely not what you intended. To address +these issues set a domain in \fISet\-Cookie\fP (doing that includes subdomains) or +much better: use the Netscape file format. + +Additionally, there are commands available that perform actions if you pass in +these exact strings: +.IP ALL +erases all cookies held in memory +.IP SESS +erases all session cookies held in memory +.IP FLUSH +writes all known cookies to the file specified by \fICURLOPT_COOKIEJAR(3)\fP +.IP RELOAD +loads all cookies from the files specified by \fICURLOPT_COOKIEFILE(3)\fP +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +/* an inline import of a cookie in Netscape format. */ + +#define SEP "\\t" /* Tab separates the fields */ + +int main(void) +{ + char *my_cookie = + "example.com" /* Hostname */ + SEP "FALSE" /* Include subdomains */ + SEP "/" /* Path */ + SEP "FALSE" /* Secure */ + SEP "0" /* Expiry in epoch time format. 0 == Session */ + SEP "foo" /* Name */ + SEP "bar"; /* Value */ + + CURL *curl = curl_easy_init(); + if(curl) { + /* my_cookie is imported immediately via CURLOPT_COOKIELIST. */ + curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie); + + /* The list of cookies in cookies.txt are not be imported until right + before a transfer is performed. Cookies in the list that have the same + hostname, path and name as in my_cookie are skipped. That is because + libcurl has already imported my_cookie and it's considered a "live" + cookie. A live cookie is not replaced by one read from a file. + */ + curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt"); /* import */ + + /* Cookies are exported after curl_easy_cleanup is called. The server + may have added, deleted or modified cookies by then. The cookies that + were skipped on import are not exported. + */ + curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt"); /* export */ + + curl_easy_perform(curl); /* cookies imported from cookies.txt */ + + curl_easy_cleanup(curl); /* cookies exported to cookies.txt */ + } +} +.fi +.SH Cookie file format +The cookie file format and general cookie concepts in curl are described +online here: https://curl.se/docs/http\-cookies.html +.SH HISTORY +\fBALL\fP was added in 7.14.1 + +\fBSESS\fP was added in 7.15.4 + +\fBFLUSH\fP was added in 7.17.1 + +\fBRELOAD\fP was added in 7.39.0 +.SH AVAILABILITY +Added in curl 7.14.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLINFO_COOKIELIST (3), +.BR CURLOPT_COOKIE (3), +.BR CURLOPT_COOKIEFILE (3), +.BR CURLOPT_COOKIEJAR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_COOKIESESSION.3 b/3rdparty/curl/share/man/man3/CURLOPT_COOKIESESSION.3 new file mode 100644 index 0000000..f405863 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_COOKIESESSION.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_COOKIESESSION.md +.TH CURLOPT_COOKIESESSION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_COOKIESESSION \- start a new cookie session +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIESESSION, long init); +.fi +.SH DESCRIPTION +Pass a long set to 1 to mark this as a new cookie "session". It forces libcurl +to ignore all cookies it is about to load that are "session cookies" from the +previous session. By default, libcurl always loads all cookies, independent if +they are session cookies or not. Session cookies are cookies without expiry +date and they are meant to be alive and existing for this "session" only. + +A "session" is usually defined in browser land for as long as you have your +browser up, more or less. libcurl needs the application to use this option to +tell it when a new session starts, otherwise it assumes everything is still in +the same session. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* new "session", do not load session cookies */ + curl_easy_setopt(curl, CURLOPT_COOKIESESSION, 1L); + + /* get the (non session) cookies from this file */ + curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "/tmp/cookies.txt"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.7 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_COOKIE (3), +.BR CURLOPT_COOKIEFILE (3), +.BR CURLOPT_COOKIEJAR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_COPYPOSTFIELDS.3 b/3rdparty/curl/share/man/man3/CURLOPT_COPYPOSTFIELDS.3 new file mode 100644 index 0000000..844c7dd --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_COPYPOSTFIELDS.3 @@ -0,0 +1,62 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_COPYPOSTFIELDS.md +.TH CURLOPT_COPYPOSTFIELDS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_COPYPOSTFIELDS \- have libcurl copy data to POST +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COPYPOSTFIELDS, char *data); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should be the full \fIdata\fP to post in a +HTTP POST operation. It behaves as the \fICURLOPT_POSTFIELDS(3)\fP option, but the +original data is instead copied by the library, allowing the application to +overwrite the original data after setting this option. + +Because data is copied, care must be taken when using this option in +conjunction with \fICURLOPT_POSTFIELDSIZE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP. +If the size has not been set prior to \fICURLOPT_COPYPOSTFIELDS(3)\fP, the data is +assumed to be a null\-terminated string; else the stored size informs the +library about the byte count to copy. In any case, the size must not be +changed after \fICURLOPT_COPYPOSTFIELDS(3)\fP, unless another \fICURLOPT_POSTFIELDS(3)\fP +or \fICURLOPT_COPYPOSTFIELDS(3)\fP option is set. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + char local_buffer[1024]="data to send"; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* size of the data to copy from the buffer and send in the request */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); + + /* send data from the local stack */ + curl_easy_setopt(curl, CURLOPT_COPYPOSTFIELDS, local_buffer); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.17.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_MIMEPOST (3), +.BR CURLOPT_POSTFIELDS (3), +.BR CURLOPT_POSTFIELDSIZE (3), +.BR CURLOPT_UPLOAD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CRLF.3 b/3rdparty/curl/share/man/man3/CURLOPT_CRLF.3 new file mode 100644 index 0000000..30c3d54 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CRLF.3 @@ -0,0 +1,41 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CRLF.md +.TH CURLOPT_CRLF 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CRLF \- CRLF conversion +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CRLF, long conv); +.fi +.SH DESCRIPTION +Pass a long. If the value is set to 1 (one), libcurl converts Unix newlines to +CRLF newlines on transfers. Disable this option again by setting the value to +0 (zero). + +This is a legacy option of questionable use. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); + curl_easy_setopt(curl, CURLOPT_CRLF, 1L); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_CONV_FROM_NETWORK_FUNCTION (3), +.BR CURLOPT_CONV_TO_NETWORK_FUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CRLFILE.3 b/3rdparty/curl/share/man/man3/CURLOPT_CRLFILE.3 new file mode 100644 index 0000000..c4210bd --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CRLFILE.3 @@ -0,0 +1,67 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CRLFILE.md +.TH CURLOPT_CRLFILE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CRLFILE \- Certificate Revocation List file +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CRLFILE, char *file); +.fi +.SH DESCRIPTION +Pass a char pointer to a null\-terminated string naming a \fIfile\fP with the +concatenation of CRL (in PEM format) to use in the certificate validation that +occurs during the SSL exchange. + +When curl is built to use GnuTLS, there is no way to influence the use of CRL +passed to help in the verification process. + +When libcurl is built with OpenSSL support, X509_V_FLAG_CRL_CHECK and +X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL check against all the +elements of the certificate chain if a CRL file is passed. Also note that +\fICURLOPT_CRLFILE(3)\fP implies \fBCURLSSLOPT_NO_PARTIALCHAIN\fP (see +\fICURLOPT_SSL_OPTIONS(3)\fP) since curl 7.71.0 due to an OpenSSL bug. + +This option makes sense only when used in combination with the +\fICURLOPT_SSL_VERIFYPEER(3)\fP option. + +A specific error code (\fICURLE_SSL_CRL_BADFILE\fP) is defined with the option. It +is returned when the SSL exchange fails because the CRL file cannot be loaded. +A failure in certificate verification due to a revocation information found in +the CRL does not trigger this specific error. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, mbedTLS and rustls +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_CRLFILE, "/etc/certs/crl.pem"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY_CRLFILE (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CURLU.3 b/3rdparty/curl/share/man/man3/CURLOPT_CURLU.3 new file mode 100644 index 0000000..6b6d17c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CURLU.3 @@ -0,0 +1,58 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CURLU.md +.TH CURLOPT_CURLU 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CURLU \- URL in URL handle format +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CURLU, CURLU *pointer); +.fi +.SH DESCRIPTION +Pass in a pointer to the \fIURL\fP handle to work with. The parameter should be a +\fICURLU pointer\fP. Setting \fICURLOPT_CURLU(3)\fP explicitly overrides +\fICURLOPT_URL(3)\fP. + +\fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a +transfer is started. + +libcurl uses this handle and its contents read\-only and does not change its +contents. An application can update the contents of the URL handle after a +transfer is done and if the same handle is used in a subsequent request the +updated contents is used. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + CURLU *urlp = curl_url(); + if(curl) { + CURLcode res; + CURLUcode ret; + ret = curl_url_set(urlp, CURLUPART_URL, "https://example.com", 0); + + curl_easy_setopt(curl, CURLOPT_CURLU, urlp); + + res = curl_easy_perform(curl); + + curl_url_cleanup(urlp); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.63.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_URL (3), +.BR curl_url (3), +.BR curl_url_cleanup (3), +.BR curl_url_dup (3), +.BR curl_url_get (3), +.BR curl_url_set (3), +.BR curl_url_strerror (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_CUSTOMREQUEST.3 b/3rdparty/curl/share/man/man3/CURLOPT_CUSTOMREQUEST.3 new file mode 100644 index 0000000..6529f9a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_CUSTOMREQUEST.3 @@ -0,0 +1,100 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_CUSTOMREQUEST.md +.TH CURLOPT_CUSTOMREQUEST 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_CUSTOMREQUEST \- custom request method +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *method); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. + +When changing the request \fImethod\fP by setting \fICURLOPT_CUSTOMREQUEST(3)\fP, you do +not actually change how libcurl behaves or acts: you only change the actual +string sent in the request. + +libcurl passes on the verbatim string in its request without any filter or +other safe guards. That includes white space and control characters. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Restore to the internal default by setting this to NULL. + +This option can be used to specify the request: +.IP HTTP +Instead of GET or HEAD when performing HTTP based requests. This is +particularly useful, for example, for performing an HTTP DELETE request. + +For example: + +When you tell libcurl to do a HEAD request, but then specify a GET though a +custom request libcurl still acts as if it sent a HEAD. To switch to a proper +HEAD use \fICURLOPT_NOBODY(3)\fP, to switch to a proper POST use +\fICURLOPT_POST(3)\fP or \fICURLOPT_POSTFIELDS(3)\fP and to switch to a proper +GET use \fICURLOPT_HTTPGET(3)\fP. + +Many people have wrongly used this option to replace the entire request with +their own, including multiple headers and POST contents. While that might work +in many cases, it might cause libcurl to send invalid requests and it could +possibly confuse the remote server badly. Use \fICURLOPT_POST(3)\fP and +\fICURLOPT_POSTFIELDS(3)\fP to set POST data. Use \fICURLOPT_HTTPHEADER(3)\fP +to replace or extend the set of headers sent by libcurl. Use +\fICURLOPT_HTTP_VERSION(3)\fP to change HTTP version. +.IP FTP +Instead of LIST and NLST when performing FTP directory listings. +.IP IMAP +Instead of LIST when issuing IMAP based requests. +.IP POP3 +Instead of LIST and RETR when issuing POP3 based requests. + +For example: + +When you tell libcurl to use a custom request it behaves like a LIST or RETR +command was sent where it expects data to be returned by the server. As such +\fICURLOPT_NOBODY(3)\fP should be used when specifying commands such as +\fBDELE\fP and \fBNOOP\fP for example. +.IP SMTP +Instead of a \fBHELP\fP or \fBVRFY\fP when issuing SMTP based requests. + +For example: + +Normally a multi line response is returned which can be used, in conjunction +with \fICURLOPT_MAIL_RCPT(3)\fP, to specify an EXPN request. If the +\fICURLOPT_NOBODY(3)\fP option is specified then the request can be used to +issue \fBNOOP\fP and \fBRSET\fP commands. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp, http, imap, pop3 and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* DELETE the given path */ + curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLINFO_EFFECTIVE_METHOD (3), +.BR CURLOPT_HTTPHEADER (3), +.BR CURLOPT_NOBODY (3), +.BR CURLOPT_REQUEST_TARGET (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DEBUGDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_DEBUGDATA.3 new file mode 100644 index 0000000..6a7a6a1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DEBUGDATA.3 @@ -0,0 +1,65 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DEBUGDATA.md +.TH CURLOPT_DEBUGDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DEBUGDATA \- pointer passed to the debug callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEBUGDATA, void *pointer); +.fi +.SH DESCRIPTION +Pass a \fIpointer\fP to whatever you want passed in to your +\fICURLOPT_DEBUGFUNCTION(3)\fP in the last void * argument. This pointer is +not used by libcurl, it is only passed to the callback. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct data { + void *custom; +}; + +static int my_trace(CURL *handle, curl_infotype type, + char *data, size_t size, + void *clientp) +{ + struct data *mine = clientp; + printf("our ptr: %p\\n", mine->custom); + + /* output debug info */ +} + +int main(void) +{ + CURL *curl; + CURLcode res; + struct data my_tracedata; + + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace); + + curl_easy_setopt(curl, CURLOPT_DEBUGDATA, &my_tracedata); + + /* the DEBUGFUNCTION has no effect until we enable VERBOSE */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } + return 0; +} +.fi +.SH AVAILABILITY +Added in curl 7.9.6 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_STDERR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DEBUGFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_DEBUGFUNCTION.3 new file mode 100644 index 0000000..47c0ce8 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DEBUGFUNCTION.3 @@ -0,0 +1,181 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DEBUGFUNCTION.md +.TH CURLOPT_DEBUGFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DEBUGFUNCTION \- debug callback +.SH SYNOPSIS +.nf +#include + +typedef enum { + CURLINFO_TEXT = 0, + CURLINFO_HEADER_IN, /* 1 */ + CURLINFO_HEADER_OUT, /* 2 */ + CURLINFO_DATA_IN, /* 3 */ + CURLINFO_DATA_OUT, /* 4 */ + CURLINFO_SSL_DATA_IN, /* 5 */ + CURLINFO_SSL_DATA_OUT, /* 6 */ + CURLINFO_END +} curl_infotype; + +int debug_callback(CURL *handle, + curl_infotype type, + char *data, + size_t size, + void *clientp); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEBUGFUNCTION, + debug_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +\fICURLOPT_DEBUGFUNCTION(3)\fP replaces the standard debug function used when +\fICURLOPT_VERBOSE(3)\fP is in effect. This callback receives debug +information, as specified in the \fItype\fP argument. This function must +return 0. The \fIdata\fP pointed to by the char * passed to this function is +not null\-terminated, but is exactly of the \fIsize\fP as told by the +\fIsize\fP argument. + +The \fIclientp\fP argument is the pointer set with \fICURLOPT_DEBUGDATA(3)\fP. + +Available \fBcurl_infotype\fP values: +.IP CURLINFO_TEXT +The data is informational text. +.IP CURLINFO_HEADER_IN +The data is header (or header\-like) data received from the peer. +.IP CURLINFO_HEADER_OUT +The data is header (or header\-like) data sent to the peer. +.IP CURLINFO_DATA_IN +The data is the unprocessed protocol data received from the peer. Even if the +data is encoded or compressed, it is not provided decoded nor decompressed +to this callback. If you need the data in decoded and decompressed form, use +\fICURLOPT_WRITEFUNCTION(3)\fP. +.IP CURLINFO_DATA_OUT +The data is protocol data sent to the peer. +.IP CURLINFO_SSL_DATA_OUT +The data is SSL/TLS (binary) data sent to the peer. +.IP CURLINFO_SSL_DATA_IN +The data is SSL/TLS (binary) data received from the peer. +.PP +WARNING: This callback may be called with the curl \fIhandle\fP set to an internal +handle. (Added in 8.4.0) + +If you need to distinguish your curl \fIhandle\fP from internal handles then set +\fICURLOPT_PRIVATE(3)\fP on your handle. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +static +void dump(const char *text, + FILE *stream, unsigned char *ptr, size_t size) +{ + size_t i; + size_t c; + unsigned int width = 0x10; + + fprintf(stream, "%s, %10.10ld bytes (0x%8.8lx)\\n", + text, (long)size, (long)size); + + for(i = 0; i < size; i += width) { + fprintf(stream, "%4.4lx: ", (long)i); + + /* show hex to the left */ + for(c = 0; c < width; c++) { + if(i + c < size) + fprintf(stream, "%02x ", ptr[i + c]); + else + fputs(" ", stream); + } + + /* show data on the right */ + for(c = 0; (c < width) && (i + c < size); c++) { + char x = (ptr[i + c] >= 0x20 && ptr[i + c] < 0x80) ? ptr[i + c] : '.'; + fputc(x, stream); + } + + fputc('\\n', stream); /* newline */ + } +} + +static +int my_trace(CURL *handle, curl_infotype type, + char *data, size_t size, + void *clientp) +{ + const char *text; + (void)handle; /* prevent compiler warning */ + (void)clientp; + + switch(type) { + case CURLINFO_TEXT: + fputs("== Info: ", stderr); + fwrite(data, size, 1, stderr); + default: /* in case a new one is introduced to shock us */ + return 0; + + case CURLINFO_HEADER_OUT: + text = "=> Send header"; + break; + case CURLINFO_DATA_OUT: + text = "=> Send data"; + break; + case CURLINFO_SSL_DATA_OUT: + text = "=> Send SSL data"; + break; + case CURLINFO_HEADER_IN: + text = "<= Recv header"; + break; + case CURLINFO_DATA_IN: + text = "<= Recv data"; + break; + case CURLINFO_SSL_DATA_IN: + text = "<= Recv SSL data"; + break; + } + + dump(text, stderr, (unsigned char *)data, size); + return 0; +} + +int main(void) +{ + CURL *curl; + CURLcode res; + + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace); + + /* the DEBUGFUNCTION has no effect until we enable VERBOSE */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + /* example.com is redirected, so we tell libcurl to follow redirection */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\\n", + curl_easy_strerror(res)); + + /* always cleanup */ + curl_easy_cleanup(curl); + } + return 0; +} +.fi +.SH AVAILABILITY +Added in curl 7.9.6 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLINFO_CONN_ID (3), +.BR CURLINFO_XFER_ID (3), +.BR CURLOPT_DEBUGDATA (3), +.BR CURLOPT_VERBOSE (3), +.BR curl_global_trace (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DEFAULT_PROTOCOL.3 b/3rdparty/curl/share/man/man3/CURLOPT_DEFAULT_PROTOCOL.3 new file mode 100644 index 0000000..b3d988a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DEFAULT_PROTOCOL.3 @@ -0,0 +1,71 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DEFAULT_PROTOCOL.md +.TH CURLOPT_DEFAULT_PROTOCOL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DEFAULT_PROTOCOL \- default protocol to use if the URL is missing a +scheme name +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEFAULT_PROTOCOL, + char *protocol); +.fi +.SH DESCRIPTION +This option tells libcurl to use \fIprotocol\fP if the URL is missing a scheme +name. + +Use one of these protocol (scheme) names: + +dict, file, ftp, ftps, gopher, http, https, imap, imaps, ldap, ldaps, pop3, +pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps, telnet, tftp + +An unknown or unsupported protocol causes error \fICURLE_UNSUPPORTED_PROTOCOL\fP +when libcurl parses a URL without a scheme. Parsing happens when +\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP is called. The protocol set +supported by libcurl vary depending on how it was built. Use +\fIcurl_version_info(3)\fP if you need a list of protocol names supported by the +build of libcurl that you are using. + +This option does not change the default proxy protocol (http). + +Without this option libcurl would make a guess based on the host, see +\fICURLOPT_URL(3)\fP for details. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL (make a guess based on the host) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* set a URL without a scheme */ + curl_easy_setopt(curl, CURLOPT_URL, "example.com"); + + /* set the default protocol (scheme) for schemeless URLs */ + curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https"); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.45.0 +.SH RETURN VALUE +CURLE_OK if the option is supported. + +CURLE_OUT_OF_MEMORY if there was insufficient heap space. + +CURLE_UNKNOWN_OPTION if the option is not supported. +.SH SEE ALSO +.BR CURLINFO_PROTOCOL (3), +.BR CURLINFO_SCHEME (3), +.BR CURLOPT_URL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DIRLISTONLY.3 b/3rdparty/curl/share/man/man3/CURLOPT_DIRLISTONLY.3 new file mode 100644 index 0000000..ed17919 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DIRLISTONLY.3 @@ -0,0 +1,64 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DIRLISTONLY.md +.TH CURLOPT_DIRLISTONLY 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DIRLISTONLY \- ask for names only in a directory listing +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DIRLISTONLY, long listonly); +.fi +.SH DESCRIPTION +For FTP and SFTP based URLs a parameter set to 1 tells the library to list the +names of files in a directory, rather than performing a full directory listing +that would normally include file sizes, dates etc. + +For POP3 a parameter of 1 tells the library to list the email message or +messages on the POP3 server. This can be used to change the default behavior +of libcurl, when combined with a URL that contains a message ID, to perform a +\&"scan listing" which can then be used to determine the size of an email. + +For FILE, this option has no effect yet as directories are always listed in +this mode. + +Note: For FTP this causes a NLST command to be sent to the FTP server. Beware +that some FTP servers list only files in their response to NLST; they might +not include subdirectories and symbolic links. + +Setting this option to 1 also implies a directory listing even if the URL +does not end with a slash, which otherwise is necessary. + +Do not use this option if you also use \fICURLOPT_WILDCARDMATCH(3)\fP as it +effectively breaks that feature. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects ftp, pop3 and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/"); + + /* list only */ + curl_easy_setopt(curl, CURLOPT_DIRLISTONLY, 1L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +This option was known as CURLOPT_FTPLISTONLY up to 7.16.4. POP3 is supported +since 7.21.5. +.SH AVAILABILITY +Added in curl 7.17.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CUSTOMREQUEST (3), +.BR CURLOPT_WILDCARDMATCH (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DISALLOW_USERNAME_IN_URL.3 b/3rdparty/curl/share/man/man3/CURLOPT_DISALLOW_USERNAME_IN_URL.3 new file mode 100644 index 0000000..fd184a4 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DISALLOW_USERNAME_IN_URL.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DISALLOW_USERNAME_IN_URL.md +.TH CURLOPT_DISALLOW_USERNAME_IN_URL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DISALLOW_USERNAME_IN_URL \- disallow specifying username in the URL +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DISALLOW_USERNAME_IN_URL, + long disallow); +.fi +.SH DESCRIPTION +A long parameter set to 1 tells the library to not allow URLs that include a +username. + +This is the equivalent to the \fICURLU_DISALLOW_USER\fP flag for the +\fIcurl_url_set(3)\fP function. +.SH DEFAULT +0 (disabled) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_DISALLOW_USERNAME_IN_URL, 1L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.61.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. + +\fIcurl_easy_perform(3)\fP returns CURLE_LOGIN_DENIED if this option is +enabled and a URL containing a username is specified. +.SH SEE ALSO +.BR CURLOPT_PROTOCOLS_STR (3), +.BR CURLOPT_URL (3), +.BR curl_url_set (3), +.BR libcurl-security (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DNS_CACHE_TIMEOUT.3 b/3rdparty/curl/share/man/man3/CURLOPT_DNS_CACHE_TIMEOUT.3 new file mode 100644 index 0000000..6bcb6d4 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DNS_CACHE_TIMEOUT.3 @@ -0,0 +1,68 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DNS_CACHE_TIMEOUT.md +.TH CURLOPT_DNS_CACHE_TIMEOUT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DNS_CACHE_TIMEOUT \- life\-time for DNS cache entries +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age); +.fi +.SH DESCRIPTION +Pass a long, this sets the timeout in seconds. Name resolve results are kept +in memory and used for this number of seconds. Set to zero to completely +disable caching, or set to \-1 to make the cached entries remain forever. By +default, libcurl caches this info for 60 seconds. + +We recommend users not to tamper with this option unless strictly necessary. +If you do, be careful of using large values that can make the cache size grow +significantly if many different hostnames are used within that timeout period. + +The name resolve functions of various libc implementations do not re\-read name +server information unless explicitly told so (for example, by calling +\fIres_init(3)\fP). This may cause libcurl to keep using the older server even +if DHCP has updated the server info, and this may look like a DNS cache issue +to the casual libcurl\-app user. + +DNS entries have a "TTL" property but libcurl does not use that. This DNS +cache timeout is entirely speculative that a name resolves to the same address +for a small amount of time into the future. + +Since version 8.1.0, libcurl prunes entries from the DNS cache if it exceeds +30,000 entries no matter which timeout value is used. +.SH DEFAULT +60 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* only reuse addresses for a short time */ + curl_easy_setopt(curl, CURLOPT_DNS_CACHE_TIMEOUT, 2L); + + res = curl_easy_perform(curl); + + /* in this second request, the cache is not be used if more than + two seconds have passed since the previous name resolve */ + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.3 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_CONNECTTIMEOUT_MS (3), +.BR CURLOPT_DNS_SERVERS (3), +.BR CURLOPT_DNS_USE_GLOBAL_CACHE (3), +.BR CURLOPT_MAXAGE_CONN (3), +.BR CURLOPT_RESOLVE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DNS_INTERFACE.3 b/3rdparty/curl/share/man/man3/CURLOPT_DNS_INTERFACE.3 new file mode 100644 index 0000000..8de4c6c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DNS_INTERFACE.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DNS_INTERFACE.md +.TH CURLOPT_DNS_INTERFACE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DNS_INTERFACE \- interface to speak DNS over +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_INTERFACE, char *ifname); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter. Set the name of the network interface that +the DNS resolver should bind to. This must be an interface name (not an +address). Set this option to NULL to use the default setting (do not bind to a +specific interface). + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_DNS_INTERFACE, "eth0"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH NOTES +This option requires that libcurl was built with a resolver backend that +supports this operation. The c\-ares backend is the only such one. +.SH AVAILABILITY +Added in curl 7.33.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +or CURLE_NOT_BUILT_IN if support was disabled at compile\-time. +.SH SEE ALSO +.BR CURLOPT_DNS_LOCAL_IP4 (3), +.BR CURLOPT_DNS_LOCAL_IP6 (3), +.BR CURLOPT_DNS_SERVERS (3), +.BR CURLOPT_INTERFACE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DNS_LOCAL_IP4.3 b/3rdparty/curl/share/man/man3/CURLOPT_DNS_LOCAL_IP4.3 new file mode 100644 index 0000000..b41e37f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DNS_LOCAL_IP4.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DNS_LOCAL_IP4.md +.TH CURLOPT_DNS_LOCAL_IP4 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DNS_LOCAL_IP4 \- IPv4 address to bind DNS resolves to +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_LOCAL_IP4, char *address); +.fi +.SH DESCRIPTION +Set the local IPv4 \fIaddress\fP that the resolver should bind to. The argument +should be of type char * and contain a single numerical IPv4 address as a +string. Set this option to NULL to use the default setting (do not bind to a +specific IP address). + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_DNS_LOCAL_IP4, "192.168.0.14"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH NOTES +This option requires that libcurl was built with a resolver backend that +supports this operation. The c\-ares backend is the only such one. +.SH AVAILABILITY +Added in curl 7.33.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +CURLE_NOT_BUILT_IN if support was disabled at compile\-time, or +CURLE_BAD_FUNCTION_ARGUMENT when given a bad address. +.SH SEE ALSO +.BR CURLOPT_DNS_INTERFACE (3), +.BR CURLOPT_DNS_LOCAL_IP6 (3), +.BR CURLOPT_DNS_SERVERS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DNS_LOCAL_IP6.3 b/3rdparty/curl/share/man/man3/CURLOPT_DNS_LOCAL_IP6.3 new file mode 100644 index 0000000..f7889de --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DNS_LOCAL_IP6.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DNS_LOCAL_IP6.md +.TH CURLOPT_DNS_LOCAL_IP6 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DNS_LOCAL_IP6 \- IPv6 address to bind DNS resolves to +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_LOCAL_IP6, char *address); +.fi +.SH DESCRIPTION +Set the local IPv6 \fIaddress\fP that the resolver should bind to. The argument +should be of type char * and contain a single IPv6 address as a string. Set +this option to NULL to use the default setting (do not bind to a specific IP +address). + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_DNS_LOCAL_IP6, "fe80::a9ff:fe46:b619"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH NOTES +This option requires that libcurl was built with a resolver backend that +supports this operation. The c\-ares backend is the only such one. +.SH AVAILABILITY +Added in curl 7.33.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +CURLE_NOT_BUILT_IN if support was disabled at compile\-time, or +CURLE_BAD_FUNCTION_ARGUMENT when given a bad address. +.SH SEE ALSO +.BR CURLOPT_DNS_INTERFACE (3), +.BR CURLOPT_DNS_LOCAL_IP4 (3), +.BR CURLOPT_DNS_SERVERS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DNS_SERVERS.3 b/3rdparty/curl/share/man/man3/CURLOPT_DNS_SERVERS.3 new file mode 100644 index 0000000..676fd5e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DNS_SERVERS.3 @@ -0,0 +1,62 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DNS_SERVERS.md +.TH CURLOPT_DNS_SERVERS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DNS_SERVERS \- DNS servers to use +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SERVERS, char *servers); +.fi +.SH DESCRIPTION +Pass a char pointer that is the list of DNS servers to be used instead of the +system default. The format of the dns servers option is: + +.nf +host[:port][,host[:port]]... +.fi + +For example: + +.nf +192.168.1.100,192.168.1.101,3.4.5.6 +.fi + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_DNS_SERVERS, + "192.168.1.100:53,192.168.1.101"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH NOTES +This option requires that libcurl was built with a resolver backend that +supports this operation. The c\-ares backend is the only such one. +.SH AVAILABILITY +Added in curl 7.24.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +CURLE_NOT_BUILT_IN if support was disabled at compile\-time, +CURLE_BAD_FUNCTION_ARGUMENT when given an invalid server list, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_DNS_CACHE_TIMEOUT (3), +.BR CURLOPT_DNS_LOCAL_IP4 (3), +.BR CURLOPT_DNS_LOCAL_IP6 (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 b/3rdparty/curl/share/man/man3/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 new file mode 100644 index 0000000..3232c8e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DNS_SHUFFLE_ADDRESSES.md +.TH CURLOPT_DNS_SHUFFLE_ADDRESSES 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DNS_SHUFFLE_ADDRESSES \- shuffle IP addresses for hostname +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SHUFFLE_ADDRESSES, long onoff); +.fi +.SH DESCRIPTION +Pass a long set to 1 to enable this option. + +When a name is resolved and more than one IP address is returned, this +function shuffles the order of all returned addresses so that they are used in +a random order. This is similar to the ordering behavior of the legacy +gethostbyname function which is no longer used on most platforms. + +Addresses are not reshuffled if name resolution is completed using the DNS +cache. \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP can be used together with this +option to reduce DNS cache timeout or disable caching entirely if frequent +reshuffling is needed. + +Since the addresses returned are randomly reordered, the order is not in +accordance with RFC 3484 or any other deterministic order that may be +generated by the system\(aqs name resolution implementation. This may have +performance impacts and may cause IPv4 to be used before IPv6 or vice versa. +.SH DEFAULT +0 (disabled) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_DNS_SHUFFLE_ADDRESSES, 1L); + + curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.60.0 +.SH RETURN VALUE +CURLE_OK or an error such as CURLE_UNKNOWN_OPTION. +.SH SEE ALSO +.BR CURLOPT_DNS_CACHE_TIMEOUT (3), +.BR CURLOPT_IPRESOLVE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DNS_USE_GLOBAL_CACHE.3 b/3rdparty/curl/share/man/man3/CURLOPT_DNS_USE_GLOBAL_CACHE.3 new file mode 100644 index 0000000..db72cde --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DNS_USE_GLOBAL_CACHE.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DNS_USE_GLOBAL_CACHE.md +.TH CURLOPT_DNS_USE_GLOBAL_CACHE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DNS_USE_GLOBAL_CACHE \- global DNS cache +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_USE_GLOBAL_CACHE, + long enable); +.fi +.SH DESCRIPTION +Has no function since 7.62.0. Do not use! + +Pass a long. If the \fIenable\fP value is 1, it tells curl to use a global DNS +cache that survives between easy handle creations and deletions. This is not +thread\-safe and this uses a global variable. + +See \fICURLOPT_SHARE(3)\fP and \fIcurl_share_init(3)\fP for the correct way to share DNS +cache between transfers. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* switch off the use of a global, thread unsafe, cache */ + curl_easy_setopt(curl, CURLOPT_DNS_USE_GLOBAL_CACHE, 0L); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} + +.fi +.SH DEPRECATED +Deprecated since 7.11.1. Functionality removed in 7.62.0. +.SH AVAILABILITY +Added in curl 7.9.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_DNS_CACHE_TIMEOUT (3), +.BR CURLOPT_SHARE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DOH_SSL_VERIFYHOST.3 b/3rdparty/curl/share/man/man3/CURLOPT_DOH_SSL_VERIFYHOST.3 new file mode 100644 index 0000000..556038d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DOH_SSL_VERIFYHOST.3 @@ -0,0 +1,69 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DOH_SSL_VERIFYHOST.md +.TH CURLOPT_DOH_SSL_VERIFYHOST 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DOH_SSL_VERIFYHOST \- verify the hostname in the DoH SSL certificate +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYHOST, + long verify); +.fi +.SH DESCRIPTION +Pass a long set to 2L as asking curl to \fIverify\fP the DoH (DNS\-over\-HTTPS) +server\(aqs certificate name fields against the hostname. + +This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYHOST(3)\fP and +only affects requests to the DoH server. + +When \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP is 2, the SSL certificate provided by +the DoH server must indicate that the server name is the same as the server +name to which you meant to connect to, or the connection fails. + +Curl considers the DoH server the intended one when the Common Name field or a +Subject Alternate Name field in the certificate matches the hostname in the +DoH URL to which you told Curl to connect. + +When the \fIverify\fP value is set to 1L it is treated the same as 2L. However +for consistency with the other \fIVERIFYHOST\fP options we suggest use 2 and +not 1. + +When the \fIverify\fP value is set to 0L, the connection succeeds regardless of +the names used in the certificate. Use that ability with caution! + +See also \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP to verify the digital signature +of the DoH server certificate. +.SH DEFAULT +2 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_DOH_URL, + "https://cloudflare-dns.com/dns-query"); + + /* Disable host name verification of the DoH server */ + curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYHOST, 0L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.76.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_DOH_SSL_VERIFYPEER (3), +.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), +.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DOH_SSL_VERIFYPEER.3 b/3rdparty/curl/share/man/man3/CURLOPT_DOH_SSL_VERIFYPEER.3 new file mode 100644 index 0000000..9b96f12 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DOH_SSL_VERIFYPEER.3 @@ -0,0 +1,81 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DOH_SSL_VERIFYPEER.md +.TH CURLOPT_DOH_SSL_VERIFYPEER 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DOH_SSL_VERIFYPEER \- verify the DoH SSL certificate +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYPEER, + long verify); +.fi +.SH DESCRIPTION +Pass a long as parameter set to 1L to enable or 0L to disable. + +This option tells curl to verify the authenticity of the DoH (DNS\-over\-HTTPS) +server\(aqs certificate. A value of 1 means curl verifies; 0 (zero) means it +does not. + +This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYPEER(3)\fP and +only affects requests to the DoH server. + +When negotiating a TLS or SSL connection, the server sends a certificate +indicating its identity. Curl verifies whether the certificate is authentic, +i.e. that you can trust that the server is who the certificate says it is. +This trust is based on a chain of digital signatures, rooted in certification +authority (CA) certificates you supply. curl uses a default bundle of CA +certificates (the path for that is determined at build time) and you can +specify alternate certificates with the \fICURLOPT_CAINFO(3)\fP option or the +\fICURLOPT_CAPATH(3)\fP option. + +When \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP is enabled, and the verification fails to +prove that the certificate is authentic, the connection fails. When the option +is zero, the peer certificate verification succeeds regardless. + +Authenticating the certificate is not enough to be sure about the server. You +typically also want to ensure that the server is the server you mean to be +talking to. Use \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP for that. The check that the +hostname in the certificate is valid for the hostname you are connecting to +is done independently of the \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP option. + +WARNING: disabling verification of the certificate allows bad guys to +man\-in\-the\-middle the communication without you knowing it. Disabling +verification makes the communication insecure. Just having encryption on a +transfer is not enough as you cannot be sure that you are communicating with +the correct end\-point. +.SH DEFAULT +1 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_DOH_URL, + "https://cloudflare-dns.com/dns-query"); + + /* Disable certificate verification of the DoH server */ + curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYPEER, 0L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.76.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_CAPATH (3), +.BR CURLOPT_DOH_SSL_VERIFYHOST (3), +.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), +.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DOH_SSL_VERIFYSTATUS.3 b/3rdparty/curl/share/man/man3/CURLOPT_DOH_SSL_VERIFYSTATUS.3 new file mode 100644 index 0000000..247e84d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DOH_SSL_VERIFYSTATUS.3 @@ -0,0 +1,57 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DOH_SSL_VERIFYSTATUS.md +.TH CURLOPT_DOH_SSL_VERIFYSTATUS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DOH_SSL_VERIFYSTATUS \- verify the DoH SSL certificate\(aqs status +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYSTATUS, + long verify); +.fi +.SH DESCRIPTION +Pass a long as parameter set to 1 to enable or 0 to disable. + +This option determines whether libcurl verifies the status of the DoH +(DNS\-over\-HTTPS) server cert using the "Certificate Status Request" TLS +extension (aka. OCSP stapling). + +This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYSTATUS(3)\fP and +only affects requests to the DoH server. + +If this option is enabled and the server does not support the TLS extension, +the verification fails. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_DOH_URL, + "https://cloudflare-dns.com/dns-query"); + + /* Ask for OCSP stapling when verifying the DoH server */ + curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYSTATUS, 1L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.76.0 +.SH RETURN VALUE +Returns CURLE_OK if OCSP stapling is supported by the SSL backend, otherwise +returns CURLE_NOT_BUILT_IN. +.SH SEE ALSO +.BR CURLOPT_DOH_SSL_VERIFYHOST (3), +.BR CURLOPT_DOH_SSL_VERIFYPEER (3), +.BR CURLOPT_SSL_VERIFYSTATUS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_DOH_URL.3 b/3rdparty/curl/share/man/man3/CURLOPT_DOH_URL.3 new file mode 100644 index 0000000..618665f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_DOH_URL.3 @@ -0,0 +1,74 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_DOH_URL.md +.TH CURLOPT_DOH_URL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_DOH_URL \- provide the DNS\-over\-HTTPS URL +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_URL, char *URL); +.fi +.SH DESCRIPTION +Pass in a pointer to a \fIURL\fP for the DoH server to use for name resolving. The +parameter should be a char pointer to a null\-terminated string which must be a +valid and correct HTTPS URL. + +libcurl does not validate the syntax or use this variable until the transfer +is issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP still +returns \fICURLE_OK\fP. + +curl sends POST requests to the given DNS\-over\-HTTPS URL. + +To find the DoH server itself, which might be specified using a name, libcurl +uses the default name lookup function. You can bootstrap that by providing the +address for the DoH server with \fICURLOPT_RESOLVE(3)\fP. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH INHERIT OPTIONS +DoH lookups use SSL and some SSL settings from your transfer are inherited, +like \fICURLOPT_SSL_CTX_FUNCTION(3)\fP. + +The hostname and peer certificate verification settings are not inherited but +can be controlled separately via \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP and +\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP. + +A set \fICURLOPT_OPENSOCKETFUNCTION(3)\fP callback is not inherited. +.SH KNOWN BUGS +Even when DoH is set to be used with this option, there are still some name +resolves that are performed without it, using the default name resolver +mechanism. This includes name resolves done for \fICURLOPT_INTERFACE(3)\fP, +\fICURLOPT_FTPPORT(3)\fP, a proxy type set to \fBCURLPROXY_SOCKS4\fP or +\fBCURLPROXY_SOCKS5\fP and probably some more. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://dns.example.com"); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.62.0 +.SH RETURN VALUE +Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient +heap space. + +Note that \fIcurl_easy_setopt(3)\fP does immediately parse the given string so +when given a bad DoH URL, libcurl might not detect the problem until it later +tries to resolve a name with it. +.SH SEE ALSO +.BR CURLOPT_DNS_CACHE_TIMEOUT (3), +.BR CURLOPT_RESOLVE (3), +.BR CURLOPT_VERBOSE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_ECH.3 b/3rdparty/curl/share/man/man3/CURLOPT_ECH.3 new file mode 100644 index 0000000..ff41f11 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_ECH.3 @@ -0,0 +1,75 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_ECH.md +.TH CURLOPT_ECH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_ECH \- configuration for Encrypted Client Hello +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ECH, char *config); +.fi +.SH DESCRIPTION +ECH is only compatible with TLSv1.3. + +This experimental feature requires a special build of OpenSSL, as ECH is not +yet supported in OpenSSL releases. In contrast ECH is supported by the latest +BoringSSL and wolfSSL releases. + +There is also a known issue with using wolfSSL which does not support ECH when +the HelloRetryRequest mechanism is used. + +Pass a string that specifies configuration details for ECH. In all cases, if +ECH is attempted, it may fail for various reasons. The keywords supported are: +.IP false +Turns off ECH. +.IP grease +Instructs client to emit a GREASE ECH extension. (The connection fails if ECH +is attempted but fails.) +.IP true +Instructs client to attempt ECH, if possible, but to not fail if attempting +ECH is not possible. +.IP hard +Instructs client to attempt ECH and fail if attempting ECH is not possible. +.IP ecl:\ +If the string starts with \fIecl:\fP then the remainder of the string should be a +base64\-encoded ECHConfigList that is used for ECH rather than attempting to +download such a value from the DNS. +.IP pn:\ +If the string starts with \fIpn:\fP then the remainder of the string should be a +DNS/hostname that is used to over\-ride the public_name field of the +ECHConfigList that is used for ECH. +.PP +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL or "false" to disable its use again. +.SH DEFAULT +NULL, meaning ECH is disabled. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + + const char *config = \\ + "ecl:AED+DQA87wAgACB/RuzUCsW3uBbSFI7mzD63TUXpI8sGDTnFTbFCDpa+" \\ + "CAAEAAEAAQANY292ZXIuZGVmby5pZQAA"; + if(curl) { + curl_easy_setopt(curl, CURLOPT_ECH, config); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 8.8.0 +.SH RETURN VALUE +Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient +heap space. +.SH SEE ALSO +.BR CURLOPT_DOH_URL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_EGDSOCKET.3 b/3rdparty/curl/share/man/man3/CURLOPT_EGDSOCKET.3 new file mode 100644 index 0000000..72918e3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_EGDSOCKET.3 @@ -0,0 +1,22 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_EGDSOCKET.md +.TH CURLOPT_EGDSOCKET 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_EGDSOCKET \- EGD socket path +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_EGDSOCKET, char *path); +.fi +.SH DESCRIPTION +Deprecated option. It serves no purpose anymore. +.SH DEFAULT +NULL +.SH DEPRECATED +This option was deprecated in 7.84.0. +.SH AVAILABILITY +Added in curl 7.7 +.SH RETURN VALUE +Returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_RANDOM_FILE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_ERRORBUFFER.3 b/3rdparty/curl/share/man/man3/CURLOPT_ERRORBUFFER.3 new file mode 100644 index 0000000..2ff586b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_ERRORBUFFER.3 @@ -0,0 +1,83 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_ERRORBUFFER.md +.TH CURLOPT_ERRORBUFFER 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_ERRORBUFFER \- error buffer for error messages +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ERRORBUFFER, char *buf); +.fi +.SH DESCRIPTION +Pass a char pointer to a buffer that libcurl may use to store human readable +error messages on failures or problems. This may be more helpful than just the +return code from \fIcurl_easy_perform(3)\fP and related functions. The buffer must +be at least \fBCURL_ERROR_SIZE\fP bytes big. + +You must keep the associated buffer available until libcurl no longer needs +it. Failing to do so might cause odd behavior or even crashes. libcurl might +need it until you call \fIcurl_easy_cleanup(3)\fP or you set the same option again +to use a different pointer. + +Do not rely on the contents of the buffer unless an error code was returned. +Since 7.60.0 libcurl initializes the contents of the error buffer to an empty +string before performing the transfer. For earlier versions if an error code +was returned but there was no error detail then the buffer was untouched. + +Consider \fICURLOPT_VERBOSE(3)\fP and \fICURLOPT_DEBUGFUNCTION(3)\fP to better debug and +trace why errors happen. + +Using this option multiple times makes the last set pointer override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +#include /* for strlen() */ +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + char errbuf[CURL_ERROR_SIZE]; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* provide a buffer to store errors in */ + curl_easy_setopt(curl, CURLOPT_ERRORBUFFER, errbuf); + + /* set the error buffer as empty before performing a request */ + errbuf[0] = 0; + + /* perform the request */ + res = curl_easy_perform(curl); + + /* if the request did not complete correctly, show the error + information. if no detailed error information was written to errbuf + show the more generic information from curl_easy_strerror instead. + */ + if(res != CURLE_OK) { + size_t len = strlen(errbuf); + fprintf(stderr, "\\nlibcurl: (%d) ", res); + if(len) + fprintf(stderr, "%s%s", errbuf, + ((errbuf[len - 1] != '\\n') ? "\\n" : "")); + else + fprintf(stderr, "%s\\n", curl_easy_strerror(res)); + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_VERBOSE (3), +.BR curl_easy_strerror (3), +.BR curl_multi_strerror (3), +.BR curl_share_strerror (3), +.BR curl_url_strerror (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_EXPECT_100_TIMEOUT_MS.3 b/3rdparty/curl/share/man/man3/CURLOPT_EXPECT_100_TIMEOUT_MS.3 new file mode 100644 index 0000000..ed849e1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_EXPECT_100_TIMEOUT_MS.3 @@ -0,0 +1,43 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_EXPECT_100_TIMEOUT_MS.md +.TH CURLOPT_EXPECT_100_TIMEOUT_MS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_EXPECT_100_TIMEOUT_MS \- timeout for Expect: 100\-continue response +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_EXPECT_100_TIMEOUT_MS, + long milliseconds); +.fi +.SH DESCRIPTION +Pass a long to tell libcurl the number of \fImilliseconds\fP to wait for a +server response with the HTTP status 100 (Continue), 417 (Expectation Failed) +or similar after sending an HTTP request containing an Expect: 100\-continue +header. If this times out before a response is received, the request body is +sent anyway. +.SH DEFAULT +1000 milliseconds +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* wait 3 seconds for 100-continue */ + curl_easy_setopt(curl, CURLOPT_EXPECT_100_TIMEOUT_MS, 3000L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.36.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTPPOST (3), +.BR CURLOPT_POST (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FAILONERROR.3 b/3rdparty/curl/share/man/man3/CURLOPT_FAILONERROR.3 new file mode 100644 index 0000000..3cdf2dc --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FAILONERROR.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FAILONERROR.md +.TH CURLOPT_FAILONERROR 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FAILONERROR \- request failure on HTTP response >= 400 +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FAILONERROR, long fail); +.fi +.SH DESCRIPTION +A long parameter set to 1 tells the library to fail the request if the HTTP +code returned is equal to or larger than 400. The default action would be to +return the page normally, ignoring that code. + +This method is not fail\-safe and there are occasions where non\-successful +response codes slip through, especially when authentication is involved +(response codes 401 and 407). + +You might get some amounts of headers transferred before this situation is +detected, like when a "100\-continue" is received as a response to a POST/PUT +and a 401 or 407 is received immediately afterwards. + +When this option is used and an error is detected, it causes the connection to +get closed and \fICURLE_HTTP_RETURNED_ERROR\fP is returned. +.SH DEFAULT +0, do not fail on error +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_FAILONERROR, 1L); + ret = curl_easy_perform(curl); + if(ret == CURLE_HTTP_RETURNED_ERROR) { + /* an HTTP response error problem */ + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RESPONSE_CODE (3), +.BR CURLOPT_HTTP200ALIASES (3), +.BR CURLOPT_KEEP_SENDING_ON_ERROR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FILETIME.3 b/3rdparty/curl/share/man/man3/CURLOPT_FILETIME.3 new file mode 100644 index 0000000..78bd071 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FILETIME.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FILETIME.md +.TH CURLOPT_FILETIME 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FILETIME \- get the modification time of the remote resource +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FILETIME, long gettime); +.fi +.SH DESCRIPTION +Pass a long. If it is 1, libcurl attempts to get the modification time of the +remote document in this operation. This requires that the remote server sends +the time or replies to a time querying command. The \fIcurl_easy_getinfo(3)\fP +function with the \fICURLINFO_FILETIME(3)\fP argument can be used after a +transfer to extract the received time (if any). +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects file, ftp, http, sftp and smb +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/path.html"); + /* Ask for filetime */ + curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + long filetime; + res = curl_easy_getinfo(curl, CURLINFO_FILETIME, &filetime); + if((CURLE_OK == res) && (filetime >= 0)) { + time_t file_time = (time_t)filetime; + printf("filetime: %s", ctime(&file_time)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.5 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLINFO_FILETIME (3), +.BR curl_easy_getinfo (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FNMATCH_DATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_FNMATCH_DATA.3 new file mode 100644 index 0000000..fa483a7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FNMATCH_DATA.3 @@ -0,0 +1,59 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FNMATCH_DATA.md +.TH CURLOPT_FNMATCH_DATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FNMATCH_DATA \- pointer passed to the fnmatch callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_DATA, + void *pointer); +.fi +.SH DESCRIPTION +Pass a pointer that is untouched by libcurl and passed as the ptr argument to +the \fICURLOPT_FNMATCH_FUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +extern int string_match(const char *s1, const char *s2); + +struct local_stuff { + void *custom; +}; + +static int my_fnmatch(void *clientp, + const char *pattern, const char *string) +{ + struct local_stuff *my = clientp; + printf("my ptr: %p\\n", my->custom); + + if(string_match(pattern, string)) + return CURL_FNMATCHFUNC_MATCH; + else + return CURL_FNMATCHFUNC_NOMATCH; +} + +int main(void) +{ + struct local_stuff local_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://ftp.example.com/file*"); + curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); + curl_easy_setopt(curl, CURLOPT_FNMATCH_FUNCTION, my_fnmatch); + curl_easy_setopt(curl, CURLOPT_FNMATCH_DATA, &local_data); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FNMATCH_FUNCTION (3), +.BR CURLOPT_WILDCARDMATCH (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FNMATCH_FUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_FNMATCH_FUNCTION.3 new file mode 100644 index 0000000..ceec19c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FNMATCH_FUNCTION.3 @@ -0,0 +1,67 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FNMATCH_FUNCTION.md +.TH CURLOPT_FNMATCH_FUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FNMATCH_FUNCTION \- wildcard match callback +.SH SYNOPSIS +.nf +#include + +int fnmatch_callback(void *ptr, + const char *pattern, + const char *string); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_FUNCTION, + fnmatch_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback is used for wildcard matching. + +Return \fICURL_FNMATCHFUNC_MATCH\fP if pattern matches the string, +\fICURL_FNMATCHFUNC_NOMATCH\fP if not or \fICURL_FNMATCHFUNC_FAIL\fP if an +error occurred. +.SH DEFAULT +NULL == an internal function for wildcard matching. +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +extern int string_match(const char *s1, const char *s2); + +struct local_stuff { + void *custom; +}; +static int my_fnmatch(void *clientp, + const char *pattern, const char *string) +{ + struct local_stuff *data = clientp; + printf("my pointer: %p\\n", data->custom); + if(string_match(pattern, string)) + return CURL_FNMATCHFUNC_MATCH; + else + return CURL_FNMATCHFUNC_NOMATCH; +} + +int main(void) +{ + struct local_stuff local_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://ftp.example.com/file*"); + curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); + curl_easy_setopt(curl, CURLOPT_FNMATCH_FUNCTION, my_fnmatch); + curl_easy_setopt(curl, CURLOPT_FNMATCH_DATA, &local_data); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_FNMATCH_DATA (3), +.BR CURLOPT_WILDCARDMATCH (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FOLLOWLOCATION.3 b/3rdparty/curl/share/man/man3/CURLOPT_FOLLOWLOCATION.3 new file mode 100644 index 0000000..a41b82d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FOLLOWLOCATION.3 @@ -0,0 +1,80 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FOLLOWLOCATION.md +.TH CURLOPT_FOLLOWLOCATION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FOLLOWLOCATION \- follow HTTP 3xx redirects +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FOLLOWLOCATION, long enable); +.fi +.SH DESCRIPTION +A long parameter set to 1 tells the library to follow any Location: header +redirects that an HTTP server sends in a 30x response. The Location: header +can specify a relative or an absolute URL to follow. + +libcurl issues another request for the new URL and follows subsequent new +\fILocation:\fP redirects all the way until no more such headers are returned or +the maximum limit is reached. \fICURLOPT_MAXREDIRS(3)\fP is used to limit the number +of redirects libcurl follows. + +libcurl restricts what protocols it automatically follow redirects to. The +accepted target protocols are set with \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP. By +default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects. + +When following a redirect, the specific 30x response code also dictates which +request method libcurl uses in the subsequent request: For 301, 302 and 303 +responses libcurl switches method from POST to GET unless \fICURLOPT_POSTREDIR(3)\fP +instructs libcurl otherwise. All other redirect response codes make libcurl +use the same method again. + +For users who think the existing location following is too naive, too simple +or just lacks features, it is easy to instead implement your own redirect +follow logic with the use of \fIcurl_easy_getinfo(3)\fP\(aqs \fICURLINFO_REDIRECT_URL(3)\fP +option instead of using \fICURLOPT_FOLLOWLOCATION(3)\fP. + +By default, libcurl only sends \fIAuthentication:\fP or explicitly set \fICookie:\fP +headers to the initial host given in the original URL, to avoid leaking +username + password to other sites. \fICURLOPT_UNRESTRICTED_AUTH(3)\fP is provided +to change that behavior. + +Due to the way HTTP works, almost any header can be made to contain data a +client may not want to pass on to other servers than the initially intended +host and for all other headers than the two mentioned above, there is no +protection from this happening when libcurl is told to follow redirects. +.SH NOTE +Since libcurl changes method or not based on the specific HTTP response code, +setting \fICURLOPT_CUSTOMREQUEST(3)\fP while following redirects may change what +libcurl would otherwise do and if not that carefully may even make it +misbehave since \fICURLOPT_CUSTOMREQUEST(3)\fP overrides the method libcurl would +otherwise select internally. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* example.com is redirected, so we tell libcurl to follow redirection */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_REDIRECT_COUNT (3), +.BR CURLINFO_REDIRECT_URL (3), +.BR CURLOPT_POSTREDIR (3), +.BR CURLOPT_PROTOCOLS_STR (3), +.BR CURLOPT_REDIR_PROTOCOLS_STR (3), +.BR CURLOPT_UNRESTRICTED_AUTH (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FORBID_REUSE.3 b/3rdparty/curl/share/man/man3/CURLOPT_FORBID_REUSE.3 new file mode 100644 index 0000000..2695c6d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FORBID_REUSE.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FORBID_REUSE.md +.TH CURLOPT_FORBID_REUSE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FORBID_REUSE \- make connection get closed at once after use +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FORBID_REUSE, long close); +.fi +.SH DESCRIPTION +Pass a long. Set \fIclose\fP to 1 to make libcurl explicitly close the +connection when done with the transfer. Normally, libcurl keeps all +connections alive when done with one transfer in case a succeeding one follows +that can reuse them. This option should be used with caution and only if you +understand what it does as it can seriously impact performance. + +Set to 0 to have libcurl keep the connection open for possible later reuse +(default behavior). +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_FORBID_REUSE, 1L); + curl_easy_perform(curl); + + /* this second transfer may not reuse the same connection */ + curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.7 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_FRESH_CONNECT (3), +.BR CURLOPT_MAXCONNECTS (3), +.BR CURLOPT_MAXLIFETIME_CONN (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FRESH_CONNECT.3 b/3rdparty/curl/share/man/man3/CURLOPT_FRESH_CONNECT.3 new file mode 100644 index 0000000..cdd2638 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FRESH_CONNECT.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FRESH_CONNECT.md +.TH CURLOPT_FRESH_CONNECT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FRESH_CONNECT \- force a new connection to be used +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FRESH_CONNECT, long fresh); +.fi +.SH DESCRIPTION +Pass a long. Set to 1 to make the next transfer use a new (fresh) connection +by force instead of trying to reuse an existing one. This option should be +used with caution and only if you understand what it does as it may impact +performance negatively. + +Related functionality is \fICURLOPT_FORBID_REUSE(3)\fP which makes sure the +connection is closed after use so that it cannot be reused. + +Set \fIfresh\fP to 0 to have libcurl attempt reusing an existing connection +(default behavior). +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_FRESH_CONNECT, 1L); + /* this transfer must use a new connection, not reuse an existing */ + curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.7 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_FORBID_REUSE (3), +.BR CURLOPT_MAXAGE_CONN (3), +.BR CURLOPT_MAXLIFETIME_CONN (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FTPPORT.3 b/3rdparty/curl/share/man/man3/CURLOPT_FTPPORT.3 new file mode 100644 index 0000000..1e99e28 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FTPPORT.3 @@ -0,0 +1,79 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FTPPORT.md +.TH CURLOPT_FTPPORT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FTPPORT \- make FTP transfer active +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPPORT, char *spec); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. It specifies that the +FTP transfer should be made actively and the given string is used to get the +IP address to use for the FTP PORT instruction. + +The PORT instruction tells the remote server to do a TCP connect to our +specified IP address. The string may be a plain IP address, a hostname, a +network interface name (under Unix) or just a \(aq\-\(aq symbol to let the library +use your system\(aqs default IP address. Default FTP operations are passive, and +does not use the PORT command. + +The address can be followed by a \(aq:\(aq to specify a port, optionally followed by +a \(aq\-\(aq to specify a port range. If the port specified is 0, the operating +system picks a free port. If a range is provided and all ports in the range +are not available, libcurl reports CURLE_FTP_PORT_FAILED for the +handle. Invalid port/range settings are ignored. IPv6 addresses followed by a +port or port range have to be in brackets. IPv6 addresses without port/range +specifier can be in brackets. + +Examples with specified ports: + +.nf +eth0:0 +192.168.1.2:32000-33000 +curl.se:32123 +[::1]:1234-4567 +.fi + +We strongly advise against specifying the address with a name, as it causes +libcurl to do a blocking name resolve call to retrieve the IP address. That +name resolve operation does \fBnot\fP use DNS\-over\-HTTPS even if +\fICURLOPT_DOH_URL(3)\fP is set. + +Using anything else than "\-" for this option should typically only be done if +you have special knowledge and confirmation that it works. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. You disable PORT again and go back to using the passive version +by setting this option to NULL. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/old-server/file.txt"); + curl_easy_setopt(curl, CURLOPT_FTPPORT, "-"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_FTP_USE_EPRT (3), +.BR CURLOPT_FTP_USE_EPSV (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FTPSSLAUTH.3 b/3rdparty/curl/share/man/man3/CURLOPT_FTPSSLAUTH.3 new file mode 100644 index 0000000..f134e7c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FTPSSLAUTH.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FTPSSLAUTH.md +.TH CURLOPT_FTPSSLAUTH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FTPSSLAUTH \- order in which to attempt TLS vs SSL +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPSSLAUTH, long order); +.fi +.SH DESCRIPTION +Pass a long using one of the values from below, to alter how libcurl issues +\&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated. This is only +interesting if \fICURLOPT_USE_SSL(3)\fP is also set. + +Possible \fIorder\fP values: +.IP CURLFTPAUTH_DEFAULT +Allow libcurl to decide. +.IP CURLFTPAUTH_SSL +Try "AUTH SSL" first, and only if that fails try "AUTH TLS". +.IP CURLFTPAUTH_TLS +Try "AUTH TLS" first, and only if that fails try "AUTH SSL". +.SH DEFAULT +CURLFTPAUTH_DEFAULT +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); + curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_TRY); + /* funny server, ask for SSL before TLS */ + curl_easy_setopt(curl, CURLOPT_FTPSSLAUTH, (long)CURLFTPAUTH_SSL); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.12.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FTP_SSL_CCC (3), +.BR CURLOPT_USE_SSL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FTP_ACCOUNT.3 b/3rdparty/curl/share/man/man3/CURLOPT_FTP_ACCOUNT.3 new file mode 100644 index 0000000..551de88 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FTP_ACCOUNT.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FTP_ACCOUNT.md +.TH CURLOPT_FTP_ACCOUNT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FTP_ACCOUNT \- account info for FTP +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ACCOUNT, char *account); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string (or NULL to disable). When an FTP +server asks for "account data" after username and password has been provided, +this data is sent off using the ACCT command. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); + + curl_easy_setopt(curl, CURLOPT_FTP_ACCOUNT, "human-resources"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.13.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PASSWORD (3), +.BR CURLOPT_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 b/3rdparty/curl/share/man/man3/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 new file mode 100644 index 0000000..26c2747 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FTP_ALTERNATIVE_TO_USER.md +.TH CURLOPT_FTP_ALTERNATIVE_TO_USER 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FTP_ALTERNATIVE_TO_USER \- command to use instead of USER with FTP +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ALTERNATIVE_TO_USER, + char *cmd); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, pointing to a string which is used to +authenticate if the usual FTP "USER user" and "PASS password" negotiation +fails. This is currently only known to be required when connecting to +Tumbleweed\(aqs Secure Transport FTPS server using client certificates for +authentication. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_FTP_ALTERNATIVE_TO_USER, "two users"); + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.15.5 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_FTP_ACCOUNT (3), +.BR CURLOPT_FTP_SKIP_PASV_IP (3), +.BR CURLOPT_SERVER_RESPONSE_TIMEOUT (3), +.BR CURLOPT_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FTP_CREATE_MISSING_DIRS.3 b/3rdparty/curl/share/man/man3/CURLOPT_FTP_CREATE_MISSING_DIRS.3 new file mode 100644 index 0000000..25b192f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FTP_CREATE_MISSING_DIRS.3 @@ -0,0 +1,66 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FTP_CREATE_MISSING_DIRS.md +.TH CURLOPT_FTP_CREATE_MISSING_DIRS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FTP_CREATE_MISSING_DIRS \- create missing directories for FTP and SFTP +.SH SYNOPSIS +.nf +#include + +typedef enum { + CURLFTP_CREATE_DIR_NONE, + CURLFTP_CREATE_DIR, + CURLFTP_CREATE_DIR_RETRY +} curl_ftpcreatedir; + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_CREATE_MISSING_DIRS, + long create); +.fi +.SH DESCRIPTION +Pass a long telling libcurl to \fIcreate\fP the dir. If the value is +\fICURLFTP_CREATE_DIR\fP (1), libcurl may create any remote directory that it +fails to "move" into. + +For FTP requests, that means a CWD command fails. CWD being the command that +changes working directory. + +For SFTP requests, libcurl may create the remote directory if it cannot obtain +a handle to the target\-location. The creation fails if a file of the same name +as the directory to create already exists or lack of permissions prevents +creation. + +Setting \fIcreate\fP to \fICURLFTP_CREATE_DIR_RETRY\fP (2), tells libcurl to +retry the CWD command again if the subsequent \fBMKD\fP command fails. This is +especially useful if you are doing many simultaneous connections against the +same server and they all have this option enabled, as then CWD may first fail +but then another connection does \fBMKD\fP before this connection and thus +\fBMKD\fP fails but trying CWD works! +.SH DEFAULT +CURLFTP_CREATE_DIR_NONE (0) +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/non-existing/new.txt"); + curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS, + (long)CURLFTP_CREATE_DIR_RETRY); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.7 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the +create value is not. +.SH SEE ALSO +.BR CURLOPT_FTP_FILEMETHOD (3), +.BR CURLOPT_FTP_USE_EPSV (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FTP_FILEMETHOD.3 b/3rdparty/curl/share/man/man3/CURLOPT_FTP_FILEMETHOD.3 new file mode 100644 index 0000000..25dea6a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FTP_FILEMETHOD.3 @@ -0,0 +1,59 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FTP_FILEMETHOD.md +.TH CURLOPT_FTP_FILEMETHOD 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FTP_FILEMETHOD \- select directory traversing method for FTP +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_FILEMETHOD, + long method); +.fi +.SH DESCRIPTION +Pass a long telling libcurl which \fImethod\fP to use to reach a file on a +FTP(S) server. + +This option exists because some server implementations are not compliant to +what the standards say should work. + +The argument should be one of the following alternatives: +.IP CURLFTPMETHOD_MULTICWD +libcurl does a single CWD operation for each path part in the given URL. For +deep hierarchies this means many commands. This is how RFC 1738 says it should +be done. This is the default but the slowest behavior. +.IP CURLFTPMETHOD_NOCWD +libcurl makes no CWD at all. libcurl does SIZE, RETR, STOR etc and gives a +full path to the server for all these commands. This is the fastest behavior +since it skips having to change directories. +.IP CURLFTPMETHOD_SINGLECWD +libcurl does one CWD with the full target directory and then operates on the +file &"normally" (like in the multicwd case). This is somewhat more standards +compliant than \(aqnocwd\(aq but without the full penalty of \(aqmulticwd\(aq. +.SH DEFAULT +CURLFTPMETHOD_MULTICWD +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/1/2/3/4/new.txt"); + curl_easy_setopt(curl, CURLOPT_FTP_FILEMETHOD, + (long)CURLFTPMETHOD_SINGLECWD); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.15.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_DIRLISTONLY (3), +.BR CURLOPT_FTP_SKIP_PASV_IP (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FTP_SKIP_PASV_IP.3 b/3rdparty/curl/share/man/man3/CURLOPT_FTP_SKIP_PASV_IP.3 new file mode 100644 index 0000000..79bf752 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FTP_SKIP_PASV_IP.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FTP_SKIP_PASV_IP.md +.TH CURLOPT_FTP_SKIP_PASV_IP 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FTP_SKIP_PASV_IP \- ignore the IP address in the PASV response +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SKIP_PASV_IP, long skip); +.fi +.SH DESCRIPTION +Pass a long. If \fIskip\fP is set to 1, it instructs libcurl to not use the IP +address the server suggests in its 227\-response to libcurl\(aqs PASV command when +libcurl connects the data connection. Instead libcurl reuses the same IP +address it already uses for the control connection. It still uses the port +number from the 227\-response. + +This option allows libcurl to work around broken server installations or funny +network setups that due to NATs, firewalls or incompetence report the wrong IP +address. Setting this option also reduces the risk for various sorts of client +abuse by malicious servers. + +This option has no effect if PORT, EPRT or EPSV is used instead of PASV. +.SH DEFAULT +1 since 7.74.0, was 0 before then. +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); + + /* please ignore the IP in the PASV response */ + curl_easy_setopt(curl, CURLOPT_FTP_SKIP_PASV_IP, 1L); + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.15.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FTPPORT (3), +.BR CURLOPT_FTP_USE_EPRT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FTP_SSL_CCC.3 b/3rdparty/curl/share/man/man3/CURLOPT_FTP_SSL_CCC.3 new file mode 100644 index 0000000..ca43420 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FTP_SSL_CCC.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FTP_SSL_CCC.md +.TH CURLOPT_FTP_SSL_CCC 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FTP_SSL_CCC \- switch off SSL again with FTP after auth +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SSL_CCC, + long how); +.fi +.SH DESCRIPTION +If enabled, this option makes libcurl use CCC (Clear Command Channel). It +shuts down the SSL/TLS layer after authenticating. The rest of the control +channel communication remains unencrypted. This allows NAT routers to follow +the FTP transaction. Pass a long using one of the values below +.IP CURLFTPSSL_CCC_NONE +do not attempt to use CCC. +.IP CURLFTPSSL_CCC_PASSIVE +Do not initiate the shutdown, but wait for the server to do it. Do not send a +reply. +.IP CURLFTPSSL_CCC_ACTIVE +Initiate the shutdown and wait for a reply. +.SH DEFAULT +CURLFTPSSL_CCC_NONE +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); + curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_CONTROL); + /* go back to clear-text FTP after authenticating */ + curl_easy_setopt(curl, CURLOPT_FTP_SSL_CCC, (long)CURLFTPSSL_CCC_ACTIVE); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FTPSSLAUTH (3), +.BR CURLOPT_PROTOCOLS_STR (3), +.BR CURLOPT_USE_SSL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FTP_USE_EPRT.3 b/3rdparty/curl/share/man/man3/CURLOPT_FTP_USE_EPRT.3 new file mode 100644 index 0000000..b504282 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FTP_USE_EPRT.3 @@ -0,0 +1,55 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FTP_USE_EPRT.md +.TH CURLOPT_FTP_USE_EPRT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FTP_USE_EPRT \- use EPRT for FTP +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPRT, long enabled); +.fi +.SH DESCRIPTION +Pass a long. If the value is 1, it tells curl to use the EPRT command when +doing active FTP downloads (which is enabled by +\fICURLOPT_FTPPORT(3)\fP). Using EPRT means that libcurl first attempts to use +EPRT before using PORT, but if you pass zero to this option, it avoids using +EPRT, only plain PORT. + +The EPRT command is a slightly newer addition to the FTP protocol than PORT +and is the preferred command to use since it enables IPv6 to be used. Old FTP +servers might not support it, which is why libcurl has a fallback mechanism. +Sometimes that fallback is not enough and then this option might come handy. + +If the server is an IPv6 host, this option has no effect as EPRT is necessary +then. +.SH DEFAULT +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); + + /* contact us back, aka "active" FTP */ + curl_easy_setopt(curl, CURLOPT_FTPPORT, "-"); + + /* FTP the way the neanderthals did it */ + curl_easy_setopt(curl, CURLOPT_FTP_USE_EPRT, 0L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.5 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_FTPPORT (3), +.BR CURLOPT_FTP_USE_EPSV (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FTP_USE_EPSV.3 b/3rdparty/curl/share/man/man3/CURLOPT_FTP_USE_EPSV.3 new file mode 100644 index 0000000..9d1694b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FTP_USE_EPSV.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FTP_USE_EPSV.md +.TH CURLOPT_FTP_USE_EPSV 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FTP_USE_EPSV \- use EPSV for FTP +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPSV, long epsv); +.fi +.SH DESCRIPTION +Pass \fIepsv\fP as a long. If the value is 1, it tells curl to use the EPSV +command when doing passive FTP downloads (which it does by default). Using +EPSV means that libcurl first attempts to use the EPSV command before using +PASV. If you pass zero to this option, it does not use EPSV, only plain PASV. + +The EPSV command is a slightly newer addition to the FTP protocol than PASV +and is the preferred command to use since it enables IPv6 to be used. Old FTP +servers might not support it, which is why libcurl has a fallback mechanism. +Sometimes that fallback is not enough and then this option might come handy. + +If the server is an IPv6 host, this option has no effect. +.SH DEFAULT +1 +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/old-server/file.txt"); + + /* let's shut off this modern feature */ + curl_easy_setopt(curl, CURLOPT_FTP_USE_EPSV, 0L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.2 +.SH RETURN VALUE +Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FTPPORT (3), +.BR CURLOPT_FTP_USE_EPRT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_FTP_USE_PRET.3 b/3rdparty/curl/share/man/man3/CURLOPT_FTP_USE_PRET.3 new file mode 100644 index 0000000..ada7cdd --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_FTP_USE_PRET.3 @@ -0,0 +1,45 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_FTP_USE_PRET.md +.TH CURLOPT_FTP_USE_PRET 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_FTP_USE_PRET \- use PRET for FTP +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_PRET, long enable); +.fi +.SH DESCRIPTION +Pass a long. If the value is 1, it tells curl to send a PRET command before +PASV (and EPSV). Certain FTP servers, mainly drftpd, require this non\-standard +command for directory listings as well as up and downloads in PASV mode. Has +no effect when using the active FTP transfers mode. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/old-server/file.txt"); + + /* a drftpd server, do it! */ + curl_easy_setopt(curl, CURLOPT_FTP_USE_PRET, 1L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FTP_USE_EPRT (3), +.BR CURLOPT_FTP_USE_EPSV (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_GSSAPI_DELEGATION.3 b/3rdparty/curl/share/man/man3/CURLOPT_GSSAPI_DELEGATION.3 new file mode 100644 index 0000000..bb57c17 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_GSSAPI_DELEGATION.3 @@ -0,0 +1,44 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_GSSAPI_DELEGATION.md +.TH CURLOPT_GSSAPI_DELEGATION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_GSSAPI_DELEGATION \- allowed GSS\-API delegation +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_GSSAPI_DELEGATION, long level); +.fi +.SH DESCRIPTION +Set the long parameter \fIlevel\fP to \fBCURLGSSAPI_DELEGATION_FLAG\fP to allow +unconditional GSSAPI credential delegation. The delegation is disabled by +default since 7.21.7. Set the parameter to +\fBCURLGSSAPI_DELEGATION_POLICY_FLAG\fP to delegate only if the OK\-AS\-DELEGATE +flag is set in the service ticket in case this feature is supported by the +GSS\-API implementation and the definition of \fIGSS_C_DELEG_POLICY_FLAG\fP was +available at compile\-time. +.SH DEFAULT +CURLGSSAPI_DELEGATION_NONE +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* delegate if okayed by policy */ + curl_easy_setopt(curl, CURLOPT_GSSAPI_DELEGATION, + (long)CURLGSSAPI_DELEGATION_POLICY_FLAG); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.22.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTPAUTH (3), +.BR CURLOPT_PROXYAUTH (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 b/3rdparty/curl/share/man/man3/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 new file mode 100644 index 0000000..dd42c24 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md +.TH CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS \- head start for IPv6 for happy eyeballs +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, + long timeout); +.fi +.SH DESCRIPTION +Happy eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6 +addresses for dual\-stack hosts, preferring IPv6 first for \fItimeout\fP +milliseconds. If the IPv6 address cannot be connected to within that time then +a connection attempt is made to the IPv4 address in parallel. The first +connection to be established is the one that is used. + +The range of suggested useful values for \fItimeout\fP is limited. Happy +Eyeballs RFC 6555 says "It is RECOMMENDED that connection attempts be paced +150\-250 ms apart to balance human factors against network load." libcurl +currently defaults to 200 ms. Firefox and Chrome currently default to 300 ms. +.SH DEFAULT +CURL_HET_DEFAULT (currently defined as 200L) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, 300L); + + curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.59.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_CONNECTTIMEOUT_MS (3), +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HAPROXYPROTOCOL.3 b/3rdparty/curl/share/man/man3/CURLOPT_HAPROXYPROTOCOL.3 new file mode 100644 index 0000000..ca9a9b3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HAPROXYPROTOCOL.3 @@ -0,0 +1,43 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HAPROXYPROTOCOL.md +.TH CURLOPT_HAPROXYPROTOCOL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HAPROXYPROTOCOL \- send HAProxy PROXY protocol v1 header +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPROXYPROTOCOL, + long haproxy_protocol); +.fi +.SH DESCRIPTION +A long parameter set to 1 tells the library to send an HAProxy PROXY +protocol v1 header at beginning of the connection. The default action is not to +send this header. + +This option is primarily useful when sending test requests to a service that +expects this header. + +Most applications do not need this option. +.SH DEFAULT +0, do not send any HAProxy PROXY protocol header +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_HAPROXYPROTOCOL, 1L); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.60.0 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_PROXY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HAPROXY_CLIENT_IP.3 b/3rdparty/curl/share/man/man3/CURLOPT_HAPROXY_CLIENT_IP.3 new file mode 100644 index 0000000..a2bda99 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HAPROXY_CLIENT_IP.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HAPROXY_CLIENT_IP.md +.TH CURLOPT_HAPROXY_CLIENT_IP 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HAPROXY_CLIENT_IP \- set HAProxy PROXY protocol client IP +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPROXY_CLIENT_IP, + char *client_ip); +.fi +.SH DESCRIPTION +When this parameter is set to a valid IPv4 or IPv6 numerical address, the +library sends this address as client address in the HAProxy PROXY protocol v1 +header at beginning of the connection. + +This option is an alternative to \fICURLOPT_HAPROXYPROTOCOL(3)\fP as that one cannot +use a specified address. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +NULL, no HAProxy header is sent +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_HAPROXY_CLIENT_IP, "1.1.1.1"); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 8.2.0 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HAPROXYPROTOCOL (3), +.BR CURLOPT_PROXY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HEADER.3 b/3rdparty/curl/share/man/man3/CURLOPT_HEADER.3 new file mode 100644 index 0000000..e65d53e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HEADER.3 @@ -0,0 +1,55 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HEADER.md +.TH CURLOPT_HEADER 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HEADER \- pass headers to the data stream +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADER, long onoff); +.fi +.SH DESCRIPTION +Pass the long value \fIonoff\fP set to 1 to ask libcurl to include the headers +in the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP). This option is +relevant for protocols that actually have headers or other meta\-data (like +HTTP and FTP). + +When asking to get the headers passed to the same callback as the body, it is +not possible to accurately separate them again without detailed knowledge +about the protocol in use. + +Further: the \fICURLOPT_WRITEFUNCTION(3)\fP callback is limited to only ever +get a maximum of \fICURL_MAX_WRITE_SIZE\fP bytes passed to it (16KB), while a +header can be longer and the \fICURLOPT_HEADERFUNCTION(3)\fP supports getting +called with headers up to \fICURL_MAX_HTTP_HEADER\fP bytes big (100KB). + +It is often better to use \fICURLOPT_HEADERFUNCTION(3)\fP to get the header +data separately. + +While named confusingly similar, \fICURLOPT_HTTPHEADER(3)\fP is used to set +custom HTTP headers! +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects ftp, http, imap, pop3 and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_HEADER, 1L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_HEADERFUNCTION (3), +.BR CURLOPT_HTTPHEADER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HEADERDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_HEADERDATA.3 new file mode 100644 index 0000000..88f0db3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HEADERDATA.3 @@ -0,0 +1,68 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HEADERDATA.md +.TH CURLOPT_HEADERDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HEADERDATA \- pointer to pass to header callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERDATA, void *pointer); +.fi +.SH DESCRIPTION +Pass a \fIpointer\fP to be used to write the header part of the received data +to. + +If \fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP is used, +\fIpointer\fP is passed in to the respective callback. + +If neither of those options are set, \fIpointer\fP must be a valid FILE * and +it is used by a plain fwrite() to write headers to. + +If you are using libcurl as a Windows DLL, you \fBMUST\fP use a +\fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP if you set +this option or you might experience crashes. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct my_info { + int shoesize; + char *secret; +}; + +static size_t header_callback(char *buffer, size_t size, + size_t nitems, void *userdata) +{ + struct my_info *i = userdata; + printf("shoe size: %d\\n", i->shoesize); + /* now this callback can access the my_info struct */ + + return nitems * size; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct my_info my = { 10, "the cookies are in the cupboard" }; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback); + + /* pass in custom data to the callback */ + curl_easy_setopt(curl, CURLOPT_HEADERDATA, &my); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_HEADERFUNCTION (3), +.BR CURLOPT_WRITEFUNCTION (3), +.BR curl_easy_header (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HEADERFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_HEADERFUNCTION.3 new file mode 100644 index 0000000..605c5f8 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HEADERFUNCTION.3 @@ -0,0 +1,108 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HEADERFUNCTION.md +.TH CURLOPT_HEADERFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HEADERFUNCTION \- callback that receives header data +.SH SYNOPSIS +.nf +#include + +size_t header_callback(char *buffer, + size_t size, + size_t nitems, + void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERFUNCTION, + header_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets invoked by libcurl as soon as it has received +header data. The header callback is called once for each header and only +complete header lines are passed on to the callback. Parsing headers is easy +to do using this callback. \fIbuffer\fP points to the delivered data, and the +size of that data is \fInitems\fP; \fIsize\fP is always 1. The provide header +line is not null\-terminated! + +The pointer named \fIuserdata\fP is the one you set with the +\fICURLOPT_HEADERDATA(3)\fP option. + +Your callback should return the number of bytes actually taken care of. If +that amount differs from the amount passed to your callback function, it +signals an error condition to the library. This causes the transfer to get +aborted and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. + +You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0) + +A complete HTTP header that is passed to this function can be up to +\fICURL_MAX_HTTP_HEADER\fP (100K) bytes and includes the final line terminator. + +If this option is not set, or if it is set to NULL, but +\fICURLOPT_HEADERDATA(3)\fP is set to anything but NULL, the function used to +accept response data is used instead. That is the function specified with +\fICURLOPT_WRITEFUNCTION(3)\fP, or if it is not specified or NULL \- the +default, stream\-writing function. + +It is important to note that the callback is invoked for the headers of all +responses received after initiating a request and not just the final +response. This includes all responses which occur during authentication +negotiation. If you need to operate on only the headers from the final +response, you need to collect headers in the callback yourself and use HTTP +status lines, for example, to delimit response boundaries. + +For an HTTP transfer, the status line and the blank line preceding the response +body are both included as headers and passed to this function. + +When a server sends a chunked encoded transfer, it may contain a trailer. That +trailer is identical to an HTTP header and if such a trailer is received it is +passed to the application using this callback as well. There are several ways +to detect it being a trailer and not an ordinary header: 1) it comes after the +response\-body. 2) it comes after the final header line (CR LF) 3) a Trailer: +header among the regular response\-headers mention what header(s) to expect in +the trailer. + +For non\-HTTP protocols like FTP, POP3, IMAP and SMTP this function gets called +with the server responses to the commands that libcurl sends. + +A more convenient way to get HTTP headers might be to use +\fIcurl_easy_header(3)\fP. +.SH LIMITATIONS +libcurl does not unfold HTTP "folded headers" (deprecated since RFC 7230). A +folded header is a header that continues on a subsequent line and starts with +a whitespace. Such folds are passed to the header callback as separate ones, +although strictly they are just continuations of the previous lines. +.SH DEFAULT +Nothing. +.SH PROTOCOLS +This functionality affects ftp, http, imap, pop3 and smtp +.SH EXAMPLE +.nf +static size_t header_callback(char *buffer, size_t size, + size_t nitems, void *userdata) +{ + /* received header is nitems * size long in 'buffer' NOT ZERO TERMINATED */ + /* 'userdata' is set with CURLOPT_HEADERDATA */ + return nitems * size; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.7.2 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_HEADERDATA (3), +.BR CURLOPT_WRITEFUNCTION (3), +.BR curl_easy_header (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HEADEROPT.3 b/3rdparty/curl/share/man/man3/CURLOPT_HEADEROPT.3 new file mode 100644 index 0000000..2be880b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HEADEROPT.3 @@ -0,0 +1,60 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HEADEROPT.md +.TH CURLOPT_HEADEROPT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HEADEROPT \- send HTTP headers to both proxy and host or separately +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADEROPT, long bitmask); +.fi +.SH DESCRIPTION +Pass a long that is a bitmask of options of how to deal with headers. The two +mutually exclusive options are: + +\fBCURLHEADER_UNIFIED\fP \- the headers specified in +\fICURLOPT_HTTPHEADER(3)\fP are used in requests both to servers and +proxies. With this option enabled, \fICURLOPT_PROXYHEADER(3)\fP does not have +any effect. + +\fBCURLHEADER_SEPARATE\fP \- makes \fICURLOPT_HTTPHEADER(3)\fP headers only get +sent to a server and not to a proxy. Proxy headers must be set with +\fICURLOPT_PROXYHEADER(3)\fP to get used. Note that if a non\-CONNECT request +is sent to a proxy, libcurl sends both server headers and proxy headers. When +doing CONNECT, libcurl sends \fICURLOPT_PROXYHEADER(3)\fP headers only to the +proxy and then \fICURLOPT_HTTPHEADER(3)\fP headers only to the server. +.SH DEFAULT +CURLHEADER_SEPARATE (changed in 7.42.1, used CURLHEADER_UNIFIED before then) +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + struct curl_slist *list; + list = curl_slist_append(NULL, "Shoesize: 10"); + list = curl_slist_append(list, "Accept:"); + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); + curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list); + + /* HTTPS over a proxy makes a separate CONNECT to the proxy, so tell + libcurl to not send the custom headers to the proxy. Keep them + separate! */ + curl_easy_setopt(curl, CURLOPT_HEADEROPT, CURLHEADER_SEPARATE); + ret = curl_easy_perform(curl); + curl_slist_free_all(list); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.37.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTPHEADER (3), +.BR CURLOPT_PROXYHEADER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HSTS.3 b/3rdparty/curl/share/man/man3/CURLOPT_HSTS.3 new file mode 100644 index 0000000..98d9539 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HSTS.3 @@ -0,0 +1,63 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HSTS.md +.TH CURLOPT_HSTS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HSTS \- HSTS cache filename +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS, char *filename); +.fi +.SH DESCRIPTION +Make the \fIfilename\fP point to a filename to load an existing HSTS cache +from, and to store the cache in when the easy handle is closed. Setting a file +name with this option also enables HSTS for this handle (the equivalent of +setting \fICURLHSTS_ENABLE\fP with \fICURLOPT_HSTS_CTRL(3)\fP). + +If the given file does not exist or contains no HSTS entries at startup, the +HSTS cache simply starts empty. Setting the filename to NULL allows HSTS +without reading from or writing to any file. NULL also makes libcurl clear the +list of files to read HSTS data from, if any such were previously set. + +If this option is set multiple times, libcurl loads cache entries from each +given file but only stores the last used name for later writing. +.SH FILE FORMAT +The HSTS cache is saved to and loaded from a text file with one entry per +physical line. Each line in the file has the following format: + +.nf +[host] [stamp] +.fi + +[host] is the domain name for the entry and the name is dot\-prefixed if it is +an entry valid for all subdomains to the name as well or only for the exact +name. + +[stamp] is the time (in UTC) when the entry expires and it uses the format +\&"YYYYMMDD HH:MM:SS". + +Lines starting with "#" are treated as comments and are ignored. There is +currently no length or size limit. +.SH DEFAULT +NULL, no filename +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_HSTS, "/home/user/.hsts-cache"); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.74.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_ALTSVC (3), +.BR CURLOPT_HSTS_CTRL (3), +.BR CURLOPT_RESOLVE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HSTSREADDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_HSTSREADDATA.3 new file mode 100644 index 0000000..cb1098d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HSTSREADDATA.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HSTSREADDATA.md +.TH CURLOPT_HSTSREADDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HSTSREADDATA \- pointer passed to the HSTS read callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADDATA, void *pointer); +.fi +.SH DESCRIPTION +Data \fIpointer\fP to pass to the HSTS read function. If you use the +\fICURLOPT_HSTSREADFUNCTION(3)\fP option, this is the pointer you get as input +in the 3rd argument to the callback. + +This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to +do that. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +struct MyData { + void *custom; +}; + +int main(void) +{ + CURL *curl = curl_easy_init(); + struct MyData this; + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* pass pointer that gets passed in to the + CURLOPT_HSTSREADFUNCTION callback */ + curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &this); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.74.0 +.SH RETURN VALUE +This returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_HSTS (3), +.BR CURLOPT_HSTSREADFUNCTION (3), +.BR CURLOPT_HSTSWRITEDATA (3), +.BR CURLOPT_HSTSWRITEFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HSTSREADFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_HSTSREADFUNCTION.3 new file mode 100644 index 0000000..0027b35 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HSTSREADFUNCTION.3 @@ -0,0 +1,85 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HSTSREADFUNCTION.md +.TH CURLOPT_HSTSREADFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HSTSREADFUNCTION \- read callback for HSTS hosts +.SH SYNOPSIS +.nf +#include + +struct curl_hstsentry { + char *name; + size_t namelen; + unsigned int includeSubDomains:1; + char expire[18]; /* YYYYMMDD HH:MM:SS [null-terminated] */ +}; + +CURLSTScode hstsread(CURL *easy, struct curl_hstsentry *sts, void *clientp); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADFUNCTION, hstsread); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, as the prototype shows above. + +This callback function gets called by libcurl repeatedly when it populates the +in\-memory HSTS cache. + +Set the \fIclientp\fP argument with the \fICURLOPT_HSTSREADDATA(3)\fP option +or it is NULL. + +When this callback is invoked, the \fIsts\fP pointer points to a populated +struct: Copy the hostname to \fIname\fP (no longer than \fInamelen\fP +bytes). Make it null\-terminated. Set \fIincludeSubDomains\fP to TRUE or +FALSE. Set \fIexpire\fP to a date stamp or a zero length string for \fIforever\fP +(wrong date stamp format might cause the name to not get accepted) + +The callback should return \fICURLSTS_OK\fP if it returns a name and is +prepared to be called again (for another host) or \fICURLSTS_DONE\fP if it has +no entry to return. It can also return \fICURLSTS_FAIL\fP to signal +error. Returning \fICURLSTS_FAIL\fP stops the transfer from being performed +and make \fICURLE_ABORTED_BY_CALLBACK\fP get returned. + +This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to +do that. +.SH DEFAULT +NULL \- no callback. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +struct priv { + void *custom; +}; + +static CURLSTScode hsts_cb(CURL *easy, struct curl_hstsentry *sts, + void *clientp) +{ + /* populate the struct as documented */ + return CURLSTS_OK; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct priv my_stuff; + CURLcode res; + + /* set HSTS read callback */ + curl_easy_setopt(curl, CURLOPT_HSTSREADFUNCTION, hsts_cb); + + /* pass in suitable argument to the callback */ + curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &my_stuff); + + res = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.74.0 +.SH RETURN VALUE +This returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_HSTS (3), +.BR CURLOPT_HSTSREADDATA (3), +.BR CURLOPT_HSTSWRITEFUNCTION (3), +.BR CURLOPT_HSTS_CTRL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HSTSWRITEDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_HSTSWRITEDATA.3 new file mode 100644 index 0000000..b5c67da --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HSTSWRITEDATA.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HSTSWRITEDATA.md +.TH CURLOPT_HSTSWRITEDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HSTSWRITEDATA \- pointer passed to the HSTS write callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEDATA, void *pointer); +.fi +.SH DESCRIPTION +Data \fIpointer\fP to pass to the HSTS write function. If you use the +\fICURLOPT_HSTSWRITEFUNCTION(3)\fP option, this is the pointer you get as +input in the fourth argument to the callback. + +This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to +do that. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +struct MyData { + void *custom; +}; + +int main(void) +{ + CURL *curl = curl_easy_init(); + struct MyData this; + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* pass pointer that gets passed in to the + CURLOPT_HSTSWRITEFUNCTION callback */ + curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &this); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.74.0 +.SH RETURN VALUE +This returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_HSTS (3), +.BR CURLOPT_HSTSREADDATA (3), +.BR CURLOPT_HSTSREADFUNCTION (3), +.BR CURLOPT_HSTSWRITEFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HSTSWRITEFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_HSTSWRITEFUNCTION.3 new file mode 100644 index 0000000..0a335c0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HSTSWRITEFUNCTION.3 @@ -0,0 +1,89 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HSTSWRITEFUNCTION.md +.TH CURLOPT_HSTSWRITEFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HSTSWRITEFUNCTION \- write callback for HSTS hosts +.SH SYNOPSIS +.nf +#include + +struct curl_hstsentry { + char *name; + size_t namelen; + unsigned int includeSubDomains:1; + char expire[18]; /* YYYYMMDD HH:MM:SS [null-terminated] */ +}; + +struct curl_index { + size_t index; /* the provided entry's "index" or count */ + size_t total; /* total number of entries to save */ +}; + +CURLSTScode hstswrite(CURL *easy, struct curl_hstsentry *sts, + struct curl_index *count, void *clientp); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEFUNCTION, hstswrite); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, as the prototype shows above. + +This callback function gets called by libcurl repeatedly to allow the +application to store the in\-memory HSTS cache when libcurl is about to discard +it. + +Set the \fIclientp\fP argument with the \fICURLOPT_HSTSWRITEDATA(3)\fP option +or it is NULL. +When the callback is invoked, the \fIsts\fP pointer points to a populated +struct: Read the hostname to \(aqname\(aq (it is \fInamelen\fP bytes long and null +terminated. The \fIincludeSubDomains\fP field is non\-zero if the entry matches +subdomains. The \fIexpire\fP string is a date stamp null\-terminated string +using the syntax YYYYMMDD HH:MM:SS. + +The callback should return \fICURLSTS_OK\fP if it succeeded and is prepared to +be called again (for another host) or \fICURLSTS_DONE\fP if there is nothing +more to do. It can also return \fICURLSTS_FAIL\fP to signal error. + +This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to +do that. +.SH DEFAULT +NULL \- no callback. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +struct priv { + void *custom; +}; + +static CURLSTScode hswr_cb(CURL *easy, struct curl_hstsentry *sts, + struct curl_index *count, void *clientp) +{ + /* save the passed in HSTS data somewhere */ + return CURLSTS_OK; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct priv my_stuff; + CURLcode res; + + /* set HSTS read callback */ + curl_easy_setopt(curl, CURLOPT_HSTSWRITEFUNCTION, hswr_cb); + + /* pass in suitable argument to the callback */ + curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &my_stuff); + + res = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.74.0 +.SH RETURN VALUE +This returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_HSTS (3), +.BR CURLOPT_HSTSWRITEDATA (3), +.BR CURLOPT_HSTSWRITEFUNCTION (3), +.BR CURLOPT_HSTS_CTRL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HSTS_CTRL.3 b/3rdparty/curl/share/man/man3/CURLOPT_HSTS_CTRL.3 new file mode 100644 index 0000000..6119b9e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HSTS_CTRL.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HSTS_CTRL.md +.TH CURLOPT_HSTS_CTRL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HSTS_CTRL \- control HSTS behavior +.SH SYNOPSIS +.nf +#include + +#define CURLHSTS_ENABLE (1<<0) +#define CURLHSTS_READONLYFILE (1<<1) + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS_CTRL, long bitmask); +.fi +.SH DESCRIPTION +HSTS (HTTP Strict Transport Security) means that an HTTPS server can instruct +the client to not contact it again over clear\-text HTTP for a certain period +into the future. libcurl then automatically redirects HTTP attempts to such +hosts to instead use HTTPS. This is done by libcurl retaining this knowledge +in an in\-memory cache. + +Populate the long \fIbitmask\fP with the correct set of features to instruct +libcurl how to handle HSTS for the transfers using this handle. +.SH BITS +.IP CURLHSTS_ENABLE +Enable the in\-memory HSTS cache for this handle. +.IP CURLHSTS_READONLYFILE +Make the HSTS file (if specified) read\-only \- makes libcurl not save the cache +to the file when closing the handle. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_HSTS_CTRL, (long)CURLHSTS_ENABLE); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.74.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_ALTSVC (3), +.BR CURLOPT_CONNECT_TO (3), +.BR CURLOPT_HSTS (3), +.BR CURLOPT_RESOLVE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HTTP09_ALLOWED.3 b/3rdparty/curl/share/man/man3/CURLOPT_HTTP09_ALLOWED.3 new file mode 100644 index 0000000..9601ed7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HTTP09_ALLOWED.3 @@ -0,0 +1,45 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HTTP09_ALLOWED.md +.TH CURLOPT_HTTP09_ALLOWED 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HTTP09_ALLOWED \- allow HTTP/0.9 response +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP09_ALLOWED, long allowed); +.fi +.SH DESCRIPTION +Pass the long argument \fIallowed\fP set to 1L to allow HTTP/0.9 responses. + +An HTTP/0.9 response is a server response entirely without headers and only a +body. You can connect to lots of random TCP services and still get a response +that curl might consider to be HTTP/0.9! +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_HTTP09_ALLOWED, 1L); + ret = curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +curl allowed HTTP/0.9 responses by default before 7.66.0 + +Since 7.66.0, libcurl requires this option set to 1L to allow HTTP/0.9 +responses. +.SH AVAILABILITY +Added in curl 7.64.0 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTP_VERSION (3), +.BR CURLOPT_SSLVERSION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HTTP200ALIASES.3 b/3rdparty/curl/share/man/man3/CURLOPT_HTTP200ALIASES.3 new file mode 100644 index 0000000..5daf8c3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HTTP200ALIASES.3 @@ -0,0 +1,60 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HTTP200ALIASES.md +.TH CURLOPT_HTTP200ALIASES 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HTTP200ALIASES \- alternative matches for HTTP 200 OK +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP200ALIASES, + struct curl_slist *aliases); +.fi +.SH DESCRIPTION +Pass a pointer to a linked list of \fIaliases\fP to be treated as valid HTTP 200 +responses. Some servers respond with a custom header response line. For +example, SHOUTcast servers respond with "ICY 200 OK". Also some old Icecast +1.3.x servers respond like that for certain user agent headers or in absence +of such. By including this string in your list of aliases, the response gets +treated as a valid HTTP header line such as "HTTP/1.0 200 OK". + +The linked list should be a fully valid list of struct curl_slist structs, and +be properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and +\fIcurl_slist_free_all(3)\fP to clean up an entire list. + +The alias itself is not parsed for any version strings. The protocol is +assumed to match HTTP 1.0 when an alias match. + +Using this option multiple times makes the last set list override the previous +ones. Set it to NULL to disable its use again. + +libcurl does not copy the list, it needs to be kept around until after the +transfer has completed. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct curl_slist *list; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + list = curl_slist_append(NULL, "ICY 200 OK"); + list = curl_slist_append(list, "WEIRDO 99 FINE"); + + curl_easy_setopt(curl, CURLOPT_HTTP200ALIASES, list); + curl_easy_perform(curl); + curl_slist_free_all(list); /* free the list again */ + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.3 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTP09_ALLOWED (3), +.BR CURLOPT_HTTP_VERSION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HTTPAUTH.3 b/3rdparty/curl/share/man/man3/CURLOPT_HTTPAUTH.3 new file mode 100644 index 0000000..12ebd42 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HTTPAUTH.3 @@ -0,0 +1,122 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HTTPAUTH.md +.TH CURLOPT_HTTPAUTH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HTTPAUTH \- HTTP server authentication methods to try +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPAUTH, long bitmask); +.fi +.SH DESCRIPTION +Pass a long as parameter, which is set to a bitmask, to tell libcurl which +authentication method(s) you want it to use speaking to the remote server. + +The available bits are listed below. If more than one bit is set, libcurl +first queries the host to see which authentication methods it supports and +then picks the best one you allow it to use. For some methods, this induces an +extra network round\-trip. Set the actual name and password with the +\fICURLOPT_USERPWD(3)\fP option or with the \fICURLOPT_USERNAME(3)\fP and the +\fICURLOPT_PASSWORD(3)\fP options. + +For authentication with a proxy, see \fICURLOPT_PROXYAUTH(3)\fP. +.IP CURLAUTH_BASIC +HTTP Basic authentication. This is the default choice, and the only method +that is in wide\-spread use and supported virtually everywhere. This sends +the username and password over the network in plain text, easily captured by +others. +.IP CURLAUTH_DIGEST +HTTP Digest authentication. Digest authentication is defined in RFC 2617 and +is a more secure way to do authentication over public networks than the +regular old\-fashioned Basic method. +.IP CURLAUTH_DIGEST_IE +HTTP Digest authentication with an IE flavor. Digest authentication is defined +in RFC 2617 and is a more secure way to do authentication over public networks +than the regular old\-fashioned Basic method. The IE flavor is simply that +libcurl uses a special "quirk" that IE is known to have used before version 7 +and that some servers require the client to use. +.IP CURLAUTH_BEARER +HTTP Bearer token authentication, used primarily in OAuth 2.0 protocol. + +You can set the Bearer token to use with \fICURLOPT_XOAUTH2_BEARER(3)\fP. +.IP CURLAUTH_NEGOTIATE +HTTP Negotiate (SPNEGO) authentication. Negotiate authentication is defined +in RFC 4559 and is the most secure way to perform authentication over HTTP. + +You need to build libcurl with a suitable GSS\-API library or SSPI on Windows +for this to work. +.IP CURLAUTH_NTLM +HTTP NTLM authentication. A proprietary protocol invented and used by +Microsoft. It uses a challenge\-response and hash concept similar to Digest, to +prevent the password from being eavesdropped. + +You need to build libcurl with either OpenSSL or GnuTLS support for this +option to work, or build libcurl on Windows with SSPI support. +.IP CURLAUTH_NTLM_WB +Support for this is removed since libcurl 8.8.0. + +NTLM delegating to winbind helper. Authentication is performed by a separate +binary application that is executed when needed. The name of the application +is specified at compile time but is typically \fB/usr/bin/ntlm_auth\fP. + +Note that libcurl forks when necessary to run the winbind application and kill +it when complete, calling \fBwaitpid()\fP to await its exit when done. On POSIX +operating systems, killing the process causes a SIGCHLD signal to be raised +(regardless of whether \fICURLOPT_NOSIGNAL(3)\fP is set), which must be handled +intelligently by the application. In particular, the application must not +unconditionally call wait() in its SIGCHLD signal handler to avoid being +subject to a race condition. This behavior is subject to change in future +versions of libcurl. +.IP CURLAUTH_ANY +This is a convenience macro that sets all bits and thus makes libcurl pick any +it finds suitable. libcurl automatically selects the one it finds most secure. +.IP CURLAUTH_ANYSAFE +This is a convenience macro that sets all bits except Basic and thus makes +libcurl pick any it finds suitable. libcurl automatically selects the one it +finds most secure. +.IP CURLAUTH_ONLY +This is a meta symbol. OR this value together with a single specific auth +value to force libcurl to probe for unrestricted auth and if not, only that +single auth algorithm is acceptable. +.IP CURLAUTH_AWS_SIGV4 +provides AWS V4 signature authentication on HTTPS header +see \fICURLOPT_AWS_SIGV4(3)\fP. +.SH DEFAULT +CURLAUTH_BASIC +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* allow whatever auth the server speaks */ + curl_easy_setopt(curl, CURLOPT_HTTPAUTH, (long)CURLAUTH_ANY); + curl_easy_setopt(curl, CURLOPT_USERPWD, "james:bond"); + ret = curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +CURLAUTH_DIGEST_IE was added in 7.19.3 + +CURLAUTH_ONLY was added in 7.21.3 + +CURLAUTH_NTLM_WB was added in 7.22.0 + +CURLAUTH_BEARER was added in 7.61.0 + +CURLAUTH_AWS_SIGV4 was added in 7.74.0 +.SH AVAILABILITY +Added in curl 7.10.6 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication +methods. +.SH SEE ALSO +.BR CURLOPT_PASSWORD (3), +.BR CURLOPT_PROXYAUTH (3), +.BR CURLOPT_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HTTPGET.3 b/3rdparty/curl/share/man/man3/CURLOPT_HTTPGET.3 new file mode 100644 index 0000000..3cb9451 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HTTPGET.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HTTPGET.md +.TH CURLOPT_HTTPGET 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HTTPGET \- ask for an HTTP GET request +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPGET, long useget); +.fi +.SH DESCRIPTION +Pass a long. If \fIuseget\fP is 1, this forces the HTTP request to get back to +using GET. Usable if a POST, HEAD, PUT, etc has been used previously using the +same curl \fIhandle\fP. + +When setting \fICURLOPT_HTTPGET(3)\fP to 1, libcurl automatically sets +\fICURLOPT_NOBODY(3)\fP to 0 and \fICURLOPT_UPLOAD(3)\fP to 0. + +Setting this option to zero has no effect. Applications need to explicitly +select which HTTP request method to use, they cannot deselect a method. To +reset a handle to default method, consider \fIcurl_easy_reset(3)\fP. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* use a GET to fetch this */ + curl_easy_setopt(curl, CURLOPT_HTTPGET, 1L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.8.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_NOBODY (3), +.BR CURLOPT_POST (3), +.BR CURLOPT_UPLOAD (3), +.BR curl_easy_reset (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HTTPHEADER.3 b/3rdparty/curl/share/man/man3/CURLOPT_HTTPHEADER.3 new file mode 100644 index 0000000..439c18f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HTTPHEADER.3 @@ -0,0 +1,147 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HTTPHEADER.md +.TH CURLOPT_HTTPHEADER 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HTTPHEADER \- set of HTTP headers +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPHEADER, + struct curl_slist *headers); +.fi +.SH DESCRIPTION +Pass a pointer to a linked list of HTTP headers to pass to the server and/or +proxy in your HTTP request. The same list can be used for both host and proxy +requests! + +When used within an IMAP or SMTP request to upload a MIME mail, the given +header list establishes the document\-level MIME headers to prepend to the +uploaded document described by \fICURLOPT_MIMEPOST(3)\fP. This does not affect raw +mail uploads. + +The linked list should be a fully valid list of \fBstruct curl_slist\fP structs +properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and +\fIcurl_slist_free_all(3)\fP to clean up an entire list. If you add a header that is +otherwise generated and used by libcurl internally, your added header is used +instead. If you add a header with no content as in \(aqAccept:\(aq (no data on the +right side of the colon), the internally used header is disabled/removed. With +this option you can add new headers, replace internal headers and remove +internal headers. To add a header with no content (nothing to the right side +of the colon), use the form \(aqname;\(aq (note the ending semicolon). + +The headers included in the linked list \fBmust not\fP be CRLF\-terminated, +because libcurl adds CRLF after each header item itself. Failure to comply +with this might result in strange behavior. libcurl passes on the verbatim +strings you give it, without any filter or other safe guards. That includes +white space and control characters. + +The first line in an HTTP request (containing the method, usually a GET or +POST) is not a header and cannot be replaced using this option. Only the lines +following the request\-line are headers. Adding this method line in this list +of headers only causes your request to send an invalid header. Use +\fICURLOPT_CUSTOMREQUEST(3)\fP to change the method. + +When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl does not copy the +entire list so you \fBmust\fP keep it around until you no longer use this +\fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on the list. + +Using this option multiple times makes the last set list override the previous +ones. Set it to NULL to disable its use again. + +The most commonly replaced HTTP headers have "shortcuts" in the options +\fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP and \fICURLOPT_REFERER(3)\fP. We recommend +using those. + +There is an alternative option that sets or replaces headers only for requests +that are sent with CONNECT to a proxy: \fICURLOPT_PROXYHEADER(3)\fP. Use +\fICURLOPT_HEADEROPT(3)\fP to control the behavior. +.SH SPECIFIC HTTP HEADERS +Setting some specific headers causes libcurl to act differently. +.IP Host: +The specified hostname is used for cookie matching if the cookie engine is +also enabled for this transfer. If the request is done over HTTP/2 or HTTP/3, +the custom hostname is instead used in the ":authority" header field and +Host: is not sent at all over the wire. +.IP "Transfer-Encoding: chunked" +Tells libcurl the upload is to be done using this chunked encoding instead of +providing the Content\-Length: field in the request. +.SH SPECIFIC MIME HEADERS +When used to build a MIME email for IMAP or SMTP, the following document\-level +headers can be set to override libcurl\-generated values: +.IP Mime-Version: +Tells the parser at the receiving site how to interpret the MIME framing. +It defaults to "1.0" and should normally not be altered. +.IP Content-Type: +Indicates the document\(aqs global structure type. By default, libcurl sets it +to "multipart/mixed", describing a document made of independent parts. When a +MIME mail is only composed of alternative representations of the same data +(i.e.: HTML and plain text), this header must be set to "multipart/alternative". +In all cases the value must be of the form "multipart/*" to respect the +document structure and may not include the "boundary=" parameter. +.PP +Other specific headers that do not have a libcurl default value but are +strongly desired by mail delivery and user agents should also be included. +These are \fIFrom:\fP, \fITo:\fP, \fIDate:\fP and \fISubject:\fP among others and their +presence and value is generally checked by anti\-spam utilities. +.SH SECURITY CONCERNS +By default, this option makes libcurl send the given headers in all HTTP +requests done by this handle. You should therefore use this option with +caution if you for example connect to the remote site using a proxy and a +CONNECT request, you should to consider if that proxy is supposed to also get +the headers. They may be private or otherwise sensitive to leak. + +Use \fICURLOPT_HEADEROPT(3)\fP to make the headers only get sent to where you +intend them to get sent. + +Custom headers are sent in all requests done by the easy handle, which implies +that if you tell libcurl to follow redirects +(\fICURLOPT_FOLLOWLOCATION(3)\fP), the same set of custom headers is sent in +the subsequent request. Redirects can of course go to other hosts and thus +those servers get all the contents of your custom headers too. + +Starting in 7.58.0, libcurl specifically prevents "Authorization:" headers +from being sent to other hosts than the first used one, unless specifically +permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option. + +Starting in 7.64.0, libcurl specifically prevents "Cookie:" headers from being +sent to other hosts than the first used one, unless specifically permitted +with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + + struct curl_slist *list = NULL; + + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + list = curl_slist_append(list, "Shoesize: 10"); + list = curl_slist_append(list, "Accept:"); + + curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list); + + curl_easy_perform(curl); + + curl_slist_free_all(list); /* free the list */ + } +} +.fi +.SH HISTORY +Use for MIME mail added in 7.56.0. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CUSTOMREQUEST (3), +.BR CURLOPT_HEADER (3), +.BR CURLOPT_HEADEROPT (3), +.BR CURLOPT_MIMEPOST (3), +.BR CURLOPT_PROXYHEADER (3), +.BR curl_mime_init (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HTTPPOST.3 b/3rdparty/curl/share/man/man3/CURLOPT_HTTPPOST.3 new file mode 100644 index 0000000..fa76e37 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HTTPPOST.3 @@ -0,0 +1,81 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HTTPPOST.md +.TH CURLOPT_HTTPPOST 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HTTPPOST \- multipart formpost content +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPOST, + struct curl_httppost *formpost); +.fi +.SH DESCRIPTION +\fBThis option is deprecated.\fP Use \fICURLOPT_MIMEPOST(3)\fP instead. + +Tells libcurl you want a \fBmultipart/formdata\fP HTTP POST to be made and you +instruct what data to pass on to the server in the \fIformpost\fP argument. +Pass a pointer to a linked list of \fIcurl_httppost\fP structs as parameter. +The easiest way to create such a list, is to use \fIcurl_formadd(3)\fP as +documented. The data in this list must remain intact as long as the curl +transfer is alive and is using it. + +Using POST with HTTP 1.1 implies the use of a "Expect: 100\-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP. + +When setting \fICURLOPT_HTTPPOST(3)\fP, libcurl automatically sets +\fICURLOPT_NOBODY(3)\fP to 0. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + struct curl_httppost *formpost; + struct curl_httppost *lastptr; + + /* Fill in the file upload field. This makes libcurl load data from + the given file name when curl_easy_perform() is called. */ + curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "sendfile", + CURLFORM_FILE, "postit2.c", + CURLFORM_END); + + /* Fill in the filename field */ + curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "filename", + CURLFORM_COPYCONTENTS, "postit2.c", + CURLFORM_END); + + /* Fill in the submit field too, even if this is rarely needed */ + curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "submit", + CURLFORM_COPYCONTENTS, "send", + CURLFORM_END); + + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost); + curl_easy_perform(curl); + curl_easy_cleanup(curl); + } + curl_formfree(formpost); +} +.fi +.SH DEPRECATED +Deprecated in 7.56.0. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_MIMEPOST (3), +.BR CURLOPT_POST (3), +.BR CURLOPT_POSTFIELDS (3), +.BR curl_formadd (3), +.BR curl_formfree (3), +.BR curl_mime_init (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HTTPPROXYTUNNEL.3 b/3rdparty/curl/share/man/man3/CURLOPT_HTTPPROXYTUNNEL.3 new file mode 100644 index 0000000..3bc96e5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HTTPPROXYTUNNEL.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HTTPPROXYTUNNEL.md +.TH CURLOPT_HTTPPROXYTUNNEL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HTTPPROXYTUNNEL \- tunnel through HTTP proxy +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPROXYTUNNEL, long tunnel); +.fi +.SH DESCRIPTION +Set the \fBtunnel\fP parameter to 1L to make libcurl tunnel all operations +through the HTTP proxy (set with \fICURLOPT_PROXY(3)\fP). There is a big +difference between using a proxy and to tunnel through it. + +Tunneling means that an HTTP CONNECT request is sent to the proxy, asking it +to connect to a remote host on a specific port number and then the traffic is +just passed through the proxy. Proxies tend to white\-list specific port numbers +it allows CONNECT requests to and often only port 80 and 443 are allowed. + +To suppress proxy CONNECT response headers from user callbacks use +\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP. + +HTTP proxies can generally only speak HTTP (for obvious reasons), which makes +libcurl convert non\-HTTP requests to HTTP when using an HTTP proxy without +this tunnel option set. For example, asking for an FTP URL and specifying an +HTTP proxy makes libcurl send an FTP URL in an HTTP GET request to the +proxy. By instead tunneling through the proxy, you avoid that conversion (that +rarely works through the proxy anyway). +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80"); + curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.3 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_PROXY (3), +.BR CURLOPT_PROXYPORT (3), +.BR CURLOPT_PROXYTYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HTTP_CONTENT_DECODING.3 b/3rdparty/curl/share/man/man3/CURLOPT_HTTP_CONTENT_DECODING.3 new file mode 100644 index 0000000..cf1ee98 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HTTP_CONTENT_DECODING.3 @@ -0,0 +1,41 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HTTP_CONTENT_DECODING.md +.TH CURLOPT_HTTP_CONTENT_DECODING 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HTTP_CONTENT_DECODING \- HTTP content decoding control +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_CONTENT_DECODING, + long enabled); +.fi +.SH DESCRIPTION +Pass a long to tell libcurl how to act on content decoding. If set to zero, +content decoding is disabled. If set to 1 it is enabled. Libcurl has no +default content decoding but requires you to use +\fICURLOPT_ACCEPT_ENCODING(3)\fP for that. +.SH DEFAULT +1 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_HTTP_CONTENT_DECODING, 0L); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_ACCEPT_ENCODING (3), +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_STDERR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HTTP_TRANSFER_DECODING.3 b/3rdparty/curl/share/man/man3/CURLOPT_HTTP_TRANSFER_DECODING.3 new file mode 100644 index 0000000..982c8a2 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HTTP_TRANSFER_DECODING.3 @@ -0,0 +1,42 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HTTP_TRANSFER_DECODING.md +.TH CURLOPT_HTTP_TRANSFER_DECODING 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HTTP_TRANSFER_DECODING \- HTTP transfer decoding control +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_TRANSFER_DECODING, + long enabled); +.fi +.SH DESCRIPTION +Pass a long to tell libcurl how to act on transfer decoding. If set to zero, +transfer decoding is disabled, if set to 1 it is enabled (default). libcurl +does chunked transfer decoding by default unless this option is set to zero. +.SH NOTES +This option does not work with the hyper backend as that always has transfer +decoding enabled. +.SH DEFAULT +1 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_HTTP_TRANSFER_DECODING, 0L); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_ACCEPT_ENCODING (3), +.BR CURLOPT_HTTP_CONTENT_DECODING (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_HTTP_VERSION.3 b/3rdparty/curl/share/man/man3/CURLOPT_HTTP_VERSION.3 new file mode 100644 index 0000000..1316a70 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_HTTP_VERSION.3 @@ -0,0 +1,86 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_HTTP_VERSION.md +.TH CURLOPT_HTTP_VERSION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_HTTP_VERSION \- HTTP protocol version to use +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_VERSION, long version); +.fi +.SH DESCRIPTION +Pass \fIversion\fP a long, set to one of the values described below. They ask +libcurl to use the specific HTTP versions. + +Note that the HTTP version is just a request. libcurl still prioritizes to +reuse existing connections so it might then reuse a connection using an HTTP +version you have not asked for. +.IP CURL_HTTP_VERSION_NONE +We do not care about what version the library uses. libcurl uses whatever it +thinks fit. +.IP CURL_HTTP_VERSION_1_0 +Enforce HTTP 1.0 requests. +.IP CURL_HTTP_VERSION_1_1 +Enforce HTTP 1.1 requests. +.IP CURL_HTTP_VERSION_2_0 +Attempt HTTP 2 requests. libcurl falls back to HTTP 1.1 if HTTP 2 cannot be +negotiated with the server. (Added in 7.33.0) + +When libcurl uses HTTP/2 over HTTPS, it does not itself insist on TLS 1.2 or +higher even though that is required by the specification. A user can add this +version requirement with \fICURLOPT_SSLVERSION(3)\fP. + +The alias \fICURL_HTTP_VERSION_2\fP was added in 7.43.0 to better reflect the +actual protocol name. +.IP CURL_HTTP_VERSION_2TLS +Attempt HTTP 2 over TLS (HTTPS) only. libcurl falls back to HTTP 1.1 if HTTP 2 +cannot be negotiated with the HTTPS server. For clear text HTTP servers, +libcurl uses 1.1. (Added in 7.47.0) +.IP CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE +Issue non\-TLS HTTP requests using HTTP/2 without HTTP/1.1 Upgrade. It requires +prior knowledge that the server supports HTTP/2 straight away. HTTPS requests +still do HTTP/2 the standard way with negotiated protocol version in the TLS +handshake. (Added in 7.49.0) + +Since 8.10.0 if this option is set for an HTTPS request then the application +layer protocol version (ALPN) offered to the server is only HTTP/2. Prior to +that both HTTP/1.1 and HTTP/2 were offered. +.IP CURL_HTTP_VERSION_3 +(Added in 7.66.0) This option makes libcurl attempt to use HTTP/3 to the host +given in the URL, with fallback to earlier HTTP versions if needed. +.IP CURL_HTTP_VERSION_3ONLY +(Added in 7.88.0) Setting this makes libcurl attempt to use HTTP/3 directly to +server given in the URL and does not downgrade to earlier HTTP version if the +server does not support HTTP/3. +.SH DEFAULT +Since curl 7.62.0: CURL_HTTP_VERSION_2TLS + +Before that: CURL_HTTP_VERSION_1_1 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_HTTP_VERSION, + (long)CURL_HTTP_VERSION_2TLS); + ret = curl_easy_perform(curl); + if(ret == CURLE_HTTP_RETURNED_ERROR) { + /* an HTTP response error problem */ + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_ALTSVC (3), +.BR CURLOPT_HTTP09_ALLOWED (3), +.BR CURLOPT_HTTP200ALIASES (3), +.BR CURLOPT_SSLVERSION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_IGNORE_CONTENT_LENGTH.3 b/3rdparty/curl/share/man/man3/CURLOPT_IGNORE_CONTENT_LENGTH.3 new file mode 100644 index 0000000..d490d09 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_IGNORE_CONTENT_LENGTH.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_IGNORE_CONTENT_LENGTH.md +.TH CURLOPT_IGNORE_CONTENT_LENGTH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_IGNORE_CONTENT_LENGTH \- ignore content length +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IGNORE_CONTENT_LENGTH, + long ignore); +.fi +.SH DESCRIPTION +If \fIignore\fP is set to 1L, ignore the Content\-Length header in the HTTP +response and ignore asking for or relying on it for FTP transfers. + +This is useful for doing HTTP transfers with ancient web servers which report +incorrect content length for files over 2 gigabytes. If this option is used, +curl cannot accurately report progress, and it instead stops the download when +the server ends the connection. + +It is also useful with FTP when for example the file is growing while the +transfer is in progress which otherwise unconditionally causes libcurl to +report error. + +Only use this option if strictly necessary. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects ftp and http +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* we know the server is silly, ignore content-length */ + curl_easy_setopt(curl, CURLOPT_IGNORE_CONTENT_LENGTH, 1L); + + curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +Support for FTP added in 7.46.0. +.SH NOTES +This option is not working for HTTP when libcurl is built to use the hyper +backend. +.SH AVAILABILITY +Added in curl 7.14.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTP_VERSION (3), +.BR CURLOPT_MAXFILESIZE_LARGE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_INFILESIZE.3 b/3rdparty/curl/share/man/man3/CURLOPT_INFILESIZE.3 new file mode 100644 index 0000000..f7ee110 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_INFILESIZE.3 @@ -0,0 +1,66 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_INFILESIZE.md +.TH CURLOPT_INFILESIZE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_INFILESIZE \- size of the input file to send off +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INFILESIZE, long filesize); +.fi +.SH DESCRIPTION +When uploading a file to a remote site, \fIfilesize\fP should be used to tell +libcurl what the expected size of the input file is. This value must be passed +as a long. See also \fICURLOPT_INFILESIZE_LARGE(3)\fP for sending files larger +than 2GB. + +For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE(3)\fP is +mandatory. + +To unset this value again, set it to \-1. + +Using \fICURLOPT_UPLOAD(3)\fP to an HTTP/1.1 server and this value set to \-1, makes +libcurl do a chunked transfer\-encoded upload. + +When sending emails using SMTP, this command can be used to specify the +optional SIZE parameter for the MAIL FROM command. + +This option does not limit how much data libcurl actually sends, as that is +controlled entirely by what the read callback returns, but telling one value +and sending a different amount may lead to errors. +.SH DEFAULT +Unset +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf + +#define FILE_SIZE 12345L + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + long uploadsize = FILE_SIZE; + + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/destination.tar.gz"); + + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + curl_easy_setopt(curl, CURLOPT_INFILESIZE, uploadsize); + + curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +SMTP support added in 7.23.0 +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CONTENT_LENGTH_UPLOAD_T (3), +.BR CURLOPT_INFILESIZE_LARGE (3), +.BR CURLOPT_UPLOAD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_INFILESIZE_LARGE.3 b/3rdparty/curl/share/man/man3/CURLOPT_INFILESIZE_LARGE.3 new file mode 100644 index 0000000..e2afcf3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_INFILESIZE_LARGE.3 @@ -0,0 +1,62 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_INFILESIZE_LARGE.md +.TH CURLOPT_INFILESIZE_LARGE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_INFILESIZE_LARGE \- size of the input file to send off +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INFILESIZE_LARGE, + curl_off_t filesize); +.fi +.SH DESCRIPTION +When uploading a file to a remote site, \fIfilesize\fP should be used to tell +libcurl what the expected size of the input file is. This value must be passed +as a \fBcurl_off_t\fP. + +For uploading using SCP, this option or \fICURLOPT_INFILESIZE(3)\fP is +mandatory. + +To unset this value again, set it to \-1. + +When sending emails using SMTP, this command can be used to specify the +optional SIZE parameter for the MAIL FROM command. + +This option does not limit how much data libcurl actually sends, as that is +controlled entirely by what the read callback returns, but telling one value +and sending a different amount may lead to errors. +.SH DEFAULT +Unset +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +#define FILE_SIZE 123456 + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_off_t uploadsize = FILE_SIZE; + + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/destination.tar.gz"); + + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, uploadsize); + + curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +SMTP support added in 7.23.0 +.SH AVAILABILITY +Added in curl 7.11.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CONTENT_LENGTH_UPLOAD_T (3), +.BR CURLOPT_INFILESIZE (3), +.BR CURLOPT_UPLOAD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_INTERFACE.3 b/3rdparty/curl/share/man/man3/CURLOPT_INTERFACE.3 new file mode 100644 index 0000000..d2556c0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_INTERFACE.3 @@ -0,0 +1,71 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_INTERFACE.md +.TH CURLOPT_INTERFACE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_INTERFACE \- source interface for outgoing traffic +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERFACE, char *interface); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter. This sets the \fIinterface\fP name to use as +outgoing network interface. The name can be an interface name, an IP address, +or a hostname. If you prefer one of these, you can use the following special +prefixes: + +* \fIif!\fP \- Interface name +* \fIhost!\fP \- IP address or hostname +* \fIifhost!!\fP \- Interface name and IP address or hostname + +If \fIif!\fP or \fIifhost!\fP is specified but the parameter does not match an existing +interface, \fICURLE_INTERFACE_FAILED\fP is returned from the libcurl function used +to perform the transfer. + +libcurl does not support using network interface names for this option on +Windows. + +We strongly advise against specifying the interface with a hostname, as it +causes libcurl to do a blocking name resolve call to retrieve the IP address. +That name resolve operation does \fBnot\fP use DNS\-over\-HTTPS even if +\fICURLOPT_DOH_URL(3)\fP is set. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL, use whatever the TCP stack finds suitable +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + curl_easy_setopt(curl, CURLOPT_INTERFACE, "eth0"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +The \fIif!\fP and \fIhost!\fP syntax was added in 7.24.0. + +The \fIifhost!\fP syntax was added in 8.9.0. +.SH AVAILABILITY +Added in curl 7.3 +.SH RETURN VALUE +Returns CURLE_OK on success or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_LOCALPORT (3), +.BR CURLOPT_SOCKOPTFUNCTION (3), +.BR CURLOPT_TCP_NODELAY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_INTERLEAVEDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_INTERLEAVEDATA.3 new file mode 100644 index 0000000..1fc940b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_INTERLEAVEDATA.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_INTERLEAVEDATA.md +.TH CURLOPT_INTERLEAVEDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_INTERLEAVEDATA \- pointer passed to RTSP interleave callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEDATA, void *pointer); +.fi +.SH DESCRIPTION +This is the userdata \fIpointer\fP that is passed to +\fICURLOPT_INTERLEAVEFUNCTION(3)\fP when interleaved RTP data is received. If +the interleave function callback is not set, this pointer is not used +anywhere. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +struct local { + void *custom; +}; +static size_t rtp_write(void *ptr, size_t size, size_t nmemb, void *userp) +{ + struct local *l = userp; + printf("my pointer: %p\\n", l->custom); + /* take care of the packet in 'ptr', then return... */ + return size * nmemb; +} + +int main(void) +{ + struct local rtp_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_INTERLEAVEFUNCTION, rtp_write); + curl_easy_setopt(curl, CURLOPT_INTERLEAVEDATA, &rtp_data); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_INTERLEAVEFUNCTION (3), +.BR CURLOPT_RTSP_REQUEST (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_INTERLEAVEFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_INTERLEAVEFUNCTION.3 new file mode 100644 index 0000000..2107104 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_INTERLEAVEFUNCTION.3 @@ -0,0 +1,81 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_INTERLEAVEFUNCTION.md +.TH CURLOPT_INTERLEAVEFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_INTERLEAVEFUNCTION \- callback for RTSP interleaved data +.SH SYNOPSIS +.nf +#include + +size_t interleave_callback(void *ptr, size_t size, size_t nmemb, + void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEFUNCTION, + interleave_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl as soon as it has received +interleaved RTP data. This function gets called for each $ block and therefore +contains exactly one upper\-layer protocol unit (e.g. one RTP packet). Curl +writes the interleaved header as well as the included data for each call. The +first byte is always an ASCII dollar sign. The dollar sign is followed by a +one byte channel identifier and then a 2 byte integer length in network byte +order. See RFC 2326 Section 10.12 for more information on how RTP interleaving +behaves. If unset or set to NULL, curl uses the default write function. + +Interleaved RTP poses some challenges for the client application. Since the +stream data is sharing the RTSP control connection, it is critical to service +the RTP in a timely fashion. If the RTP data is not handled quickly, +subsequent response processing may become unreasonably delayed and the +connection may close. The application may use \fICURL_RTSPREQ_RECEIVE\fP to +service RTP data when no requests are desired. If the application makes a +request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler processes +any pending RTP data before marking the request as finished. + +The \fICURLOPT_INTERLEAVEDATA(3)\fP is passed in the \fIuserdata\fP argument in +the callback. + +Your callback should return the number of bytes actually taken care of. If +that amount differs from the amount passed to your callback function, it +signals an error condition to the library. This causes the transfer to abort +and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. + +You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0) +.SH DEFAULT +NULL, the interleave data is then passed to the regular write function: +\fICURLOPT_WRITEFUNCTION(3)\fP. +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +struct local { + void *custom; +}; + +static size_t rtp_write(void *ptr, size_t size, size_t nmemb, void *userp) +{ + struct local *l = userp; + printf("our ptr: %p\\n", l->custom); + /* take care of the packet in 'ptr', then return... */ + return size * nmemb; +} + +int main(void) +{ + struct local rtp_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_INTERLEAVEFUNCTION, rtp_write); + curl_easy_setopt(curl, CURLOPT_INTERLEAVEDATA, &rtp_data); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_INTERLEAVEDATA (3), +.BR CURLOPT_RTSP_REQUEST (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_IOCTLDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_IOCTLDATA.3 new file mode 100644 index 0000000..73f6225 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_IOCTLDATA.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_IOCTLDATA.md +.TH CURLOPT_IOCTLDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_IOCTLDATA \- pointer passed to I/O callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLDATA, void *pointer); +.fi +.SH DESCRIPTION +Pass the \fIpointer\fP that is untouched by libcurl and passed as the 3rd +argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +#include /* for lseek */ + +struct data { + int fd; /* our file descriptor */ +}; + +static curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp) +{ + struct data *io = (struct data *)clientp; + if(cmd == CURLIOCMD_RESTARTREAD) { + lseek(io->fd, 0, SEEK_SET); + return CURLIOE_OK; + } + return CURLIOE_UNKNOWNCMD; +} +int main(void) +{ + struct data ioctl_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_IOCTLFUNCTION, ioctl_callback); + curl_easy_setopt(curl, CURLOPT_IOCTLDATA, &ioctl_data); + } +} +.fi +.SH DEPRECATED +Deprecated since 7.18.0. +.SH AVAILABILITY +Added in curl 7.12.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_IOCTLFUNCTION (3), +.BR CURLOPT_SEEKFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_IOCTLFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_IOCTLFUNCTION.3 new file mode 100644 index 0000000..be40d72 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_IOCTLFUNCTION.3 @@ -0,0 +1,84 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_IOCTLFUNCTION.md +.TH CURLOPT_IOCTLFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_IOCTLFUNCTION \- callback for I/O operations +.SH SYNOPSIS +.nf +#include + +typedef enum { + CURLIOE_OK, /* I/O operation successful */ + CURLIOE_UNKNOWNCMD, /* command was unknown to callback */ + CURLIOE_FAILRESTART, /* failed to restart the read */ + CURLIOE_LAST /* never use */ +} curlioerr; + +typedef enum { + CURLIOCMD_NOP, /* no operation */ + CURLIOCMD_RESTARTREAD, /* restart the read stream from start */ + CURLIOCMD_LAST /* never use */ +} curliocmd; + +curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLFUNCTION, ioctl_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl when something special +I/O\-related needs to be done that the library cannot do by itself. For now, +rewinding the read data stream is the only action it can request. The +rewinding of the read data stream may be necessary when doing an HTTP PUT or +POST with a multi\-pass authentication method. + +The callback MUST return \fICURLIOE_UNKNOWNCMD\fP if the input \fIcmd\fP is +not \fICURLIOCMD_RESTARTREAD\fP. + +The \fIclientp\fP argument to the callback is set with the +\fICURLOPT_IOCTLDATA(3)\fP option. + +\fBThis option is deprecated\fP. Do not use it. Use \fICURLOPT_SEEKFUNCTION(3)\fP +instead to provide seeking! If \fICURLOPT_SEEKFUNCTION(3)\fP is set, this +parameter is ignored when seeking. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +#include /* for lseek */ + +struct data { + int fd; /* our file descriptor */ +}; + +static curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp) +{ + struct data *io = (struct data *)clientp; + if(cmd == CURLIOCMD_RESTARTREAD) { + lseek(io->fd, 0, SEEK_SET); + return CURLIOE_OK; + } + return CURLIOE_UNKNOWNCMD; +} +int main(void) +{ + struct data ioctl_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_IOCTLFUNCTION, ioctl_callback); + curl_easy_setopt(curl, CURLOPT_IOCTLDATA, &ioctl_data); + } +} +.fi +.SH DEPRECATED +Deprecated since 7.18.0. +.SH AVAILABILITY +Added in curl 7.12.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_IOCTLDATA (3), +.BR CURLOPT_SEEKFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_IPRESOLVE.3 b/3rdparty/curl/share/man/man3/CURLOPT_IPRESOLVE.3 new file mode 100644 index 0000000..e4b7734 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_IPRESOLVE.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_IPRESOLVE.md +.TH CURLOPT_IPRESOLVE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_IPRESOLVE \- IP protocol version to use +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IPRESOLVE, long resolve); +.fi +.SH DESCRIPTION +Allows an application to select what kind of IP addresses to use when +establishing a connection or choosing one from the connection pool. This is +interesting when using hostnames that resolve to more than one IP family. + +If the URL provided for a transfer contains a numerical IP version as a host +name, this option does not override or prohibit libcurl from using that IP +version. + +Available values for this option are: +.IP CURL_IPRESOLVE_WHATEVER +Default, can use addresses of all IP versions that your system allows. +.IP CURL_IPRESOLVE_V4 +Uses only IPv4 addresses. +.IP CURL_IPRESOLVE_V6 +Uses only IPv6 addresses. +.SH DEFAULT +CURL_IPRESOLVE_WHATEVER +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* of all addresses example.com resolves to, only IPv6 ones are used */ + curl_easy_setopt(curl, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V6); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.8 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_HTTP_VERSION (3), +.BR CURLOPT_RESOLVE (3), +.BR CURLOPT_SSLVERSION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_ISSUERCERT.3 b/3rdparty/curl/share/man/man3/CURLOPT_ISSUERCERT.3 new file mode 100644 index 0000000..6de00b3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_ISSUERCERT.3 @@ -0,0 +1,62 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_ISSUERCERT.md +.TH CURLOPT_ISSUERCERT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_ISSUERCERT \- issuer SSL certificate filename +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ISSUERCERT, char *file); +.fi +.SH DESCRIPTION +Pass a char pointer to a null\-terminated string naming a \fIfile\fP holding a CA +certificate in PEM format. If the option is set, an additional check against +the peer certificate is performed to verify the issuer is indeed the one +associated with the certificate provided by the option. This additional check +is useful in multi\-level PKI where one needs to enforce that the peer +certificate is from a specific branch of the tree. + +This option makes sense only when used in combination with the +\fICURLOPT_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is +not considered as failure. + +A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, +which is returned if the setup of the SSL/TLS session has failed due to a +mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER(3)\fP +has to be set too for the check to fail). (Added in 7.19.0) + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_ISSUERCERT, "/etc/certs/cacert.pem"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_CRLFILE (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_ISSUERCERT_BLOB.3 b/3rdparty/curl/share/man/man3/CURLOPT_ISSUERCERT_BLOB.3 new file mode 100644 index 0000000..22b0fe9 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_ISSUERCERT_BLOB.3 @@ -0,0 +1,74 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_ISSUERCERT_BLOB.md +.TH CURLOPT_ISSUERCERT_BLOB 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_ISSUERCERT_BLOB \- issuer SSL certificate from memory blob +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ISSUERCERT_BLOB, + struct curl_blob *stblob); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_blob structure, which contains information (pointer +and size) about a memory block with binary data of a CA certificate in PEM +format. If the option is set, an additional check against the peer certificate +is performed to verify the issuer is indeed the one associated with the +certificate provided by the option. This additional check is useful in +multi\-level PKI where one needs to enforce that the peer certificate is from a +specific branch of the tree. + +This option should be used in combination with the +\fICURLOPT_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is +not considered as failure. + +A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, +which is returned if the setup of the SSL/TLS session has failed due to a +mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER(3)\fP +has to be set too for the check to fail). + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. + +This option is an alternative to \fICURLOPT_ISSUERCERT(3)\fP which instead +expects a filename as input. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL +.SH EXAMPLE +.nf + +extern char *certificateData; +extern size_t filesize; + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob blob; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + blob.data = certificateData; + blob.len = filesize; + blob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_ISSUERCERT_BLOB, &blob); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.71.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_CRLFILE (3), +.BR CURLOPT_ISSUERCERT (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_KEEP_SENDING_ON_ERROR.3 b/3rdparty/curl/share/man/man3/CURLOPT_KEEP_SENDING_ON_ERROR.3 new file mode 100644 index 0000000..695d800 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_KEEP_SENDING_ON_ERROR.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_KEEP_SENDING_ON_ERROR.md +.TH CURLOPT_KEEP_SENDING_ON_ERROR 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_KEEP_SENDING_ON_ERROR \- keep sending on early HTTP response >= 300 +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KEEP_SENDING_ON_ERROR, + long keep_sending); +.fi +.SH DESCRIPTION +A long parameter set to 1 tells the library to keep sending the request body +if the HTTP code returned is equal to or larger than 300. The default action +would be to stop sending and close the stream or connection. + +This option is suitable for manual NTLM authentication, i.e. if an application +does not use \fICURLOPT_HTTPAUTH(3)\fP, but instead sets "Authorization: NTLM ..." +headers manually using \fICURLOPT_HTTPHEADER(3)\fP. + +Most applications do not need this option. +.SH DEFAULT +0, stop sending on error +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "sending data"); + curl_easy_setopt(curl, CURLOPT_KEEP_SENDING_ON_ERROR, 1L); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.51.0 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RESPONSE_CODE (3), +.BR CURLOPT_FAILONERROR (3), +.BR CURLOPT_HTTPHEADER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_KEYPASSWD.3 b/3rdparty/curl/share/man/man3/CURLOPT_KEYPASSWD.3 new file mode 100644 index 0000000..5eceb77 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_KEYPASSWD.3 @@ -0,0 +1,55 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_KEYPASSWD.md +.TH CURLOPT_KEYPASSWD 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_KEYPASSWD \- passphrase to private key +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KEYPASSWD, char *pwd); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. It is used as the +password required to use the \fICURLOPT_SSLKEY(3)\fP or +\fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP private key. You never need a passphrase to +load a certificate but you need one to load your private key. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL, Schannel, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "superman"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and +CURLOPT_SSLCERTPASSWD up to 7.9.2. +.SH AVAILABILITY +Added in curl 7.17.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_SSH_PRIVATE_KEYFILE (3), +.BR CURLOPT_SSLKEY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_KRBLEVEL.3 b/3rdparty/curl/share/man/man3/CURLOPT_KRBLEVEL.3 new file mode 100644 index 0000000..0de491d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_KRBLEVEL.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_KRBLEVEL.md +.TH CURLOPT_KRBLEVEL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_KRBLEVEL \- FTP kerberos security level +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KRBLEVEL, char *level); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter. Set the kerberos security level for FTP; +this also enables kerberos awareness. This is a string that should match one +of the following: &\(aqclear\(aq, &\(aqsafe\(aq, &\(aqconfidential\(aq or &\(aqprivate\(aq. If the +string is set but does not match one of these, \(aqprivate\(aq is used. Set the +string to NULL to disable kerberos support for FTP. + +The application does not have to keep the string around after setting this +option. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_KRBLEVEL, "private"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +This option was known as CURLOPT_KRB4LEVEL up to 7.16.3 +.SH AVAILABILITY +Added in curl 7.16.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_KRBLEVEL (3), +.BR CURLOPT_USE_SSL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_LOCALPORT.3 b/3rdparty/curl/share/man/man3/CURLOPT_LOCALPORT.3 new file mode 100644 index 0000000..56f61a9 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_LOCALPORT.3 @@ -0,0 +1,43 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_LOCALPORT.md +.TH CURLOPT_LOCALPORT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_LOCALPORT \- local port number to use for socket +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOCALPORT, long port); +.fi +.SH DESCRIPTION +Pass a long. This sets the local port number of the socket used for the +connection. This can be used in combination with \fICURLOPT_INTERFACE(3)\fP +and you are recommended to use \fICURLOPT_LOCALPORTRANGE(3)\fP as well when +this option is set. Valid port numbers are 1 \- 65535. +.SH DEFAULT +0, disabled \- use whatever the system thinks is fine +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_LOCALPORT, 49152L); + /* and try 20 more ports following that */ + curl_easy_setopt(curl, CURLOPT_LOCALPORTRANGE, 20L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.15.2 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLINFO_LOCAL_PORT (3), +.BR CURLOPT_INTERFACE (3), +.BR CURLOPT_LOCALPORTRANGE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_LOCALPORTRANGE.3 b/3rdparty/curl/share/man/man3/CURLOPT_LOCALPORTRANGE.3 new file mode 100644 index 0000000..7fff10c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_LOCALPORTRANGE.3 @@ -0,0 +1,46 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_LOCALPORTRANGE.md +.TH CURLOPT_LOCALPORTRANGE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_LOCALPORTRANGE \- number of additional local ports to try +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOCALPORTRANGE, + long range); +.fi +.SH DESCRIPTION +Pass a long. The \fIrange\fP argument is the number of attempts libcurl makes +to find a working local port number. It starts with the given +\fICURLOPT_LOCALPORT(3)\fP and adds one to the number for each retry. Setting +this option to 1 or below makes libcurl only do one try for the exact port +number. Port numbers by nature are scarce resources that are busy at times so +setting this value to something too low might cause unnecessary connection +setup failures. +.SH DEFAULT +1 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_LOCALPORT, 49152L); + /* and try 20 more ports following that */ + curl_easy_setopt(curl, CURLOPT_LOCALPORTRANGE, 20L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.15.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_INTERFACE (3), +.BR CURLOPT_LOCALPORT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_LOGIN_OPTIONS.3 b/3rdparty/curl/share/man/man3/CURLOPT_LOGIN_OPTIONS.3 new file mode 100644 index 0000000..53967ef --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_LOGIN_OPTIONS.3 @@ -0,0 +1,60 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_LOGIN_OPTIONS.md +.TH CURLOPT_LOGIN_OPTIONS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_LOGIN_OPTIONS \- login options +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOGIN_OPTIONS, char *options); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should be pointing to the +null\-terminated \fIoptions\fP string to use for the transfer. + +For more information about the login options please see RFC 2384, RFC 5092 and +the IETF draft \fBdraft\-earhart\-url\-smtp\-00.txt\fP. + +\fICURLOPT_LOGIN_OPTIONS(3)\fP can be used to set protocol specific login options, +such as the preferred authentication mechanism via "AUTH=NTLM" or "AUTH=*", +and should be used in conjunction with the \fICURLOPT_USERNAME(3)\fP option. + +Since 8.2.0, IMAP supports the login option "AUTH=+LOGIN". With this option, +curl uses the plain (not SASL) LOGIN IMAP command even if the server +advertises SASL authentication. Care should be taken in using this option, as +it sends your password in plain text. This does not work if the IMAP server +disables the plain LOGIN (e.g. to prevent password snooping). + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects imap, ldap, pop3 and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_LOGIN_OPTIONS, "AUTH=*"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +Support for OpenLDAP added in 7.82.0. +.SH AVAILABILITY +Added in curl 7.34.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PASSWORD (3), +.BR CURLOPT_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_LOW_SPEED_LIMIT.3 b/3rdparty/curl/share/man/man3/CURLOPT_LOW_SPEED_LIMIT.3 new file mode 100644 index 0000000..10f2bf8 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_LOW_SPEED_LIMIT.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_LOW_SPEED_LIMIT.md +.TH CURLOPT_LOW_SPEED_LIMIT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_LOW_SPEED_LIMIT \- low speed limit in bytes per second +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOW_SPEED_LIMIT, + long speedlimit); +.fi +.SH DESCRIPTION +Pass a long as parameter. It contains the average transfer speed in bytes per +second that the transfer should be below during +\fICURLOPT_LOW_SPEED_TIME(3)\fP seconds for libcurl to consider it to be too +slow and abort. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* abort if slower than 30 bytes/sec during 60 seconds */ + curl_easy_setopt(curl, CURLOPT_LOW_SPEED_TIME, 60L); + curl_easy_setopt(curl, CURLOPT_LOW_SPEED_LIMIT, 30L); + res = curl_easy_perform(curl); + if(CURLE_OPERATION_TIMEDOUT == res) { + printf("Timeout!\\n"); + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_LOW_SPEED_TIME (3), +.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), +.BR CURLOPT_MAX_SEND_SPEED_LARGE (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_LOW_SPEED_TIME.3 b/3rdparty/curl/share/man/man3/CURLOPT_LOW_SPEED_TIME.3 new file mode 100644 index 0000000..fe9d1b1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_LOW_SPEED_TIME.3 @@ -0,0 +1,46 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_LOW_SPEED_TIME.md +.TH CURLOPT_LOW_SPEED_TIME 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_LOW_SPEED_TIME \- low speed limit time period +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOW_SPEED_TIME, + long speedtime); +.fi +.SH DESCRIPTION +Pass a long as parameter. It contains the time in number seconds that the +transfer speed should be below the \fICURLOPT_LOW_SPEED_LIMIT(3)\fP for the +library to consider it too slow and abort. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* abort if slower than 30 bytes/sec during 60 seconds */ + curl_easy_setopt(curl, CURLOPT_LOW_SPEED_TIME, 60L); + curl_easy_setopt(curl, CURLOPT_LOW_SPEED_LIMIT, 30L); + res = curl_easy_perform(curl); + if(CURLE_OPERATION_TIMEDOUT == res) { + printf("Timeout!\\n"); + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAIL_AUTH.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAIL_AUTH.3 new file mode 100644 index 0000000..5e997cf --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAIL_AUTH.3 @@ -0,0 +1,58 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAIL_AUTH.md +.TH CURLOPT_MAIL_AUTH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAIL_AUTH \- SMTP authentication address +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_AUTH, char *auth); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. This is used to +specify the authentication address (identity) of a submitted message that is +being relayed to another server. + +This optional parameter allows co\-operating agents in a trusted environment to +communicate the authentication of individual messages and should only be used +by the application program, using libcurl, if the application is itself a mail +server acting in such an environment. If the application is operating as such +and the AUTH address is not known or is invalid, then an empty string should +be used for this parameter. + +Unlike \fICURLOPT_MAIL_FROM(3)\fP and \fICURLOPT_MAIL_RCPT(3)\fP, the address should not +be specified within a pair of angled brackets (<>). However, if an empty +string is used then a pair of brackets are sent by libcurl as required by RFC +2554. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects smtp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_MAIL_AUTH, ""); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.25.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_MAIL_FROM (3), +.BR CURLOPT_MAIL_RCPT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAIL_FROM.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAIL_FROM.3 new file mode 100644 index 0000000..4da071f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAIL_FROM.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAIL_FROM.md +.TH CURLOPT_MAIL_FROM 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAIL_FROM \- SMTP sender address +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_FROM, char *from); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. This should be used +to specify the sender\(aqs email address when sending SMTP mail with libcurl. + +An originator email address should be specified with angled brackets (<>) +around it, which if not specified are added automatically. + +If this parameter is not specified then an empty address is sent to the SMTP +server which might cause the email to be rejected. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +blank +.SH PROTOCOLS +This functionality affects smtp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_MAIL_FROM, "president@example.com"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_MAIL_AUTH (3), +.BR CURLOPT_MAIL_RCPT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAIL_RCPT.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAIL_RCPT.3 new file mode 100644 index 0000000..aaf0b83 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAIL_RCPT.3 @@ -0,0 +1,64 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAIL_RCPT.md +.TH CURLOPT_MAIL_RCPT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAIL_RCPT \- list of SMTP mail recipients +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT, + struct curl_slist *rcpts); +.fi +.SH DESCRIPTION +Pass a pointer to a linked list of recipients to pass to the server in your +SMTP mail request. The linked list should be a fully valid list of +\fBstruct curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to +create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. + +libcurl does not copy the list, it needs to be kept around until after the +transfer has completed. + +When performing a mail transfer, each recipient should be specified within a +pair of angled brackets (<>), however, should you not use an angled bracket +as the first character libcurl assumes you provided a single email address and +encloses that address within brackets for you. + +When performing an address verification (\fBVRFY\fP command), each recipient +should be specified as the username or username plus domain (as per Section +3.5 of RFC 5321). + +When performing a mailing list expand (\fBEXPN\fP command), each recipient +should be specified using the mailing list name, such as \fIFriends\fP or +\fILondon\-Office\fP. + +Using this option multiple times makes the last set list override the previous +ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects smtp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_slist *list; + list = curl_slist_append(NULL, "root@localhost"); + list = curl_slist_append(list, "person@example.com"); + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, list); + res = curl_easy_perform(curl); + curl_slist_free_all(list); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_MAIL_AUTH (3), +.BR CURLOPT_MAIL_FROM (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 new file mode 100644 index 0000000..90f0b0d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 @@ -0,0 +1,61 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAIL_RCPT_ALLOWFAILS.md +.TH CURLOPT_MAIL_RCPT_ALLOWFAILS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAIL_RCPT_ALLOWFAILS \- allow RCPT TO command to fail for some recipients +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT_ALLOWFAILS, + long allow); +.fi +.SH DESCRIPTION +If \fIallow\fP is set to 1L, allow RCPT TO command to fail for some recipients. + +When sending data to multiple recipients, by default curl aborts the SMTP +conversation if either one of the recipients causes the RCPT TO command to +return an error. + +The default behavior can be changed by setting \fIallow\fP to 1L which makes +libcurl ignore errors for individual recipients and proceed with the remaining +accepted recipients. + +If all recipients trigger RCPT TO failures and this flag is specified, curl +aborts the SMTP conversation and returns the error received from to the last +RCPT TO command. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects smtp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct curl_slist *list; + CURLcode res; + + /* Adding one valid and one invalid email address */ + list = curl_slist_append(NULL, "person@example.com"); + list = curl_slist_append(list, "invalidemailaddress"); + + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_MAIL_RCPT_ALLOWFAILS, 1L); + + res = curl_easy_perform(curl); + curl_slist_free_all(list); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +This option was called CURLOPT_MAIL_RCPT_ALLLOWFAILS (with three instead of +two letter L) before 8.2.0 +.SH AVAILABILITY +Added in curl 8.2.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_MAIL_FROM (3), +.BR CURLOPT_MAIL_RCPT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAXAGE_CONN.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAXAGE_CONN.3 new file mode 100644 index 0000000..2e42b87 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAXAGE_CONN.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAXAGE_CONN.md +.TH CURLOPT_MAXAGE_CONN 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAXAGE_CONN \- max idle time allowed for reusing a connection +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXAGE_CONN, long age); +.fi +.SH DESCRIPTION +Pass a long as parameter containing \fIage\fP \- the maximum time in seconds +allowed for an existing connection to have been idle to be considered for +reuse for this request. + +The "connection cache" holds previously used connections. When a new request +is to be done, libcurl considers any connection that matches for reuse. The +\fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying too old +connections for reuse, since old connections have a higher risk of not working +and thus trying them is a performance loss and sometimes service loss due to +the difficulties to figure out the situation. If a connection is found in the +cache that is older than this set \fIage\fP, it is closed instead. +.SH DEFAULT +118 seconds +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* only allow 30 seconds idle time */ + curl_easy_setopt(curl, CURLOPT_MAXAGE_CONN, 30L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.65.0 +.SH RETURN VALUE +Returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_FORBID_REUSE (3), +.BR CURLOPT_FRESH_CONNECT (3), +.BR CURLOPT_MAXLIFETIME_CONN (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAXCONNECTS.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAXCONNECTS.3 new file mode 100644 index 0000000..9ea208d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAXCONNECTS.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAXCONNECTS.md +.TH CURLOPT_MAXCONNECTS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAXCONNECTS \- maximum connection cache size +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXCONNECTS, long amount); +.fi +.SH DESCRIPTION +Pass a long. The set \fIamount\fP is the maximum number of simultaneously open +persistent connections that libcurl may cache in the pool associated with this +handle. The default is 5, and there is not much point in changing this value +unless you are perfectly aware of how this works. This concerns connections +using any of the protocols that support persistent connections. + +When reaching the maximum limit, curl closes the oldest one in the cache to +prevent increasing the number of open connections. + +If you already have performed transfers with this curl handle, setting a +smaller \fICURLOPT_MAXCONNECTS(3)\fP than before may cause open connections to +get closed unnecessarily. + +If you add this easy handle to a multi handle, this setting is not +acknowledged, and you must instead use \fIcurl_multi_setopt(3)\fP and the +\fICURLMOPT_MAXCONNECTS(3)\fP option. +.SH DEFAULT +5 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* limit the connection cache for this handle to no more than 3 */ + curl_easy_setopt(curl, CURLOPT_MAXCONNECTS, 3L); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.7 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLMOPT_MAXCONNECTS (3), +.BR CURLMOPT_MAX_HOST_CONNECTIONS (3), +.BR CURLMOPT_MAX_TOTAL_CONNECTIONS (3), +.BR CURLOPT_MAXREDIRS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAXFILESIZE.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAXFILESIZE.3 new file mode 100644 index 0000000..4124cd0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAXFILESIZE.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAXFILESIZE.md +.TH CURLOPT_MAXFILESIZE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAXFILESIZE \- maximum file size allowed to download +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE, long size); +.fi +.SH DESCRIPTION +Pass a long as parameter. This specifies the maximum accepted \fIsize\fP (in +bytes) of a file to download. If the file requested is found larger than this +value, the transfer is aborted and \fICURLE_FILESIZE_EXCEEDED\fP is returned. +Passing a zero \fIsize\fP disables this, and passing a negative \fIsize\fP yields a +\fICURLE_BAD_FUNCTION_ARGUMENT\fP. + +The file size is not always known prior to the download start, and for such +transfers this option has no effect \- even if the file transfer eventually +ends up being larger than this given limit. + +If you want a limit above 2GB, use \fICURLOPT_MAXFILESIZE_LARGE(3)\fP. + +Since 8.4.0, this option also stops ongoing transfers if they reach this +threshold. +.SH DEFAULT +0, meaning disabled. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* refuse to download if larger than 1000 bytes! */ + curl_easy_setopt(curl, CURLOPT_MAXFILESIZE, 1000L); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.8 +.SH RETURN VALUE +Returns CURLE_OK if the size passed is valid or CURLE_BAD_FUNCTION_ARGUMENT if +not. +.SH SEE ALSO +.BR CURLOPT_MAXFILESIZE_LARGE (3), +.BR CURLOPT_MAX_RECV_SPEED_LARGE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAXFILESIZE_LARGE.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAXFILESIZE_LARGE.3 new file mode 100644 index 0000000..f8eb76b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAXFILESIZE_LARGE.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAXFILESIZE_LARGE.md +.TH CURLOPT_MAXFILESIZE_LARGE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAXFILESIZE_LARGE \- maximum file size allowed to download +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE_LARGE, + curl_off_t size); +.fi +.SH DESCRIPTION +Pass a curl_off_t as parameter. This specifies the maximum accepted \fIsize\fP +(in bytes) of a file to download. If the file requested is found larger than +this value, the transfer is aborted and \fICURLE_FILESIZE_EXCEEDED\fP is +returned. Passing a zero \fIsize\fP disables this, and passing a negative \fIsize\fP +yields a \fICURLE_BAD_FUNCTION_ARGUMENT\fP. + +The file size is not always known prior to the download start, and for such +transfers this option has no effect \- even if the file transfer eventually +ends up being larger than this given limit. + +Since 8.4.0, this option also stops ongoing transfers if they reach this +threshold. +.SH DEFAULT +0, meaning disabled. +.SH PROTOCOLS +This functionality affects ftp, http and mqtt +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_off_t ridiculous = (curl_off_t)1 << 48; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* refuse to download if larger than ridiculous */ + curl_easy_setopt(curl, CURLOPT_MAXFILESIZE_LARGE, ridiculous); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.11.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_BAD_FUNCTION_ARGUMENT if the size passed is invalid. +.SH SEE ALSO +.BR CURLOPT_MAXFILESIZE (3), +.BR CURLOPT_MAX_RECV_SPEED_LARGE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAXLIFETIME_CONN.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAXLIFETIME_CONN.3 new file mode 100644 index 0000000..25ae55d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAXLIFETIME_CONN.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAXLIFETIME_CONN.md +.TH CURLOPT_MAXLIFETIME_CONN 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAXLIFETIME_CONN \- max lifetime (since creation) allowed for reusing a connection +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXLIFETIME_CONN, + long maxlifetime); +.fi +.SH DESCRIPTION +Pass a long as parameter containing \fImaxlifetime\fP \- the maximum time in +seconds, since the creation of the connection, that you allow an existing +connection to have to be considered for reuse for this request. + +libcurl features a connection cache that holds previously used connections. +When a new request is to be done, libcurl considers any connection that +matches for reuse. The \fICURLOPT_MAXLIFETIME_CONN(3)\fP limit prevents +libcurl from trying too old connections for reuse. This can be used for +client\-side load balancing. If a connection is found in the cache that is +older than this set \fImaxlifetime\fP, it is instead marked for closure. + +If set to 0, this behavior is disabled: all connections are eligible for reuse. +.SH DEFAULT +0 seconds (i.e., disabled) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* only allow each connection to be reused for 30 seconds */ + curl_easy_setopt(curl, CURLOPT_MAXLIFETIME_CONN, 30L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.80.0 +.SH RETURN VALUE +Returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_FORBID_REUSE (3), +.BR CURLOPT_FRESH_CONNECT (3), +.BR CURLOPT_MAXAGE_CONN (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAXREDIRS.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAXREDIRS.3 new file mode 100644 index 0000000..7b5057e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAXREDIRS.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAXREDIRS.md +.TH CURLOPT_MAXREDIRS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAXREDIRS \- maximum number of redirects allowed +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXREDIRS, long amount); +.fi +.SH DESCRIPTION +Pass a long. The set number is the redirection limit \fIamount\fP. If that +many redirections have been followed, the next redirect triggers the error +(\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the +\fICURLOPT_FOLLOWLOCATION(3)\fP is used at the same time. + +Setting the limit to 0 makes libcurl refuse any redirect. + +Set it to \-1 for an infinite number of redirects. This allows your application +to get stuck in never\-ending redirect loops. +.SH DEFAULT +30 (since 8.3.0), it was previously unlimited. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + + /* enable redirect following */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + /* allow three redirects */ + curl_easy_setopt(curl, CURLOPT_MAXREDIRS, 3L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.5 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_REDIRECT_COUNT (3), +.BR CURLINFO_REDIRECT_URL (3), +.BR CURLOPT_FOLLOWLOCATION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAX_RECV_SPEED_LARGE.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAX_RECV_SPEED_LARGE.3 new file mode 100644 index 0000000..ff1a143 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAX_RECV_SPEED_LARGE.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAX_RECV_SPEED_LARGE.md +.TH CURLOPT_MAX_RECV_SPEED_LARGE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAX_RECV_SPEED_LARGE \- rate limit data download speed +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_RECV_SPEED_LARGE, + curl_off_t maxspeed); +.fi +.SH DESCRIPTION +Pass a curl_off_t as parameter. If a download exceeds this \fImaxspeed\fP +(counted in bytes per second) the transfer pauses to keep the average speed +less than or equal to the parameter value. Defaults to unlimited speed. + +This is not an exact science. libcurl attempts to keep the average speed below +the given threshold over a period time. + +If you set \fImaxspeed\fP to a value lower than \fICURLOPT_BUFFERSIZE(3)\fP, +libcurl might download faster than the set limit initially. + +This option does not affect transfer speeds done with FILE:// URLs. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* cap the download speed to 31415 bytes/sec */ + curl_easy_setopt(curl, CURLOPT_MAX_RECV_SPEED_LARGE, (curl_off_t)31415); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.15.5 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_MAX_SEND_SPEED_LARGE (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MAX_SEND_SPEED_LARGE.3 b/3rdparty/curl/share/man/man3/CURLOPT_MAX_SEND_SPEED_LARGE.3 new file mode 100644 index 0000000..b12a6e1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MAX_SEND_SPEED_LARGE.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MAX_SEND_SPEED_LARGE.md +.TH CURLOPT_MAX_SEND_SPEED_LARGE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MAX_SEND_SPEED_LARGE \- rate limit data upload speed +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_SEND_SPEED_LARGE, + curl_off_t maxspeed); +.fi +.SH DESCRIPTION +Pass a curl_off_t as parameter with the \fImaxspeed\fP. If an upload exceeds +this speed (counted in bytes per second) the transfer pauses to keep the +average speed less than or equal to the parameter value. Defaults to unlimited +speed. + +This is not an exact science. libcurl attempts to keep the average speed below +the given threshold over a period time. + +If you set \fImaxspeed\fP to a value lower than +\fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP, libcurl might "shoot over" the limit on +its first send and still send off a full buffer. + +This option does not affect transfer speeds done with FILE:// URLs. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* cap the upload speed to 1000 bytes/sec */ + curl_easy_setopt(curl, CURLOPT_MAX_SEND_SPEED_LARGE, (curl_off_t)1000); + /* (set some upload options as well!) */ + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.15.5 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_MAX_RECV_SPEED_LARGE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MIMEPOST.3 b/3rdparty/curl/share/man/man3/CURLOPT_MIMEPOST.3 new file mode 100644 index 0000000..3d90737 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MIMEPOST.3 @@ -0,0 +1,62 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MIMEPOST.md +.TH CURLOPT_MIMEPOST 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MIMEPOST \- send data from mime structure +.SH SYNOPSIS +.nf +#include + +curl_mime *mime; + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIMEPOST, mime); +.fi +.SH DESCRIPTION +Pass a mime handle previously obtained from \fIcurl_mime_init(3)\fP. + +This setting is supported by the HTTP protocol to post forms and by the +SMTP and IMAP protocols to provide the email data to send/upload. + +This option is the preferred way of posting an HTTP form, replacing and +extending the \fICURLOPT_HTTPPOST(3)\fP option. + +When setting \fICURLOPT_MIMEPOST(3)\fP to NULL, libcurl resets the request +type for HTTP to the default to disable the POST. Typically that would mean it +is reset to GET. Instead you should set a desired request method explicitly. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_mime *multipart = curl_mime_init(curl); + if(multipart) { + curl_mimepart *part = curl_mime_addpart(multipart); + curl_mime_name(part, "name"); + curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); + part = curl_mime_addpart(multipart); + curl_mime_name(part, "project"); + curl_mime_data(part, "curl", CURL_ZERO_TERMINATED); + part = curl_mime_addpart(multipart); + curl_mime_name(part, "logotype-image"); + curl_mime_filedata(part, "curl.png"); + + /* Set the form info */ + curl_easy_setopt(curl, CURLOPT_MIMEPOST, multipart); + + curl_easy_perform(curl); /* post away! */ + curl_mime_free(multipart); /* free the post data */ + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +This returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_HTTPPOST (3), +.BR CURLOPT_POSTFIELDS (3), +.BR CURLOPT_PUT (3), +.BR curl_mime_init (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_MIME_OPTIONS.3 b/3rdparty/curl/share/man/man3/CURLOPT_MIME_OPTIONS.3 new file mode 100644 index 0000000..f5631e7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_MIME_OPTIONS.3 @@ -0,0 +1,74 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_MIME_OPTIONS.md +.TH CURLOPT_MIME_OPTIONS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_MIME_OPTIONS \- set MIME option flags +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIME_OPTIONS, long options); +.fi +.SH DESCRIPTION +Pass a long that holds a bitmask of CURLMIMEOPT_* defines. Each bit is a +Boolean flag used while encoding a MIME tree or multipart form data. + +Available bits are: +.IP CURLMIMEOPT_FORMESCAPE +Tells libcurl to escape multipart form field and filenames using the +backslash\-escaping algorithm rather than percent\-encoding (HTTP only). + +Backslash\-escaping consists in preceding backslashes and double quotes with +a backslash. Percent encoding maps all occurrences of double quote, +carriage return and line feed to %22, %0D and %0A respectively. + +Before version 7.81.0, percent\-encoding was never applied. + +HTTP browsers used to do backslash\-escaping in the past but have over time +transitioned to use percent\-encoding. This option allows one to address +server\-side applications that have not yet have been converted. + +As an example, consider field or filename \fIstrangename"kind\fP. When the +containing multipart form is sent, this is normally transmitted as +\fIstrangename%22kind\fP. When this option is set, it is sent as +\fIstrangename"kind\fP. +.SH DEFAULT +0, meaning disabled. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + curl_mime *form = NULL; + + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_MIME_OPTIONS, CURLMIMEOPT_FORMESCAPE); + + form = curl_mime_init(curl); + if(form) { + curl_mimepart *part = curl_mime_addpart(form); + + if(part) { + curl_mime_filedata(part, "strange\\\\file\\\\name"); + curl_mime_name(part, "strange\\"field\\"name"); + curl_easy_setopt(curl, CURLOPT_MIMEPOST, form); + + /* Perform the request */ + curl_easy_perform(curl); + } + } + + curl_easy_cleanup(curl); + curl_mime_free(form); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.81.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_HTTPPOST (3), +.BR CURLOPT_MIMEPOST (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_NETRC.3 b/3rdparty/curl/share/man/man3/CURLOPT_NETRC.3 new file mode 100644 index 0000000..089a986 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_NETRC.3 @@ -0,0 +1,106 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_NETRC.md +.TH CURLOPT_NETRC 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_NETRC \- enable use of .netrc +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level); +.fi +.SH DESCRIPTION +This parameter controls the preference \fIlevel\fP of libcurl between using +usernames and passwords from your \fI~/.netrc\fP file, relative to usernames and +passwords in the URL supplied with \fICURLOPT_URL(3)\fP. + +On Windows, libcurl primarily checks for \fI.netrc\fP in \fI%HOME%\fP. If \fI%HOME%\fP is +not set on Windows, libcurl falls back to \fI%USERPROFILE%\fP. If the file does +not exist, it falls back to check if there is instead a file named \fI_netrc\fP \- +using an underscore instead of period. + +You can also tell libcurl a different filename to use with +\fICURLOPT_NETRC_FILE(3)\fP. + +libcurl uses a username (and supplied or prompted password) supplied with +\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP in preference to any of +the options controlled by this parameter. + +Only machine name, username and password are taken into account (init macros +and similar things are not supported). + +libcurl does not verify that the file has the correct properties set (as the +standard Unix ftp client does). It should only be readable by user. + +\fIlevel\fP is a long that should be set to one of the values described below. +.IP "CURL_NETRC_IGNORED (0)" +libcurl ignores the \fI.netrc\fP file. This is the default. +.IP "CURL_NETRC_OPTIONAL (1)" +The use of the \fI.netrc\fP file is optional, and information in the URL is to +be preferred. The file is scanned for the host and username (to find the +password only) or for the host only, to find the first username and password +after that \fImachine\fP, which ever information is not specified. +.IP "CURL_NETRC_REQUIRED (2)" +The use of the \fI.netrc\fP file is required, and any credential information +present in the URL is ignored. The file is scanned for the host and username +(to find the password only) or for the host only, to find the first username +and password after that \fImachine\fP, which ever information is not +specified. +.SH FILE FORMAT +The \fB.netrc\fP file format is simple: you specify lines with a machine name +and follow the login and password that are associated with that machine. + +Each field is provided as a sequence of letters that ends with a space or +newline. Starting in 7.84.0, libcurl also supports quoted strings. They start +and end with double quotes and support the escaped special letters ", n, +r, and t. Quoted strings are the only way a space character can be used in +a username or password. +.IP "machine \" +Provides credentials for a host called \fBname\fP. libcurl searches the .netrc +file for a machine token that matches the hostname specified in the URL. Once +a match is made, the subsequent tokens are processed, stopping when the end of +file is reached or another "machine" is encountered. +.IP default +This is the same as machine name except that default matches any name. There +can be only one default token, and it must be after all machine tokens. To +provide a default anonymous login for hosts that are not otherwise matched, +add a line similar to this in the end: + +.nf +default login anonymous password user@domain +.fi +.IP "login \" +The username string for the remote machine. +.IP "password \" +Supply a password. If this token is present, curl supplies the specified +string if the remote server requires a password as part of the login process. +Note that if this token is present in the .netrc file you really should make +sure the file is not readable by anyone besides the user. +.IP "macdef \" +Define a macro. This feature is not supported by libcurl. In order for the +rest of the .netrc to still work fine, libcurl properly skips every definition +done with "macdef" that it finds. +.SH DEFAULT +CURL_NETRC_IGNORED +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); + curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_NETRC_FILE (3), +.BR CURLOPT_USERNAME (3), +.BR CURLOPT_USERPWD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_NETRC_FILE.3 b/3rdparty/curl/share/man/man3/CURLOPT_NETRC_FILE.3 new file mode 100644 index 0000000..19076cd --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_NETRC_FILE.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_NETRC_FILE.md +.TH CURLOPT_NETRC_FILE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_NETRC_FILE \- filename to read .netrc info from +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC_FILE, char *file); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, pointing to a null\-terminated string +containing the full path name to the \fIfile\fP you want libcurl to use as .netrc +file. If this option is omitted, and \fICURLOPT_NETRC(3)\fP is set, libcurl checks +for a .netrc file in the current user\(aqs home directory. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); + curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL); + curl_easy_setopt(curl, CURLOPT_NETRC_FILE, "/tmp/magic-netrc"); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.11.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_NETRC (3), +.BR CURLOPT_PASSWORD (3), +.BR CURLOPT_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_NEW_DIRECTORY_PERMS.3 b/3rdparty/curl/share/man/man3/CURLOPT_NEW_DIRECTORY_PERMS.3 new file mode 100644 index 0000000..1ea428e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_NEW_DIRECTORY_PERMS.3 @@ -0,0 +1,43 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_NEW_DIRECTORY_PERMS.md +.TH CURLOPT_NEW_DIRECTORY_PERMS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_NEW_DIRECTORY_PERMS \- permissions for remotely created directories +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_DIRECTORY_PERMS, + long mode); +.fi +.SH DESCRIPTION +Pass a long as a parameter, containing the value of the permissions that is +set on newly created directories on the remote server. The default value is +\fI0755\fP, but any valid value can be used. The only protocols that can use +this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. +.SH DEFAULT +0755 +.SH PROTOCOLS +This functionality affects file, scp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, + "sftp://upload.example.com/newdir/file.zip"); + curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS, 1L); + curl_easy_setopt(curl, CURLOPT_NEW_DIRECTORY_PERMS, 0644L); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FTP_CREATE_MISSING_DIRS (3), +.BR CURLOPT_NEW_FILE_PERMS (3), +.BR CURLOPT_UPLOAD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_NEW_FILE_PERMS.3 b/3rdparty/curl/share/man/man3/CURLOPT_NEW_FILE_PERMS.3 new file mode 100644 index 0000000..a7610cf --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_NEW_FILE_PERMS.3 @@ -0,0 +1,39 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_NEW_FILE_PERMS.md +.TH CURLOPT_NEW_FILE_PERMS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_NEW_FILE_PERMS \- permissions for remotely created files +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_FILE_PERMS, + long mode); +.fi +.SH DESCRIPTION +Pass a long as a parameter, containing the value of the permissions that are +set on newly created files on the remote server. The default value is \fI0644\fP. +The only protocols that can use this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. +.SH DEFAULT +0644 +.SH PROTOCOLS +This functionality affects file, scp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://upload.example.com/file.txt"); + curl_easy_setopt(curl, CURLOPT_NEW_FILE_PERMS, 0664L); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_NEW_DIRECTORY_PERMS (3), +.BR CURLOPT_UPLOAD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_NOBODY.3 b/3rdparty/curl/share/man/man3/CURLOPT_NOBODY.3 new file mode 100644 index 0000000..4deecd7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_NOBODY.3 @@ -0,0 +1,57 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_NOBODY.md +.TH CURLOPT_NOBODY 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_NOBODY \- do the download request without getting the body +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOBODY, long opt); +.fi +.SH DESCRIPTION +A long parameter set to 1 tells libcurl to not include the body\-part in the +output when doing what would otherwise be a download. For HTTP(S), this makes +libcurl do a HEAD request. For most other protocols it means just not asking +to transfer the body data. + +For HTTP operations when \fICURLOPT_NOBODY(3)\fP has been set, disabling this +option (with 0) makes it a GET again \- only if the method is still set to be +HEAD. The proper way to get back to a GET request is to set +\fICURLOPT_HTTPGET(3)\fP and for other methods, use the POST or UPLOAD +options. + +Enabling \fICURLOPT_NOBODY(3)\fP means asking for a download without a body. + +If you do a transfer with HTTP that involves a method other than HEAD, you get +a body (unless the resource and server sends a zero byte body for the specific +URL you request). +.SH DEFAULT +0, the body is transferred +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* get us the resource without a body - use HEAD! */ + curl_easy_setopt(curl, CURLOPT_NOBODY, 1L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_HTTPGET (3), +.BR CURLOPT_MIMEPOST (3), +.BR CURLOPT_POSTFIELDS (3), +.BR CURLOPT_REQUEST_TARGET (3), +.BR CURLOPT_UPLOAD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_NOPROGRESS.3 b/3rdparty/curl/share/man/man3/CURLOPT_NOPROGRESS.3 new file mode 100644 index 0000000..1805943 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_NOPROGRESS.3 @@ -0,0 +1,44 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_NOPROGRESS.md +.TH CURLOPT_NOPROGRESS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_NOPROGRESS \- switch off the progress meter +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROGRESS, long onoff); +.fi +.SH DESCRIPTION +If \fIonoff\fP is to 1, it tells the library to shut off the progress meter +completely for requests done with this \fIhandle\fP. It also prevents the +\fICURLOPT_XFERINFOFUNCTION(3)\fP or \fICURLOPT_PROGRESSFUNCTION(3)\fP from +getting called. +.SH DEFAULT +1, meaning it normally runs without a progress meter. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable progress meter */ + curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_PROGRESSFUNCTION (3), +.BR CURLOPT_VERBOSE (3), +.BR CURLOPT_XFERINFOFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_NOPROXY.3 b/3rdparty/curl/share/man/man3/CURLOPT_NOPROXY.3 new file mode 100644 index 0000000..e999b9b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_NOPROXY.3 @@ -0,0 +1,72 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_NOPROXY.md +.TH CURLOPT_NOPROXY 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_NOPROXY \- disable proxy use for specific hosts +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROXY, char *noproxy); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string. The string consists of a comma +separated list of hostnames that do not require a proxy to get reached, even +if one is specified. The only wildcard available is a single * character, +which matches all hosts, and effectively disables the proxy. Each name in this +list is matched as either a domain which contains the hostname, or the +hostname itself. For example, "ample.com" would match ample.com, ample.com:80, +and www.ample.com, but not www.example.com or ample.com.org. + +Setting the \fInoproxy\fP string to "" (an empty string) explicitly enables the +proxy for all hostnames, even if there is an environment variable set for it. + +Enter IPv6 numerical addresses in the list of hostnames without enclosing +brackets: + +.nf +"example.com,::1,localhost" +.fi + +Since 7.86.0, IP addresses specified to this option can be provided using CIDR +notation: an appended slash and number specifies the number of "network bits" +out of the address to use in the comparison. For example "192.168.0.0/16" +would match all addresses starting with "192.168". + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH Environment variables +If there is an environment variable called \fBno_proxy\fP (or \fBNO_PROXY\fP), +it is used if the \fICURLOPT_NOPROXY(3)\fP option is not set. It works exactly +the same way. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* accept various URLs */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* use this proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); + /* ... but make sure this host name is not proxied */ + curl_easy_setopt(curl, CURLOPT_NOPROXY, "www.example.com"); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY (3), +.BR CURLOPT_PROXYAUTH (3), +.BR CURLOPT_PROXYTYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_NOSIGNAL.3 b/3rdparty/curl/share/man/man3/CURLOPT_NOSIGNAL.3 new file mode 100644 index 0000000..dabb578 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_NOSIGNAL.3 @@ -0,0 +1,55 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_NOSIGNAL.md +.TH CURLOPT_NOSIGNAL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_NOSIGNAL \- skip all signal handling +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOSIGNAL, long onoff); +.fi +.SH DESCRIPTION +If \fIonoff\fP is 1, libcurl uses no functions that install signal handlers or +any functions that cause signals to be sent to the process. This option is +here to allow multi\-threaded Unix applications to still set/use all timeout +options etc, without risking getting signals. + +If this option is set and libcurl has been built with the standard name +resolver, timeouts cannot occur while the name resolve takes place. Consider +building libcurl with the c\-ares or threaded resolver backends to enable +asynchronous DNS lookups, to enable timeouts for name resolves without the use +of signals. + +Setting \fICURLOPT_NOSIGNAL(3)\fP to 1 makes libcurl NOT ask the system to +ignore SIGPIPE signals, which otherwise are sent by the system when trying to +send data to a socket which is closed in the other end. libcurl makes an +effort to never cause such SIGPIPE signals to trigger, but some operating +systems have no way to avoid them and even on those that have there are some +corner cases when they may still happen, contrary to our desire. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + + curl_easy_setopt(curl, CURLOPT_NOSIGNAL, 1L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_TIMEOUT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_OPENSOCKETDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_OPENSOCKETDATA.3 new file mode 100644 index 0000000..0b825cf --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_OPENSOCKETDATA.3 @@ -0,0 +1,71 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_OPENSOCKETDATA.md +.TH CURLOPT_OPENSOCKETDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_OPENSOCKETDATA \- pointer passed to open socket callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETDATA, void *pointer); +.fi +.SH DESCRIPTION +Pass a \fIpointer\fP that is untouched by libcurl and passed as the first +argument in the open socket callback set with +\fICURLOPT_OPENSOCKETFUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +/* make libcurl use the already established socket 'sockfd' */ + +static curl_socket_t opensocket(void *clientp, + curlsocktype purpose, + struct curl_sockaddr *address) +{ + curl_socket_t sockfd; + sockfd = *(curl_socket_t *)clientp; + /* the actual externally set socket is passed in via the OPENSOCKETDATA + option */ + return sockfd; +} + +static int sockopt_callback(void *clientp, curl_socket_t curlfd, + curlsocktype purpose) +{ + /* This return code was added in libcurl 7.21.5 */ + return CURL_SOCKOPT_ALREADY_CONNECTED; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + extern int sockfd; /* the already connected one */ + + /* libcurl thinks that you connect to the host + * and port that you specify in the URL option. */ + curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999"); + /* call this function to get a socket */ + curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket); + curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd); + + /* call this function to set options for the socket */ + curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.17.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CLOSESOCKETFUNCTION (3), +.BR CURLOPT_OPENSOCKETFUNCTION (3), +.BR CURLOPT_SOCKOPTFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_OPENSOCKETFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_OPENSOCKETFUNCTION.3 new file mode 100644 index 0000000..28741be --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_OPENSOCKETFUNCTION.3 @@ -0,0 +1,111 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_OPENSOCKETFUNCTION.md +.TH CURLOPT_OPENSOCKETFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_OPENSOCKETFUNCTION \- callback for opening socket +.SH SYNOPSIS +.nf +#include + +typedef enum { + CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */ +} curlsocktype; + +struct curl_sockaddr { + int family; + int socktype; + int protocol; + unsigned int addrlen; + struct sockaddr addr; +}; + +curl_socket_t opensocket_callback(void *clientp, + curlsocktype purpose, + struct curl_sockaddr *address); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETFUNCTION, opensocket_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl instead of the \fIsocket(2)\fP +call. The callback\(aqs \fIpurpose\fP argument identifies the exact purpose for +this particular socket. \fICURLSOCKTYPE_IPCXN\fP is for IP based connections +and is the only purpose currently used in libcurl. Future versions of libcurl +may support more purposes. + +The \fIclientp\fP pointer contains whatever user\-defined value set using the +\fICURLOPT_OPENSOCKETDATA(3)\fP function. + +The callback gets the resolved peer address as the \fIaddress\fP argument and +is allowed to modify the address or refuse to connect completely. The callback +function should return the newly created socket or \fICURL_SOCKET_BAD\fP in +case no connection could be established or another error was detected. Any +additional \fIsetsockopt(2)\fP calls can of course be done on the socket at +the user\(aqs discretion. A \fICURL_SOCKET_BAD\fP return value from the callback +function signals an unrecoverable error to libcurl and it returns +\fICURLE_COULDNT_CONNECT\fP from the function that triggered this callback. +This return code can be used for IP address block listing. + +If you want to pass in a socket with an already established connection, pass +the socket back with this callback and then use +\fICURLOPT_SOCKOPTFUNCTION(3)\fP to signal that it already is connected. +.SH DEFAULT +The equivalent of this: +.nf + return socket(addr->family, addr->socktype, addr->protocol); +.fi +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +/* make libcurl use the already established socket 'sockfd' */ + +static curl_socket_t opensocket(void *clientp, + curlsocktype purpose, + struct curl_sockaddr *address) +{ + curl_socket_t sockfd; + sockfd = *(curl_socket_t *)clientp; + /* the actual externally set socket is passed in via the OPENSOCKETDATA + option */ + return sockfd; +} + +static int sockopt_callback(void *clientp, curl_socket_t curlfd, + curlsocktype purpose) +{ + /* This return code was added in libcurl 7.21.5 */ + return CURL_SOCKOPT_ALREADY_CONNECTED; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + extern int sockfd; /* the already connected one */ + /* libcurl thinks that you connect to the host + * and port that you specify in the URL option. */ + curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999"); + /* call this function to get a socket */ + curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket); + curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd); + + /* call this function to set options for the socket */ + curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.17.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CLOSESOCKETFUNCTION (3), +.BR CURLOPT_OPENSOCKETFUNCTION (3), +.BR CURLOPT_SOCKOPTFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PASSWORD.3 b/3rdparty/curl/share/man/man3/CURLOPT_PASSWORD.3 new file mode 100644 index 0000000..5934ffc --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PASSWORD.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PASSWORD.md +.TH CURLOPT_PASSWORD 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PASSWORD \- password to use in authentication +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PASSWORD, char *pwd); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should be pointing to the +null\-terminated password to use for the transfer. + +The \fICURLOPT_PASSWORD(3)\fP option should be used in conjunction with the +\fICURLOPT_USERNAME(3)\fP option. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +blank +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + curl_easy_setopt(curl, CURLOPT_PASSWORD, "qwerty"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_HTTPAUTH (3), +.BR CURLOPT_PROXYAUTH (3), +.BR CURLOPT_USERNAME (3), +.BR CURLOPT_USERPWD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PATH_AS_IS.3 b/3rdparty/curl/share/man/man3/CURLOPT_PATH_AS_IS.3 new file mode 100644 index 0000000..b9add58 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PATH_AS_IS.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PATH_AS_IS.md +.TH CURLOPT_PATH_AS_IS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PATH_AS_IS \- do not handle dot dot sequences +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PATH_AS_IS, long leaveit); +.fi +.SH DESCRIPTION +Set the long \fIleaveit\fP to 1, to explicitly tell libcurl to not alter the +given path before passing it on to the server. + +This instructs libcurl to NOT squash sequences of "/../" or "/./" that may +exist in the URL\(aqs path part and that is supposed to be removed according to +RFC 3986 section 5.2.4. + +Some server implementations are known to (erroneously) require the dot dot +sequences to remain in the path and some clients want to pass these on in +order to try out server implementations. + +By default libcurl normalizes such sequences before using the path. + +The corresponding flag for the \fIcurl_url_set(3)\fP function is called +\fBCURLU_PATH_AS_IS\fP. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, + "https://example.com/../../etc/password"); + + curl_easy_setopt(curl, CURLOPT_PATH_AS_IS, 1L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.42.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_STDERR (3), +.BR CURLOPT_URL (3), +.BR curl_url_set (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PINNEDPUBLICKEY.3 b/3rdparty/curl/share/man/man3/CURLOPT_PINNEDPUBLICKEY.3 new file mode 100644 index 0000000..2b504e4 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PINNEDPUBLICKEY.3 @@ -0,0 +1,122 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PINNEDPUBLICKEY.md +.TH CURLOPT_PINNEDPUBLICKEY 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PINNEDPUBLICKEY \- pinned public key +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PINNEDPUBLICKEY, + char *pinnedpubkey); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. The string can be the +filename of your pinned public key. The file format expected is "PEM" or +\&"DER". The string can also be any number of base64 encoded sha256 hashes +preceded by "sha256//" and separated by ";" + +When negotiating a TLS or SSL connection, the server sends a certificate +indicating its identity. A public key is extracted from this certificate and +if it does not exactly match the public key provided to this option, curl +aborts the connection before sending or receiving any data. + +This option is independent of option \fICURLOPT_SSL_VERIFYPEER(3)\fP. If you turn +off that option then the peer is still verified by public key. + +On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_PINNEDPUBLICKEY, "/etc/publickey.der"); + /* OR + curl_easy_setopt(curl, CURLOPT_PINNEDPUBLICKEY, + "sha256//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjAa3HWY3" + "tvRMwE=;sha256//t62CeU2tQiqkexU74Gxa2eg7fRbEg" + "oChTociMee9wno="); + */ + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH PUBLIC KEY EXTRACTION +If you do not have the server\(aqs public key file you can extract it from the +server\(aqs certificate. +.nf +# retrieve the server's certificate if you do not already have it +# +# be sure to examine the certificate to see if it is what you expected +# +# Windows-specific: +# - Use NUL instead of /dev/null. +# - OpenSSL may wait for input instead of disconnecting. Hit enter. +# - If you do not have sed, then just copy the certificate into a file: +# Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----. +# +openssl s_client -servername www.example.com -connect www.example.com:443 \\ + < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem + +# extract public key in pem format from certificate +openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem + +# convert public key from pem to der +openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem \\ + -out www.example.com.pubkey.der + +# sha256 hash and base64 encode der to string for use +openssl dgst -sha256 -binary www.example.com.pubkey.der | openssl base64 +.fi + +The public key in PEM format contains a header, base64 data and a +footer: +.nf +-----BEGIN PUBLIC KEY----- +[BASE 64 DATA] +-----END PUBLIC KEY----- +.fi +.SH HISTORY +.IP "PEM/DER support" +7.39.0: OpenSSL, GnuTLS + +7.43.0: wolfSSL + +7.47.0: mbedTLS + +7.54.1: Secure Transport on macOS 10.7+/iOS 10+ + +7.58.1: Schannel +.IP "sha256 support" +7.44.0: OpenSSL, GnuTLS and wolfSSL + +7.47.0: mbedTLS + +7.54.1: Secure Transport on macOS 10.7+/iOS 10+ + +7.58.1: Schannel + +Other SSL backends not supported. +.SH AVAILABILITY +Added in curl 7.39.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_CAPATH (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PIPEWAIT.3 b/3rdparty/curl/share/man/man3/CURLOPT_PIPEWAIT.3 new file mode 100644 index 0000000..9bf3483 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PIPEWAIT.3 @@ -0,0 +1,57 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PIPEWAIT.md +.TH CURLOPT_PIPEWAIT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PIPEWAIT \- wait for multiplexing +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PIPEWAIT, long wait); +.fi +.SH DESCRIPTION +Set \fIwait\fP to 1L to tell libcurl to prefer to wait for a connection to +confirm or deny that it can do multiplexing before continuing. + +When about to perform a new transfer that allows multiplexing, libcurl checks +for existing connections to use. If no such connection exists it immediately +continues and creates a fresh new connection to use. + +By setting this option to 1 \- and having \fICURLMOPT_PIPELINING(3)\fP enabled +for the multi handle this transfer is associated with \- libcurl instead waits +for the connection to reveal if it is possible to multiplex on before it +continues. This enables libcurl to much better keep the number of connections +to a minimum when using multiplexing protocols. + +With this option set, libcurl prefers to wait and reuse an existing connection +for multiplexing rather than the opposite: prefer to open a new connection +rather than waiting. + +The waiting time is as long as it takes for the connection to get up and for +libcurl to get the necessary response back that informs it about its protocol +and support level. +.SH DEFAULT +0 (off) +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PIPEWAIT, 1L); + + /* now add this easy handle to the multi handle */ + } +} +.fi +.SH AVAILABILITY +Added in curl 7.43.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_MAX_HOST_CONNECTIONS (3), +.BR CURLMOPT_PIPELINING (3), +.BR CURLOPT_FORBID_REUSE (3), +.BR CURLOPT_FRESH_CONNECT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PORT.3 b/3rdparty/curl/share/man/man3/CURLOPT_PORT.3 new file mode 100644 index 0000000..2dc11c3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PORT.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PORT.md +.TH CURLOPT_PORT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PORT \- remote port number to connect to +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PORT, long number); +.fi +.SH DESCRIPTION +We discourage using this option since its scope is not obvious and hard to +predict. Set the preferred port number in the URL instead. + +This option sets \fInumber\fP to be the remote port number to connect to, +instead of the one specified in the URL or the default port for the used +protocol. + +Usually, you just let the URL decide which port to use but this allows the +application to override that. + +While this option accepts a \(aqlong\(aq, a port number is an unsigned 16 bit number +and therefore using a port number lower than zero or over 65535 causes a +\fBCURLE_BAD_FUNCTION_ARGUMENT\fP error. +.SH DEFAULT +0 which makes it not used. This also makes port number zero impossible to set +with this API. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PORT, 8080L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLINFO_PRIMARY_PORT (3), +.BR CURLOPT_STDERR (3), +.BR CURLOPT_URL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_POST.3 b/3rdparty/curl/share/man/man3/CURLOPT_POST.3 new file mode 100644 index 0000000..d9188de --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_POST.3 @@ -0,0 +1,81 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_POST.md +.TH CURLOPT_POST 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_POST \- make an HTTP POST +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POST, long post); +.fi +.SH DESCRIPTION +A parameter set to 1 tells libcurl to do a regular HTTP post. This also makes +libcurl use a "Content\-Type: application/x\-www\-form\-urlencoded" header. This +is the most commonly used POST method. + +Use one of \fICURLOPT_POSTFIELDS(3)\fP or \fICURLOPT_COPYPOSTFIELDS(3)\fP +options to specify what data to post and \fICURLOPT_POSTFIELDSIZE(3)\fP or +\fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP to set the data size. + +Optionally, you can provide data to POST using the +\fICURLOPT_READFUNCTION(3)\fP and \fICURLOPT_READDATA(3)\fP options but then +you must make sure to not set \fICURLOPT_POSTFIELDS(3)\fP to anything but +NULL. When providing data with a callback, you must transmit it using chunked +transfer\-encoding or you must set the size of the data with the +\fICURLOPT_POSTFIELDSIZE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP +options. To enable chunked encoding, you simply pass in the appropriate +Transfer\-Encoding header, see the post\-callback.c example. + +You can override the default POST Content\-Type: header by setting your own +with \fICURLOPT_HTTPHEADER(3)\fP. + +Using POST with HTTP 1.1 implies the use of a "Expect: 100\-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. + +If you use POST to an HTTP 1.1 server, you can send data without knowing the +size before starting the POST if you use chunked encoding. You enable this by +adding a header like "Transfer\-Encoding: chunked" with +\fICURLOPT_HTTPHEADER(3)\fP. With HTTP 1.0 or without chunked transfer, you +must specify the size in the request. (Since 7.66.0, libcurl automatically +uses chunked encoding for POSTs if the size is unknown.) + +When setting \fICURLOPT_POST(3)\fP to 1, libcurl automatically sets +\fICURLOPT_NOBODY(3)\fP and \fICURLOPT_HTTPGET(3)\fP to 0. + +If you issue a POST request and then want to make a HEAD or GET using the same +reused handle, you must explicitly set the new request type using +\fICURLOPT_NOBODY(3)\fP or \fICURLOPT_HTTPGET(3)\fP or similar. + +When setting \fICURLOPT_POST(3)\fP to 0, libcurl resets the request type to the +default to disable the POST. Typically that means gets reset to GET. Instead +you should set a new request type explicitly as described above. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_POST, 1L); + + /* set up the read callback with CURLOPT_READFUNCTION */ + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTPPOST (3), +.BR CURLOPT_POSTFIELDS (3), +.BR CURLOPT_UPLOAD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_POSTFIELDS.3 b/3rdparty/curl/share/man/man3/CURLOPT_POSTFIELDS.3 new file mode 100644 index 0000000..ded9222 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_POSTFIELDS.3 @@ -0,0 +1,106 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_POSTFIELDS.md +.TH CURLOPT_POSTFIELDS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_POSTFIELDS \- data to POST to server +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, pointing to the data buffer to use in an +HTTP POST operation or an MQTT subscribe. The data must be formatted and +encoded the way you want the server to receive it. libcurl does not convert or +encode it in any way. For example, a web server may assume that this data is +URL encoded. + +The data pointed to is NOT copied by the library: as a consequence, it must be +preserved by the calling application until the associated transfer finishes. +This behavior can be changed (so libcurl does copy the data) by instead using +the \fICURLOPT_COPYPOSTFIELDS(3)\fP option. + +This POST is a normal \fBapplication/x\-www\-form\-urlencoded\fP kind (and libcurl +sets that Content\-Type by default when this option is used), which is commonly +used by HTML forms. Change Content\-Type with \fICURLOPT_HTTPHEADER(3)\fP. + +You can use \fIcurl_easy_escape(3)\fP to URL encode your data, if +necessary. It returns a pointer to an encoded string that can be passed as +\fIpostdata\fP. + +Using \fICURLOPT_POSTFIELDS(3)\fP implies setting \fICURLOPT_POST(3)\fP to 1. + +If \fICURLOPT_POSTFIELDS(3)\fP is explicitly set to NULL then libcurl gets the POST +data from the read callback. To send a zero\-length (empty) POST, set +\fICURLOPT_POSTFIELDS(3)\fP to an empty string, or set \fICURLOPT_POST(3)\fP to 1 and +\fICURLOPT_POSTFIELDSIZE(3)\fP to 0. + +libcurl assumes this option points to a null\-terminated string unless you also +set \fICURLOPT_POSTFIELDSIZE(3)\fP to specify the length of the provided data, which +then is strictly required if you want to send off null bytes included in the +data. + +Using POST with HTTP 1.1 implies the use of a "Expect: 100\-continue" header, +and libcurl adds that header automatically if the POST is either known to be +larger than 1MB or if the expected size is unknown. You can disable this +header with \fICURLOPT_HTTPHEADER(3)\fP as usual. + +To make \fBmultipart/formdata\fP posts, check out the +\fICURLOPT_MIMEPOST(3)\fP option combined with \fIcurl_mime_init(3)\fP. + +Using this option multiple times makes the last set pointer override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http and mqtt +.SH EXAMPLE +.nf +/* send an application/x-www-form-urlencoded POST */ +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + const char *data = "data to send"; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* size of the POST data if strlen() is not good enough */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); + + /* pass in a pointer to the data - libcurl does not copy */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); + } + + /* send an application/json POST */ + curl = curl_easy_init(); + if(curl) { + const char *json = "{\\"name\\": \\"daniel\\"}"; + struct curl_slist *slist1 = NULL; + slist1 = curl_slist_append(slist1, "Content-Type: application/json"); + slist1 = curl_slist_append(slist1, "Accept: application/json"); + + /* set custom headers */ + curl_easy_setopt(curl, CURLOPT_HTTPHEADER, slist1); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* pass in a pointer to the data - libcurl does not copy */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_COPYPOSTFIELDS (3), +.BR CURLOPT_MIMEPOST (3), +.BR CURLOPT_POSTFIELDSIZE (3), +.BR CURLOPT_READFUNCTION (3), +.BR CURLOPT_UPLOAD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_POSTFIELDSIZE.3 b/3rdparty/curl/share/man/man3/CURLOPT_POSTFIELDSIZE.3 new file mode 100644 index 0000000..8109ec6 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_POSTFIELDSIZE.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_POSTFIELDSIZE.md +.TH CURLOPT_POSTFIELDSIZE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_POSTFIELDSIZE \- size of POST data pointed to +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE, long size); +.fi +.SH DESCRIPTION +If you want to post static data to the server without having libcurl do a +strlen() to measure the data size, this option must be used. When this option +is used you can post fully binary data, which otherwise is likely to fail. If +this size is set to \-1, libcurl uses strlen() to get the size or relies on the +\fICURLOPT_READFUNCTION(3)\fP (if used) to signal the end of data. + +If you post more than 2GB, use \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP. +.SH DEFAULT +-1 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +#include /* for strlen */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + const char *data = "data to send"; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* size of the POST data */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long) strlen(data)); + + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.2 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_POSTFIELDS (3), +.BR CURLOPT_POSTFIELDSIZE_LARGE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_POSTFIELDSIZE_LARGE.3 b/3rdparty/curl/share/man/man3/CURLOPT_POSTFIELDSIZE_LARGE.3 new file mode 100644 index 0000000..fec92d4 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_POSTFIELDSIZE_LARGE.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_POSTFIELDSIZE_LARGE.md +.TH CURLOPT_POSTFIELDSIZE_LARGE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_POSTFIELDSIZE_LARGE \- size of POST data pointed to +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE_LARGE, + curl_off_t size); +.fi +.SH DESCRIPTION +If you want to post static data to the server without having libcurl do a +strlen() to measure the data size, this option must be used. When this option +is used you can post fully binary data, which otherwise is likely to fail. If +this size is set to \-1, libcurl uses strlen() to get the size or relies on the +\fICURLOPT_READFUNCTION(3)\fP (if used) to signal the end of data. +.SH DEFAULT +-1 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +extern char *large_chunk; /* pointer to somewhere */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + const char *data = large_chunk; + curl_off_t length_of_data; /* set somehow */ + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* size of the POST data */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE_LARGE, length_of_data); + + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.11.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_COPYPOSTFIELDS (3), +.BR CURLOPT_POSTFIELDS (3), +.BR CURLOPT_POSTFIELDSIZE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_POSTQUOTE.3 b/3rdparty/curl/share/man/man3/CURLOPT_POSTQUOTE.3 new file mode 100644 index 0000000..b767b2e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_POSTQUOTE.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_POSTQUOTE.md +.TH CURLOPT_POSTQUOTE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_POSTQUOTE \- (S)FTP commands to run after the transfer +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTQUOTE, + struct curl_slist *cmds); +.fi +.SH DESCRIPTION +Pass a pointer to a linked list of FTP or SFTP commands to pass to the server +after your FTP transfer request. The commands are only issued if no error +occur. The linked list should be a fully valid list of struct curl_slist +structs properly filled in as described for \fICURLOPT_QUOTE(3)\fP. + +Using this option multiple times makes the last set list override the previous +ones. Set it to NULL to disable its use again. + +libcurl does not copy the list, it needs to be kept around until after the +transfer has completed. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + struct curl_slist *cmdlist = NULL; + cmdlist = curl_slist_append(cmdlist, "RNFR source-name"); + cmdlist = curl_slist_append(cmdlist, "RNTO new-name"); + + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); + + /* pass in the FTP commands to run after the transfer */ + curl_easy_setopt(curl, CURLOPT_POSTQUOTE, cmdlist); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } + curl_slist_free_all(cmdlist); +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_PREQUOTE (3), +.BR CURLOPT_QUOTE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_POSTREDIR.3 b/3rdparty/curl/share/man/man3/CURLOPT_POSTREDIR.3 new file mode 100644 index 0000000..56030a2 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_POSTREDIR.3 @@ -0,0 +1,62 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_POSTREDIR.md +.TH CURLOPT_POSTREDIR 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_POSTREDIR \- how to act on an HTTP POST redirect +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTREDIR, + long bitmask); +.fi +.SH DESCRIPTION +Pass a bitmask to control how libcurl acts on redirects after POSTs that get a +301, 302 or 303 response back. A parameter with bit 0 set (value +\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC 7231 (section +6.4.2 to 6.4.4) and not convert POST requests into GET requests when following +a 301 redirection. Setting bit 1 (value \fBCURL_REDIR_POST_302\fP) makes +libcurl maintain the request method after a 302 redirect whilst setting bit 2 +(value \fBCURL_REDIR_POST_303\fP) makes libcurl maintain the request method +after a 303 redirect. The value \fBCURL_REDIR_POST_ALL\fP is a convenience +define that sets all three bits. + +The non\-RFC behavior is ubiquitous in web browsers, so the library does the +conversion by default to maintain consistency. However, a server may require a +POST to remain a POST after such a redirection. This option is meaningful only +when setting \fICURLOPT_FOLLOWLOCATION(3)\fP. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* a silly POST example */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data=true"); + + /* example.com is redirected, so we tell libcurl to send POST on 301, + 302 and 303 HTTP response codes */ + curl_easy_setopt(curl, CURLOPT_POSTREDIR, CURL_REDIR_POST_ALL); + + curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +This option was known as CURLOPT_POST301 up to 7.19.0 as it only supported the +301 then. CURL_REDIR_POST_303 was added in 7.26.0. +.SH AVAILABILITY +Added in curl 7.19.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_EFFECTIVE_METHOD (3), +.BR CURLINFO_REDIRECT_COUNT (3), +.BR CURLOPT_FOLLOWLOCATION (3), +.BR CURLOPT_MAXREDIRS (3), +.BR CURLOPT_POSTFIELDS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PREQUOTE.3 b/3rdparty/curl/share/man/man3/CURLOPT_PREQUOTE.3 new file mode 100644 index 0000000..d21096b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PREQUOTE.3 @@ -0,0 +1,61 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PREQUOTE.md +.TH CURLOPT_PREQUOTE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PREQUOTE \- commands to run before an FTP transfer +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREQUOTE, + struct curl_slist *cmds); +.fi +.SH DESCRIPTION +Pass a pointer to a linked list of FTP commands to pass to the server after +the transfer type is set. The linked list should be a fully valid list of +struct curl_slist structs properly filled in as described for +\fICURLOPT_QUOTE(3)\fP. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. + +libcurl does not copy the list, it needs to be kept around until after the +transfer has completed. + +These commands are not performed when a directory listing is performed, only +for file transfers. + +While \fICURLOPT_QUOTE(3)\fP and \fICURLOPT_POSTQUOTE(3)\fP work for SFTP, +this option does not. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +int main(void) +{ + struct curl_slist *cmdlist = NULL; + cmdlist = curl_slist_append(cmdlist, "SYST"); + + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); + + /* pass in the FTP commands to run */ + curl_easy_setopt(curl, CURLOPT_PREQUOTE, cmdlist); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } + curl_slist_free_all(cmdlist); +} +.fi +.SH AVAILABILITY +Added in curl 7.9.5 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_POSTQUOTE (3), +.BR CURLOPT_QUOTE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PREREQDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_PREREQDATA.3 new file mode 100644 index 0000000..5d3cd8f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PREREQDATA.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PREREQDATA.md +.TH CURLOPT_PREREQDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PREREQDATA \- pointer passed to the pre\-request callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, void *pointer); +.fi +.SH DESCRIPTION +Pass a \fIpointer\fP that is untouched by libcurl and passed as the first +argument in the pre\-request callback set with \fICURLOPT_PREREQFUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct priv { + void *custom; +}; + +static int prereq_callback(void *clientp, + char *conn_primary_ip, + char *conn_local_ip, + int conn_primary_port, + int conn_local_port) +{ + printf("Connection made to %s:%d\\n", conn_primary_ip, conn_primary_port); + return CURL_PREREQFUNC_OK; +} + +int main(void) +{ + struct priv prereq_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_PREREQFUNCTION, prereq_callback); + curl_easy_setopt(curl, CURLOPT_PREREQDATA, &prereq_data); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.80.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_PRIMARY_IP (3), +.BR CURLINFO_PRIMARY_PORT (3), +.BR CURLOPT_PREREQFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PREREQFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_PREREQFUNCTION.3 new file mode 100644 index 0000000..701454d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PREREQFUNCTION.3 @@ -0,0 +1,94 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PREREQFUNCTION.md +.TH CURLOPT_PREREQFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PREREQFUNCTION \- user callback called when a connection has been +established, but before a request has been made. +.SH SYNOPSIS +.nf +#include + +/* These are the return codes for the pre-request callback. */ +#define CURL_PREREQFUNC_OK 0 +#define CURL_PREREQFUNC_ABORT 1 /* fail the entire transfer */ + +int prereq_callback(void *clientp, + char *conn_primary_ip, + char *conn_local_ip, + int conn_primary_port, + int conn_local_port); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This function gets called by libcurl after a connection has been established +or a connection has been reused (including any SSL handshaking), but before any +request is actually made on the connection. For example, for HTTP, this +callback is called once a connection has been established to the server, but +before a GET/HEAD/POST/etc request has been sent. + +This function may be called multiple times if redirections are enabled and are +being followed (see \fICURLOPT_FOLLOWLOCATION(3)\fP). + +The callback function must return \fICURL_PREREQFUNC_OK\fP on success, or +\fICURL_PREREQFUNC_ABORT\fP to cause the transfer to fail. + +This function is passed the following arguments: +.IP conn_primary_ip +A null\-terminated pointer to a C string containing the primary IP of the +remote server established with this connection. For FTP, this is the IP for +the control connection. IPv6 addresses are represented without surrounding +brackets. +.IP conn_local_ip +A null\-terminated pointer to a C string containing the originating IP for this +connection. IPv6 addresses are represented without surrounding brackets. +.IP conn_primary_port +The primary port number on the remote server established with this connection. +For FTP, this is the port for the control connection. This can be a TCP or a +UDP port number depending on the protocol. +.IP conn_local_port +The originating port number for this connection. This can be a TCP or a UDP +port number depending on the protocol. +.IP clientp +The pointer you set with \fICURLOPT_PREREQDATA(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct priv { + void *custom; +}; + +static int prereq_callback(void *clientp, + char *conn_primary_ip, + char *conn_local_ip, + int conn_primary_port, + int conn_local_port) +{ + printf("Connection made to %s:%d\\n", conn_primary_ip, conn_primary_port); + return CURL_PREREQFUNC_OK; +} + +int main(void) +{ + struct priv prereq_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_PREREQFUNCTION, prereq_callback); + curl_easy_setopt(curl, CURLOPT_PREREQDATA, &prereq_data); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.80.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_PRIMARY_IP (3), +.BR CURLINFO_PRIMARY_PORT (3), +.BR CURLOPT_PREREQDATA (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PRE_PROXY.3 b/3rdparty/curl/share/man/man3/CURLOPT_PRE_PROXY.3 new file mode 100644 index 0000000..072d328 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PRE_PROXY.3 @@ -0,0 +1,66 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PRE_PROXY.md +.TH CURLOPT_PRE_PROXY 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PRE_PROXY \- pre\-proxy host to use +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PRE_PROXY, char *preproxy); +.fi +.SH DESCRIPTION +Set the \fIpreproxy\fP to use for the upcoming request. The parameter should be a +char * to a null\-terminated string holding the hostname or dotted numerical IP +address. A numerical IPv6 address must be written within [brackets]. + +To specify port number in this string, append :[port] to the end of the host +name. The proxy\(aqs port number may optionally be specified with the separate +option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl defaults to using +port 1080 for proxies. + +A pre proxy is a SOCKS proxy that curl connects to before it connects to the +HTTP(S) proxy specified in the \fICURLOPT_PROXY(3)\fP option. The pre proxy +can only be a SOCKS proxy. + +The pre proxy string should be prefixed with [scheme]:// to specify which kind +of socks is used. Use socks4://, socks4a://, socks5:// or socks5h:// (the last +one to enable socks5 and asking the proxy to do the resolving, also known as +\fICURLPROXY_SOCKS5_HOSTNAME\fP type) to request the specific SOCKS version to +be used. Otherwise SOCKS4 is used as default. + +Setting the pre proxy string to "" (an empty string) explicitly disables the +use of a pre proxy. + +When you set a hostname to use, do not assume that there is any particular +single port number used widely for proxies. Specify it. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt"); + curl_easy_setopt(curl, CURLOPT_PRE_PROXY, "socks4://socks-proxy:1080"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_HTTPPROXYTUNNEL (3), +.BR CURLOPT_PROXY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PRIVATE.3 b/3rdparty/curl/share/man/man3/CURLOPT_PRIVATE.3 new file mode 100644 index 0000000..3bce490 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PRIVATE.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PRIVATE.md +.TH CURLOPT_PRIVATE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PRIVATE \- store a private pointer +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PRIVATE, void *pointer); +.fi +.SH DESCRIPTION +Pass a void * as parameter, pointing to data that should be associated with +this curl handle. The pointer can subsequently be retrieved using +\fIcurl_easy_getinfo(3)\fP with the \fICURLINFO_PRIVATE(3)\fP option. libcurl itself +never does anything with this data. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct private { + void *custom; +}; + +int main(void) +{ + CURL *curl = curl_easy_init(); + struct private secrets; + if(curl) { + struct private *extracted; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* store a pointer to our private struct */ + curl_easy_setopt(curl, CURLOPT_PRIVATE, &secrets); + + curl_easy_perform(curl); + + /* we can extract the private pointer again too */ + curl_easy_getinfo(curl, CURLINFO_PRIVATE, &extracted); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_PRIVATE (3), +.BR CURLOPT_STDERR (3), +.BR CURLOPT_VERBOSE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROGRESSDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROGRESSDATA.3 new file mode 100644 index 0000000..0a00769 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROGRESSDATA.3 @@ -0,0 +1,59 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROGRESSDATA.md +.TH CURLOPT_PROGRESSDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROGRESSDATA \- pointer passed to the progress callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSDATA, void *pointer); +.fi +.SH DESCRIPTION +Pass a \fIpointer\fP that is untouched by libcurl and passed as the first +argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct progress { + char *private; + size_t size; +}; + +static size_t progress_callback(void *clientp, + double dltotal, + double dlnow, + double ultotal, + double ulnow) +{ + struct progress *memory = clientp; + printf("private: %p\\n", memory->private); + + /* use the values */ + + return 0; /* all is good */ +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct progress data; + + /* pass struct to callback */ + curl_easy_setopt(curl, CURLOPT_PROGRESSDATA, &data); + curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, progress_callback); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_PROGRESSFUNCTION (3), +.BR CURLOPT_XFERINFOFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROGRESSFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROGRESSFUNCTION.3 new file mode 100644 index 0000000..01ffdba --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROGRESSFUNCTION.3 @@ -0,0 +1,107 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROGRESSFUNCTION.md +.TH CURLOPT_PROGRESSFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROGRESSFUNCTION \- progress meter callback +.SH SYNOPSIS +.nf +#include + +int progress_callback(void *clientp, + double dltotal, + double dlnow, + double ultotal, + double ulnow); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSFUNCTION, + progress_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This option is deprecated and we encourage users to use the +newer \fICURLOPT_XFERINFOFUNCTION(3)\fP instead, if you can. + +This function gets called by libcurl instead of its internal equivalent with a +frequent interval. While data is being transferred it is invoked frequently, +and during slow periods like when nothing is being transferred it can slow +down to about one call per second. + +\fIclientp\fP is the pointer set with \fICURLOPT_PROGRESSDATA(3)\fP, it is not +used by libcurl but is only passed along from the application to the callback. + +The callback gets told how much data libcurl is about to transfer and has +transferred, in number of bytes. \fIdltotal\fP is the total number of bytes +libcurl expects to download in this transfer. \fIdlnow\fP is the number of +bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl +expects to upload in this transfer. \fIulnow\fP is the number of bytes +uploaded so far. + +Unknown/unused argument values passed to the callback are be set to zero (like +if you only download data, the upload size remains 0). Many times the callback +is called one or more times first, before it knows the data sizes so a program +must be made to handle that. + +Return zero from the callback if everything is fine. + +If your callback function returns CURL_PROGRESSFUNC_CONTINUE it causes libcurl +to continue executing the default progress function. + +Return 1 from this callback to make libcurl abort the transfer and return +\fICURLE_ABORTED_BY_CALLBACK\fP. + +If you transfer data with the multi interface, this function is not called +during periods of idleness unless you call the appropriate libcurl function +that performs transfers. + +\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually +get called. +.SH DEFAULT +NULL. libcurl has an internal progress meter. That is rarely wanted by users. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct progress { + char *private; + size_t size; +}; + +static size_t progress_callback(void *clientp, + double dltotal, + double dlnow, + double ultotal, + double ulnow) +{ + struct progress *memory = clientp; + printf("private: %p\\n", memory->private); + + /* use the values */ + + return 0; /* all is good */ +} + +int main(void) +{ + struct progress data; + + CURL *curl = curl_easy_init(); + if(curl) { + /* pass struct to callback */ + curl_easy_setopt(curl, CURLOPT_PROGRESSDATA, &data); + curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, progress_callback); + + curl_easy_perform(curl); + } +} +.fi +.SH DEPRECATED +Deprecated since 7.32.0. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_NOPROGRESS (3), +.BR CURLOPT_VERBOSE (3), +.BR CURLOPT_XFERINFOFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROTOCOLS.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROTOCOLS.3 new file mode 100644 index 0000000..49c01ea --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROTOCOLS.3 @@ -0,0 +1,85 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROTOCOLS.md +.TH CURLOPT_PROTOCOLS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROTOCOLS \- allowed protocols +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS, long bitmask); +.fi +.SH DESCRIPTION +This option is deprecated. We strongly recommend using +\fICURLOPT_PROTOCOLS_STR(3)\fP instead because this option cannot control all +available protocols! + +Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask +limits what protocols libcurl may use in the transfer. This allows you to have +a libcurl built to support a wide range of protocols but still limit specific +transfers to only be allowed to use a subset of them. By default libcurl +accepts all protocols it supports (\fICURLPROTO_ALL\fP). See also +\fICURLOPT_REDIR_PROTOCOLS(3)\fP. + +These are the available protocol defines: +.nf +CURLPROTO_DICT +CURLPROTO_FILE +CURLPROTO_FTP +CURLPROTO_FTPS +CURLPROTO_GOPHER +CURLPROTO_HTTP +CURLPROTO_HTTPS +CURLPROTO_IMAP +CURLPROTO_IMAPS +CURLPROTO_LDAP +CURLPROTO_LDAPS +CURLPROTO_POP3 +CURLPROTO_POP3S +CURLPROTO_RTMP +CURLPROTO_RTMPE +CURLPROTO_RTMPS +CURLPROTO_RTMPT +CURLPROTO_RTMPTE +CURLPROTO_RTMPTS +CURLPROTO_RTSP +CURLPROTO_SCP +CURLPROTO_SFTP +CURLPROTO_SMB +CURLPROTO_SMBS +CURLPROTO_SMTP +CURLPROTO_SMTPS +CURLPROTO_TELNET +CURLPROTO_TFTP +.fi +.SH DEFAULT +All protocols built\-in. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(int argc, char **argv) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* pass in the URL from an external source */ + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + + /* only allow HTTP, TFTP and SFTP */ + curl_easy_setopt(curl, CURLOPT_PROTOCOLS, + CURLPROTO_HTTP | CURLPROTO_TFTP | CURLPROTO_SFTP); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH DEPRECATED +Deprecated since 7.85.0. +.SH AVAILABILITY +Added in curl 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_DEFAULT_PROTOCOL (3), +.BR CURLOPT_REDIR_PROTOCOLS (3), +.BR CURLOPT_URL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROTOCOLS_STR.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROTOCOLS_STR.3 new file mode 100644 index 0000000..18525fb --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROTOCOLS_STR.3 @@ -0,0 +1,70 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROTOCOLS_STR.md +.TH CURLOPT_PROTOCOLS_STR 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROTOCOLS_STR \- allowed protocols +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS_STR, char *spec); +.fi +.SH DESCRIPTION +Pass a pointer to a string that holds a comma\-separated list of case +insensitive protocol names (URL schemes) to allow in the transfer. This +option allows applications to use libcurl built to support a wide range of +protocols but still limit specific transfers to only be allowed to use a +subset of them. By default, libcurl accepts all protocols it was built with +support for. See also \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP. + +If trying to set a non\-existing protocol or if no matching protocol at all is +set, it returns error. + +These are the available protocols: + +DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, +MQTT, POP3, POP3S, RTMP, RTMPE, RTMPS, RTMPT, RTMPTE, RTMPTS, RTSP, SCP, SFTP, +SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS, WSS + +You can set "ALL" as a short\-cut to enable all protocols. Note that by setting +all, you may enable protocols that were not supported the day you write this +but are introduced in a future libcurl version. + +\fIcurl_version_info(3)\fP can be used to get a list of all supported protocols in +the current libcurl. \fICURLINFO_SCHEME(3)\fP is the recommended way to figure out +the protocol used in a previous transfer. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to restore to the internal default. +.SH DEFAULT +All protocols built\-in +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(int argc, char **argv) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* pass in the URL from an external source */ + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + + /* only allow HTTP, TFTP and SFTP */ + curl_easy_setopt(curl, CURLOPT_PROTOCOLS_STR, "http,tftp,sftp"); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.85.0 +.SH RETURN VALUE +Returns CURLE_UNKNOWN_OPTION if the option is not implemented, +CURLE_UNSUPPORTED_PROTOCOL if a listed protocol is not supported or disabled, +CURLE_BAD_FUNCTION_ARGUMENT if no protocol is listed else CURLE_OK. +.SH SEE ALSO +.BR CURLINFO_SCHEME (3), +.BR CURLOPT_DEFAULT_PROTOCOL (3), +.BR CURLOPT_REDIR_PROTOCOLS_STR (3), +.BR CURLOPT_URL (3), +.BR curl_version_info (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY.3 new file mode 100644 index 0000000..8471705 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY.3 @@ -0,0 +1,115 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY.md +.TH CURLOPT_PROXY 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY \- proxy to use +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy); +.fi +.SH DESCRIPTION +Set the \fIproxy\fP to use for transfers with this easy handle. The parameter +should be a char * to a null\-terminated string holding the hostname or dotted +numerical IP address. A numerical IPv6 address must be written within +[brackets]. + +To specify port number in this string, append :[port] to the end of the host +name. The proxy\(aqs port number may optionally (but discouraged) be specified +with the separate option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl +defaults to using port 1080 for proxies. + +The proxy string may be prefixed with [scheme]:// to specify which kind of +proxy is used. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. + +The application does not have to keep the string around after setting this +option. +.IP http:// +HTTP Proxy. Default when no scheme or proxy type is specified. +.IP https:// +HTTPS Proxy. (Added in 7.52.0 for OpenSSL and GnuTLS Since 7.87.0, it +also works for BearSSL, mbedTLS, Rustls, Schannel, Secure Transport and +wolfSSL.) + +This uses HTTP/1 by default. Setting \fICURLOPT_PROXYTYPE(3)\fP to +\fBCURLPROXY_HTTPS2\fP allows libcurl to negotiate using HTTP/2 with proxy. +.IP socks4:// +SOCKS4 Proxy. +.IP socks4a:// +SOCKS4a Proxy. Proxy resolves URL hostname. +.IP socks5:// +SOCKS5 Proxy. +.IP socks5h:// +SOCKS5 Proxy. Proxy resolves URL hostname. +.PP +Without a scheme prefix, \fICURLOPT_PROXYTYPE(3)\fP can be used to specify which +kind of proxy the string identifies. + +When you tell the library to use an HTTP proxy, libcurl transparently converts +operations to HTTP even if you specify an FTP URL etc. This may have an impact +on what other features of the library you can use, such as \fICURLOPT_QUOTE(3)\fP +and similar FTP specifics that do not work unless you tunnel through the HTTP +proxy. Such tunneling is activated with \fICURLOPT_HTTPPROXYTUNNEL(3)\fP. + +Setting the proxy string to "" (an empty string) explicitly disables the use +of a proxy, even if there is an environment variable set for it. + +A proxy host string can also include protocol scheme (http://) and embedded +user + password. + +Unix domain sockets are supported for socks proxies since 7.84.0. Set +localhost for the host part. e.g. socks5h://localhost/path/to/socket.sock + +When you set a hostname to use, do not assume that there is any particular +single port number used widely for proxies. Specify it. + +When a proxy is used, the active FTP mode as set with \fICUROPT_FTPPORT(3)\fP, +cannot be used. +.SH Environment variables +libcurl respects the proxy environment variables named \fBhttp_proxy\fP, +\fBftp_proxy\fP, \fBsftp_proxy\fP etc. If set, libcurl uses the specified proxy +for that URL scheme. For an "FTP://" URL, the \fBftp_proxy\fP is +considered. \fBall_proxy\fP is used if no protocol specific proxy was set. + +If \fBno_proxy\fP (or \fBNO_PROXY\fP) is set, it is the exact equivalent of +setting the \fICURLOPT_NOPROXY(3)\fP option. + +The \fICURLOPT_PROXY(3)\fP and \fICURLOPT_NOPROXY(3)\fP options override environment +variables. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); + curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +Since 7.14.1 the proxy environment variable names can include the protocol +scheme. + +Since 7.21.7 the proxy string supports the socks protocols as "schemes". + +Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return +error. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_HTTPPROXYTUNNEL (3), +.BR CURLOPT_PRE_PROXY (3), +.BR CURLOPT_PROXYPORT (3), +.BR CURLOPT_PROXYTYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXYAUTH.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXYAUTH.3 new file mode 100644 index 0000000..9567266 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXYAUTH.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXYAUTH.md +.TH CURLOPT_PROXYAUTH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXYAUTH \- HTTP proxy authentication methods +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYAUTH, long bitmask); +.fi +.SH DESCRIPTION +Pass a long as parameter, which is set to a bitmask, to tell libcurl which +HTTP authentication method(s) you want it to use for your proxy +authentication. If more than one bit is set, libcurl first queries the site to +see what authentication methods it supports and then it picks the best one you +allow it to use. For some methods, this induces an extra network round\-trip. +Set the actual name and password with the \fICURLOPT_PROXYUSERPWD(3)\fP +option. + +The bitmask can be constructed by the bits listed and described in the +\fICURLOPT_HTTPAUTH(3)\fP man page. +.SH DEFAULT +CURLAUTH_BASIC +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* use this proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "http://local.example.com:1080"); + /* allow whatever auth the proxy speaks */ + curl_easy_setopt(curl, CURLOPT_PROXYAUTH, CURLAUTH_ANY); + /* set the proxy credentials */ + curl_easy_setopt(curl, CURLOPT_PROXYUSERPWD, "james:007"); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.7 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication +methods. +.SH SEE ALSO +.BR CURLOPT_HTTPAUTH (3), +.BR CURLOPT_PROXY (3), +.BR CURLOPT_PROXYPORT (3), +.BR CURLOPT_PROXYTYPE (3), +.BR CURLOPT_PROXYUSERPWD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXYHEADER.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXYHEADER.3 new file mode 100644 index 0000000..6f98375 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXYHEADER.3 @@ -0,0 +1,63 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXYHEADER.md +.TH CURLOPT_PROXYHEADER 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXYHEADER \- set of HTTP headers to pass to proxy +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYHEADER, + struct curl_slist *headers); +.fi +.SH DESCRIPTION +Pass a pointer to a linked list of HTTP headers to pass in your HTTP request +sent to a proxy. The rules for this list is identical to the +\fICURLOPT_HTTPHEADER(3)\fP option\(aqs. + +The headers set with this option is only ever used in requests sent to a proxy +- when there is also a request sent to a host. + +The first line in a request (containing the method, usually a GET or POST) is +NOT a header and cannot be replaced using this option. Only the lines +following the request\-line are headers. Adding this method line in this list +of headers causes your request to send an invalid header. + +Using this option multiple times makes the last set list override the previous +ones. Set it to NULL to disable its use again. + +libcurl does not copy the list, it needs to be kept around until after the +transfer has completed. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + + struct curl_slist *list; + + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy.example.com:80"); + + list = curl_slist_append(NULL, "Shoesize: 10"); + list = curl_slist_append(list, "Accept:"); + + curl_easy_setopt(curl, CURLOPT_PROXYHEADER, list); + + curl_easy_perform(curl); + + curl_slist_free_all(list); /* free the list again */ + } +} +.fi +.SH AVAILABILITY +Added in curl 7.37.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HEADEROPT (3), +.BR CURLOPT_HTTPHEADER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXYPASSWORD.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXYPASSWORD.3 new file mode 100644 index 0000000..c4091e5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXYPASSWORD.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXYPASSWORD.md +.TH CURLOPT_PROXYPASSWORD 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXYPASSWORD \- password to use with proxy authentication +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYPASSWORD, char *pwd); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should be pointing to the +null\-terminated password to use for authentication with the proxy. + +The \fICURLOPT_PROXYPASSWORD(3)\fP option should be used in conjunction with the +\fICURLOPT_PROXYUSERNAME(3)\fP option. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +blank +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); + curl_easy_setopt(curl, CURLOPT_PROXYUSERNAME, "mrsmith"); + curl_easy_setopt(curl, CURLOPT_PROXYPASSWORD, "qwerty"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_HTTPAUTH (3), +.BR CURLOPT_PASSWORD (3), +.BR CURLOPT_PROXYAUTH (3), +.BR CURLOPT_PROXYUSERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXYPORT.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXYPORT.3 new file mode 100644 index 0000000..6b24839 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXYPORT.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXYPORT.md +.TH CURLOPT_PROXYPORT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXYPORT \- port number the proxy listens on +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYPORT, long port); +.fi +.SH DESCRIPTION +We discourage use of this option. + +Pass a long with this option to set the proxy port to connect to unless it is +specified in the proxy string \fICURLOPT_PROXY(3)\fP or uses 443 for https proxies +and 1080 for all others as default. + +Disabling this option, setting it to zero, makes it not specified which makes +libcurl use the default proxy port number or the port number specified in the +proxy URL string. + +While this accepts a \(aqlong\(aq, the port number is 16 bit so it cannot be larger +than 65535. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PROXY, "localhost"); + curl_easy_setopt(curl, CURLOPT_PROXYPORT, 8080L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLINFO_PRIMARY_PORT (3), +.BR CURLOPT_PORT (3), +.BR CURLOPT_PROXY (3), +.BR CURLOPT_PROXYTYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXYTYPE.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXYTYPE.3 new file mode 100644 index 0000000..de43c0e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXYTYPE.3 @@ -0,0 +1,62 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXYTYPE.md +.TH CURLOPT_PROXYTYPE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXYTYPE \- proxy protocol type +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYTYPE, long type); +.fi +.SH DESCRIPTION +Pass one of the values below to set the type of the proxy. +.IP CURLPROXY_HTTP +HTTP Proxy. Default. +.IP CURLPROXY_HTTPS +HTTPS Proxy using HTTP/1. (Added in 7.52.0 for OpenSSL and GnuTLS. Since +7.87.0, it also works for BearSSL, mbedTLS, Rustls, Schannel, Secure Transport +and wolfSSL.) +.IP CURLPROXY_HTTPS2 +HTTPS Proxy and attempt to speak HTTP/2 over it. (Added in 8.1.0) +.IP CURLPROXY_HTTP_1_0 +HTTP 1.0 Proxy. This is similar to CURLPROXY_HTTP except it uses HTTP/1.0 for +any CONNECT tunneling. It does not change the HTTP version of the actual HTTP +requests, controlled by \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURLPROXY_SOCKS4 +SOCKS4 Proxy. +.IP CURLPROXY_SOCKS4A +SOCKS4a Proxy. Proxy resolves URL hostname. +.IP CURLPROXY_SOCKS5 +SOCKS5 Proxy. +.IP CURLPROXY_SOCKS5_HOSTNAME +SOCKS5 Proxy. Proxy resolves URL hostname. +.PP +Often it is more convenient to specify the proxy type with the scheme part of +the \fICURLOPT_PROXY(3)\fP string. +.SH DEFAULT +CURLPROXY_HTTP +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "local.example.com:1080"); + /* set the proxy type */ + curl_easy_setopt(curl, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_PROXY (3), +.BR CURLOPT_PROXYPORT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXYUSERNAME.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXYUSERNAME.3 new file mode 100644 index 0000000..ad2d63d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXYUSERNAME.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXYUSERNAME.md +.TH CURLOPT_PROXYUSERNAME 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXYUSERNAME \- username to use for proxy authentication +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERNAME, + char *username); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should be pointing to the +null\-terminated username to use for the transfer. + +\fICURLOPT_PROXYUSERNAME(3)\fP sets the username to be used in protocol +authentication with the proxy. + +To specify the proxy password use the \fICURLOPT_PROXYPASSWORD(3)\fP. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +blank +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); + curl_easy_setopt(curl, CURLOPT_PROXYUSERNAME, "mrsmith"); + curl_easy_setopt(curl, CURLOPT_PROXYPASSWORD, "qwerty"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_HTTPAUTH (3), +.BR CURLOPT_PROXYAUTH (3), +.BR CURLOPT_PROXYPASSWORD (3), +.BR CURLOPT_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXYUSERPWD.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXYUSERPWD.3 new file mode 100644 index 0000000..5a51540 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXYUSERPWD.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXYUSERPWD.md +.TH CURLOPT_PROXYUSERPWD 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXYUSERPWD \- username and password to use for proxy authentication +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERPWD, char *userpwd); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should be [username]:[password] to use +for the connection to the HTTP proxy. Both the name and the password are URL +decoded before used, so to include for example a colon in the username you +should encode it as %3A. (This is different to how \fICURLOPT_USERPWD(3)\fP is +used \- beware.) + +Use \fICURLOPT_PROXYAUTH(3)\fP to specify the authentication method. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); + curl_easy_setopt(curl, CURLOPT_PROXYUSERPWD, "clark%20kent:superman"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY (3), +.BR CURLOPT_PROXYPASSWORD (3), +.BR CURLOPT_PROXYTYPE (3), +.BR CURLOPT_PROXYUSERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CAINFO.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CAINFO.3 new file mode 100644 index 0000000..97d44b1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CAINFO.3 @@ -0,0 +1,78 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_CAINFO.md +.TH CURLOPT_PROXY_CAINFO 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_CAINFO \- path to proxy Certificate Authority (CA) bundle +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAINFO, char *path); +.fi +.SH DESCRIPTION +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a char pointer to a null\-terminated string naming a file holding one or +more certificates to verify the HTTPS proxy with. + +If \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the +server\(aqs certificate, \fICURLOPT_PROXY_CAINFO(3)\fP need not even indicate an +accessible file. + +This option is by default set to the system path where libcurl\(aqs CA +certificate bundle is assumed to be stored, as established at build time. + +(iOS and macOS only) If curl is built against Secure Transport, then this +option is supported for backward compatibility with other SSL engines, but it +should not be set. If the option is not set, then curl uses the certificates +in the system and user Keychain to verify the peer, which is the preferred +method of verifying the peer\(aqs certificate chain. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again and switches back to +internal default. + +The default value for this can be figured out with \fICURLINFO_CAINFO(3)\fP. +.SH DEFAULT +Built\-in system specific +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* using an HTTPS proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); + curl_easy_setopt(curl, CURLOPT_PROXY_CAINFO, "/etc/certs/cabundle.pem"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH NOTES +For TLS backends that do not support certificate files, the +\fICURLOPT_PROXY_CAINFO(3)\fP option is ignored. Refer to +https://curl.se/docs/ssl\-compared.html +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_CAINFO_BLOB (3), +.BR CURLOPT_CAPATH (3), +.BR CURLOPT_PROXY_CAINFO_BLOB (3), +.BR CURLOPT_PROXY_CAPATH (3), +.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), +.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CAINFO_BLOB.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CAINFO_BLOB.3 new file mode 100644 index 0000000..7569984 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CAINFO_BLOB.3 @@ -0,0 +1,71 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_CAINFO_BLOB.md +.TH CURLOPT_PROXY_CAINFO_BLOB 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_CAINFO_BLOB \- proxy Certificate Authority (CA) bundle in PEM format +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAINFO_BLOB, + struct curl_blob *stblob); +.fi +.SH DESCRIPTION +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a pointer to a curl_blob structure, which contains information (pointer +and size) about a memory block with binary data of PEM encoded content holding +one or more certificates to verify the HTTPS proxy with. + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. + +If \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the +server\(aqs certificate, \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP is not needed. + +This option overrides \fICURLOPT_PROXY_CAINFO(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL, Schannel, Secure Transport and rustls +.SH EXAMPLE +.nf +#include /* for strlen */ + +extern char *strpem; /* strpem must point to a PEM string */ +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob blob; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* using an HTTPS proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); + blob.data = strpem; + blob.len = strlen(strpem); + blob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_PROXY_CAINFO_BLOB, &blob); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.77.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_CAINFO_BLOB (3), +.BR CURLOPT_CAPATH (3), +.BR CURLOPT_PROXY_CAINFO (3), +.BR CURLOPT_PROXY_CAPATH (3), +.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), +.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CAPATH.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CAPATH.3 new file mode 100644 index 0000000..924578c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CAPATH.3 @@ -0,0 +1,64 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_CAPATH.md +.TH CURLOPT_PROXY_CAPATH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_CAPATH \- directory holding HTTPS proxy CA certificates +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAPATH, char *capath); +.fi +.SH DESCRIPTION +Pass a char pointer to a null\-terminated string naming a directory holding +multiple CA certificates to verify the HTTPS proxy with. If libcurl is built +against OpenSSL, the certificate directory must be prepared using the OpenSSL +\fBc_rehash\fP utility. This makes sense only when +\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is enabled (which it is by default). + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again and switch back to +internal default. + +The default value for this can be figured out with \fICURLINFO_CAPATH(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL and mbedTLS +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* using an HTTPS proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); + curl_easy_setopt(curl, CURLOPT_PROXY_CAPATH, "/etc/cert-dir"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +CURLE_OK if supported; or an error such as: + +CURLE_NOT_BUILT_IN \- Not supported by the SSL backend + +CURLE_UNKNOWN_OPTION + +CURLE_OUT_OF_MEMORY +.SH SEE ALSO +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_PROXY_CAINFO (3), +.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), +.BR CURLOPT_STDERR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CRLFILE.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CRLFILE.3 new file mode 100644 index 0000000..35d7bbf --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_CRLFILE.3 @@ -0,0 +1,68 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_CRLFILE.md +.TH CURLOPT_PROXY_CRLFILE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_CRLFILE \- HTTPS proxy Certificate Revocation List file +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CRLFILE, char *file); +.fi +.SH DESCRIPTION +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a char pointer to a null\-terminated string naming a \fIfile\fP with the +concatenation of CRL (in PEM format) to use in the certificate validation that +occurs during the SSL exchange. + +When curl is built to use GnuTLS, there is no way to influence the use of CRL +passed to help in the verification process. When libcurl is built with OpenSSL +support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, +requiring CRL check against all the elements of the certificate chain if a CRL +file is passed. + +This option makes sense only when used in combination with the +\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. + +A specific error code (\fICURLE_SSL_CRL_BADFILE\fP) is defined with the option. It +is returned when the SSL exchange fails because the CRL file cannot be loaded. +A failure in certificate verification due to a revocation information found in +the CRL does not trigger this specific error. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL and mbedTLS +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:80"); + curl_easy_setopt(curl, CURLOPT_PROXY_CRLFILE, "/etc/certs/crl.pem"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), +.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_ISSUERCERT.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_ISSUERCERT.3 new file mode 100644 index 0000000..415a063 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_ISSUERCERT.3 @@ -0,0 +1,66 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_ISSUERCERT.md +.TH CURLOPT_PROXY_ISSUERCERT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_ISSUERCERT \- proxy issuer SSL certificate filename +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_ISSUERCERT, char *file); +.fi +.SH DESCRIPTION +Pass a char pointer to a null\-terminated string naming a \fIfile\fP holding a CA +certificate in PEM format. If the option is set, an additional check against +the peer certificate is performed to verify the issuer of the HTTPS proxy is +indeed the one associated with the certificate provided by the option. This +additional check is useful in multi\-level PKI where one needs to enforce that +the peer certificate is from a specific branch of the tree. + +This option makes sense only when used in combination with the +\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is +not considered as failure. + +A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, +which is returned if the setup of the SSL/TLS session has failed due to a +mismatch with the issuer of peer certificate (\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP +has to be set too for the check to fail). + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* using an HTTPS proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); + curl_easy_setopt(curl, CURLOPT_PROXY_ISSUERCERT, "/etc/certs/cacert.pem"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.71.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_ISSUERCERT (3), +.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), +.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_ISSUERCERT_BLOB.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_ISSUERCERT_BLOB.3 new file mode 100644 index 0000000..65d1ef6 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_ISSUERCERT_BLOB.3 @@ -0,0 +1,77 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_ISSUERCERT_BLOB.md +.TH CURLOPT_PROXY_ISSUERCERT_BLOB 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_ISSUERCERT_BLOB \- proxy issuer SSL certificate from memory blob +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_ISSUERCERT_BLOB, + struct curl_blob *blob); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_blob struct, which contains information (pointer and +size) about a memory block with binary data of a CA certificate in PEM +format. If the option is set, an additional check against the peer certificate +is performed to verify the issuer of the HTTPS proxy is indeed the one +associated with the certificate provided by the option. This additional check +is useful in multi\-level PKI where one needs to enforce that the peer +certificate is from a specific branch of the tree. + +This option should be used in combination with the +\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the +check is not considered as failure. + +A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, +which is returned if the setup of the SSL/TLS session has failed due to a +mismatch with the issuer of peer certificate +(\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP has to be set too for the check to fail). + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. + +This option is an alternative to \fICURLOPT_PROXY_ISSUERCERT(3)\fP which +instead expects a filename as input. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL +.SH EXAMPLE +.nf + +extern char *certificateData; /* point to the data */ +size_t filesize; /* size of the data */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob blob; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* using an HTTPS proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); + blob.data = certificateData; + blob.len = filesize; + blob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_PROXY_ISSUERCERT_BLOB, &blob); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.71.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_ISSUERCERT_BLOB (3), +.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), +.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_KEYPASSWD.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_KEYPASSWD.3 new file mode 100644 index 0000000..ec7ad85 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_KEYPASSWD.3 @@ -0,0 +1,55 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_KEYPASSWD.md +.TH CURLOPT_PROXY_KEYPASSWD 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_KEYPASSWD \- passphrase for the proxy private key +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_KEYPASSWD, char *pwd); +.fi +.SH DESCRIPTION +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a pointer to a null\-terminated string as parameter. It is used as the +password required to use the \fICURLOPT_PROXY_SSLKEY(3)\fP private key. You never +need a passphrase to load a certificate but you need one to load your private +key. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL, Schannel, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "superman"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_KEYPASSWD (3), +.BR CURLOPT_PROXY_SSLKEY (3), +.BR CURLOPT_SSH_PRIVATE_KEYFILE (3), +.BR CURLOPT_SSLKEY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_PINNEDPUBLICKEY.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_PINNEDPUBLICKEY.3 new file mode 100644 index 0000000..8fcf426 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_PINNEDPUBLICKEY.3 @@ -0,0 +1,109 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_PINNEDPUBLICKEY.md +.TH CURLOPT_PROXY_PINNEDPUBLICKEY 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_PINNEDPUBLICKEY \- pinned public key for https proxy +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_PINNEDPUBLICKEY, + char *pinnedpubkey); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. The string can be the +filename of your pinned public key. The file format expected is "PEM" or +\&"DER". The string can also be any number of base64 encoded sha256 hashes +preceded by "sha256//" and separated by ";" + +When negotiating a TLS or SSL connection, the https proxy sends a certificate +indicating its identity. A public key is extracted from this certificate and +if it does not exactly match the public key provided to this option, libcurl +aborts the connection before sending or receiving any data. + +On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443"); + curl_easy_setopt(curl, CURLOPT_PROXY_PINNEDPUBLICKEY, + "sha256//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjA" + "a3HWY3tvRMwE=;sha256//t62CeU2tQiqkexU74" + "Gxa2eg7fRbEgoChTociMee9wno="); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH PUBLIC KEY EXTRACTION +If you do not have the https proxy server\(aqs public key file you can extract it +from the https proxy server\(aqs certificate. +.nf +# retrieve the server's certificate if you do not already have it +# +# be sure to examine the certificate to see if it is what you expected +# +# Windows-specific: +# - Use NUL instead of /dev/null. +# - OpenSSL may wait for input instead of disconnecting. Hit enter. +# - If you do not have sed, then just copy the certificate into a file: +# Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----. +# +openssl s_client -servername www.example.com -connect www.example.com:443 \\ + < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem + +# extract public key in pem format from certificate +openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem + +# convert public key from pem to der +openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem \\ + -out www.example.com.pubkey.der + +# sha256 hash and base64 encode der to string for use +openssl dgst -sha256 -binary www.example.com.pubkey.der | openssl base64 +.fi +The public key in PEM format contains a header, base64 data and a +footer: +.nf +-----BEGIN PUBLIC KEY----- +[BASE 64 DATA] +-----END PUBLIC KEY----- +.fi +.SH HISTORY +PEM/DER support: + + 7.52.0: GnuTLS, OpenSSL, mbedTLS, wolfSSL + +sha256 support: + + 7.52.0: GnuTLS, OpenSSL, mbedTLS, wolfSSL + +Other SSL backends not supported. +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PINNEDPUBLICKEY (3), +.BR CURLOPT_PROXY_CAINFO (3), +.BR CURLOPT_PROXY_CAPATH (3), +.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), +.BR CURLOPT_PROXY_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SERVICE_NAME.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SERVICE_NAME.3 new file mode 100644 index 0000000..1ac202d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SERVICE_NAME.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SERVICE_NAME.md +.TH CURLOPT_PROXY_SERVICE_NAME 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SERVICE_NAME \- proxy authentication service name +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SERVICE_NAME, + char *name); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter to a string holding the \fIname\fP of the +service. The default service name is \fB"HTTP"\fP for HTTP based proxies and +\fB"rcmd"\fP for SOCKS5. This option allows you to change it. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +See above +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY_SERVICE_NAME, "custom"); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.43.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY (3), +.BR CURLOPT_PROXYTYPE (3), +.BR CURLOPT_SERVICE_NAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLCERT.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLCERT.3 new file mode 100644 index 0000000..fa778ea --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLCERT.3 @@ -0,0 +1,64 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLCERT.md +.TH CURLOPT_PROXY_SSLCERT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SSLCERT \- HTTPS proxy client certificate +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERT, char *cert); +.fi +.SH DESCRIPTION +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a pointer to a null\-terminated string as parameter. The string should be +the filename of your client certificate used to connect to the HTTPS proxy. +The default format is "P12" on Secure Transport and "PEM" on other engines, +and can be changed with \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP. + +With Secure Transport, this can also be the nickname of the certificate you +wish to authenticate with as it is named in the security database. If you want +to use a file from the current directory, please precede it with "./" prefix, +in order to avoid confusion with a nickname. + +When using a client certificate, you most likely also need to provide a +private key with \fICURLOPT_PROXY_SSLKEY(3)\fP. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSLCERTTYPE (3), +.BR CURLOPT_PROXY_SSLKEY (3), +.BR CURLOPT_SSLCERT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLCERTTYPE.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLCERTTYPE.3 new file mode 100644 index 0000000..953dabc --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLCERTTYPE.3 @@ -0,0 +1,58 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLCERTTYPE.md +.TH CURLOPT_PROXY_SSLCERTTYPE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SSLCERTTYPE \- type of the proxy client SSL certificate +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERTTYPE, char *type); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. The string should be +the format of your client certificate used when connecting to an HTTPS proxy. + +Supported formats are "PEM" and "DER", except with Secure Transport or +Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or +later, or macOS 10.7 or later) and Schannel support "P12" for PKCS#12\-encoded +files. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +\&"PEM" +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERTTYPE, "PEM"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSLCERT (3), +.BR CURLOPT_PROXY_SSLKEY (3), +.BR CURLOPT_SSLCERTTYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLCERT_BLOB.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLCERT_BLOB.3 new file mode 100644 index 0000000..272a772 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLCERT_BLOB.3 @@ -0,0 +1,66 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLCERT_BLOB.md +.TH CURLOPT_PROXY_SSLCERT_BLOB 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SSLCERT_BLOB \- SSL proxy client certificate from memory blob +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERT_BLOB, + struct curl_blob *blob); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_blob structure, which contains information (pointer +and size) about a memory block with binary data of the certificate used to +connect to the HTTPS proxy. The format must be "P12" on Secure Transport or +Schannel. The format must be "P12" or "PEM" on OpenSSL. The string "P12" or +\&"PEM" must be specified with \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP. + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. + +This option is an alternative to \fICURLOPT_PROXY_SSLCERT(3)\fP which instead +expects a filename as input. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL, Schannel and Secure Transport +.SH EXAMPLE +.nf + +extern char *certificateData; /* point to data */ +extern size_t filesize; /* size of the data */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob blob; + blob.data = certificateData; + blob.len = filesize; + blob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT_BLOB, &blob); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.71.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSLCERT (3), +.BR CURLOPT_PROXY_SSLCERTTYPE (3), +.BR CURLOPT_PROXY_SSLKEY (3), +.BR CURLOPT_SSLCERT_BLOB (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLKEY.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLKEY.3 new file mode 100644 index 0000000..9fac6c5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLKEY.3 @@ -0,0 +1,60 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLKEY.md +.TH CURLOPT_PROXY_SSLKEY 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SSLKEY \- private key file for HTTPS proxy client cert +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEY, char *keyfile); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. The string should be +the filename of your private key used for connecting to the HTTPS proxy. The +default format is "PEM" and can be changed with +\fICURLOPT_PROXY_SSLKEYTYPE(3)\fP. + +(Windows, iOS and macOS) This option is ignored by Secure Transport and +Schannel SSL backends because they expect the private key to be already +present in the key chain or PKCS#12 file containing the certificate. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL, Schannel, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSLCERT (3), +.BR CURLOPT_PROXY_SSLKEYTYPE (3), +.BR CURLOPT_SSLCERT (3), +.BR CURLOPT_SSLKEY (3), +.BR CURLOPT_SSLKEYTYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLKEYTYPE.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLKEYTYPE.3 new file mode 100644 index 0000000..c95001d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLKEYTYPE.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLKEYTYPE.md +.TH CURLOPT_PROXY_SSLKEYTYPE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SSLKEYTYPE \- type of the proxy private key file +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEYTYPE, char *type); +.fi +.SH DESCRIPTION +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a pointer to a null\-terminated string as parameter. The string should be +the format of your private key. Supported formats are "PEM", "DER" and "ENG". + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +BearSSL, OpenSSL and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEYTYPE, "PEM"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSLCERT (3), +.BR CURLOPT_PROXY_SSLKEY (3), +.BR CURLOPT_SSLKEYTYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLKEY_BLOB.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLKEY_BLOB.3 new file mode 100644 index 0000000..512fd30 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLKEY_BLOB.3 @@ -0,0 +1,68 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLKEY_BLOB.md +.TH CURLOPT_PROXY_SSLKEY_BLOB 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SSLKEY_BLOB \- private key for proxy cert from memory blob +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEY_BLOB, + struct curl_blob *blob); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_blob structure that contains information (pointer and +size) about the private key for connecting to the HTTPS proxy. Compatible with +OpenSSL. The format (like "PEM") must be specified with +\fICURLOPT_PROXY_SSLKEYTYPE(3)\fP. + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL +.SH EXAMPLE +.nf + +extern char *certificateData; /* point to data */ +extern size_t filesize; /* size of data */ + +extern char *privateKeyData; /* point to data */ +extern size_t privateKeySize; /* size */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob blob; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + blob.data = certificateData; + blob.len = filesize; + blob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT_BLOB, &blob); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERTTYPE, "PEM"); + + blob.data = privateKeyData; + blob.len = privateKeySize; + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY_BLOB, &blob); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.71.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_SSLKEY (3), +.BR CURLOPT_SSLKEYTYPE (3), +.BR CURLOPT_SSLKEY_BLOB (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLVERSION.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLVERSION.3 new file mode 100644 index 0000000..00d98fb --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSLVERSION.3 @@ -0,0 +1,85 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLVERSION.md +.TH CURLOPT_PROXY_SSLVERSION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SSLVERSION \- preferred HTTPS proxy TLS version +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLVERSION, + long version); +.fi +.SH DESCRIPTION +Pass a long as parameter to control which version of SSL/TLS to attempt to use +when connecting to an HTTPS proxy. + +Use one of the available defines for this purpose. The available options are: +.IP CURL_SSLVERSION_DEFAULT +The default action. This attempts to figure out the remote SSL protocol +version. +.IP CURL_SSLVERSION_TLSv1 +TLSv1.x +.IP CURL_SSLVERSION_TLSv1_0 +TLSv1.0 +.IP CURL_SSLVERSION_TLSv1_1 +TLSv1.1 +.IP CURL_SSLVERSION_TLSv1_2 +TLSv1.2 +.IP CURL_SSLVERSION_TLSv1_3 +TLSv1.3 +.PP +The maximum TLS version can be set by using \fIone\fP of the CURL_SSLVERSION_MAX_ +macros below. It is also possible to OR \fIone\fP of the CURL_SSLVERSION_ macros +with \fIone\fP of the CURL_SSLVERSION_MAX_ macros. The MAX macros are not +supported for wolfSSL. +.IP CURL_SSLVERSION_MAX_DEFAULT +The flag defines the maximum supported TLS version as TLSv1.2, or the default +value from the SSL library. +(Added in 7.54.0) +.IP CURL_SSLVERSION_MAX_TLSv1_0 +The flag defines maximum supported TLS version as TLSv1.0. +(Added in 7.54.0) +.IP CURL_SSLVERSION_MAX_TLSv1_1 +The flag defines maximum supported TLS version as TLSv1.1. +(Added in 7.54.0) +.IP CURL_SSLVERSION_MAX_TLSv1_2 +The flag defines maximum supported TLS version as TLSv1.2. +(Added in 7.54.0) +.IP CURL_SSLVERSION_MAX_TLSv1_3 +The flag defines maximum supported TLS version as TLSv1.3. +(Added in 7.54.0) +.PP +In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were +documented to allow \fIonly\fP the specified TLS version, but behavior was +inconsistent depending on the TLS library. +.SH DEFAULT +CURL_SSLVERSION_DEFAULT +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* ask libcurl to use TLS version 1.0 or later */ + curl_easy_setopt(curl, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTP_VERSION (3), +.BR CURLOPT_IPRESOLVE (3), +.BR CURLOPT_SSLVERSION (3), +.BR CURLOPT_USE_SSL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_CIPHER_LIST.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_CIPHER_LIST.3 new file mode 100644 index 0000000..ae4d79c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_CIPHER_LIST.3 @@ -0,0 +1,78 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSL_CIPHER_LIST.md +.TH CURLOPT_PROXY_SSL_CIPHER_LIST 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SSL_CIPHER_LIST \- ciphers to use for HTTPS proxy +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_CIPHER_LIST, + char *list); +.fi +.SH DESCRIPTION +Pass a char pointer, pointing to a null\-terminated string holding the list of +cipher suites to use for the TLS 1.2 (1.1, 1.0) connection to the HTTPS proxy. +The list must be syntactically correct, it consists of one or more cipher suite +strings separated by colons. + +For setting TLS 1.3 ciphers see \fICURLOPT_PROXY_TLS13_CIPHERS(3)\fP. + +A valid example of a cipher list is: +.nf +"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:" +"ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305" +.fi + +For Schannel, you can use this option to set algorithms but not specific +cipher suites. Refer to the ciphers lists document for algorithms. + +Find more details about cipher lists on this URL: + + https://curl.se/docs/ssl\-ciphers.html + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL, use internal built\-in list. +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +BearSSL, OpenSSL, Schannel, Secure Transport, mbedTLS, rustls and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSL_CIPHER_LIST, + "ECDHE-ECDSA-CHACHA20-POLY1305:" + "ECDHE-RSA-CHACHA20-POLY1305"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +OpenSSL support added in 7.52.0. +wolfSSL, Schannel, Secure Transport, and BearSSL support added in 7.87.0 +mbedTLS support added in 8.8.0. +Rustls support added in 8.10.0. + +Since curl 8.10.0 returns CURLE_NOT_BUILT_IN when not supported. +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSLVERSION (3), +.BR CURLOPT_PROXY_TLS13_CIPHERS (3), +.BR CURLOPT_SSLVERSION (3), +.BR CURLOPT_SSL_CIPHER_LIST (3), +.BR CURLOPT_TLS13_CIPHERS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_OPTIONS.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_OPTIONS.3 new file mode 100644 index 0000000..6f24276 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_OPTIONS.3 @@ -0,0 +1,88 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSL_OPTIONS.md +.TH CURLOPT_PROXY_SSL_OPTIONS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SSL_OPTIONS \- HTTPS proxy SSL behavior options +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_OPTIONS, + long bitmask); +.fi +.SH DESCRIPTION +Pass a long with a bitmask to tell libcurl about specific SSL +behaviors. Available bits: +.IP CURLSSLOPT_ALLOW_BEAST +Tells libcurl to not attempt to use any workarounds for a security flaw in the +SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0, +the SSL layer libcurl uses may use a work\-around for this flaw although it +might cause interoperability problems with some (older) SSL implementations. +WARNING: avoiding this work\-around lessens the security, and by setting this +option to 1 you ask for exactly that. This option is only supported for Secure +Transport and OpenSSL. +.IP CURLSSLOPT_NO_REVOKE +Tells libcurl to disable certificate revocation checks for those SSL backends +where such behavior is present. This option is only supported for Schannel +(the native Windows SSL library), with an exception in the case of Windows\(aq +Untrusted Publishers block list which it seems cannot be bypassed. (Added in +7.44.0) +.IP CURLSSLOPT_NO_PARTIALCHAIN +Tells libcurl to not accept "partial" certificate chains, which it otherwise +does by default. This option is only supported for OpenSSL and fails the +certificate verification if the chain ends with an intermediate certificate +and not with a root cert. (Added in 7.68.0) +.IP CURLSSLOPT_REVOKE_BEST_EFFORT +Tells libcurl to ignore certificate revocation checks in case of missing or +offline distribution points for those SSL backends where such behavior is +present. This option is only supported for Schannel (the native Windows SSL +library). If combined with \fICURLSSLOPT_NO_REVOKE\fP, the latter takes +precedence. (Added in 7.70.0) +.IP CURLSSLOPT_NATIVE_CA +Tell libcurl to use the operating system\(aqs native CA store for certificate +verification. If you set this option and also set a CA certificate file or +directory then during verification those certificates are searched in addition +to the native CA store. + +Works with wolfSSL on Windows, Linux (Debian, Ubuntu, Gentoo, Fedora, RHEL), +macOS, Android and iOS (added in 8.3.0), with GnuTLS (added in 8.5.0) or on +Windows when built to use OpenSSL (Added in 7.71.0). +.IP CURLSSLOPT_AUTO_CLIENT_CERT +Tell libcurl to automatically locate and use a client certificate for +authentication, when requested by the server. This option is only supported +for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the +default behavior in libcurl with Schannel. Since the server can request any +certificate that supports client authentication in the OS certificate store it +could be a privacy violation and unexpected. +(Added in 7.77.0) +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + /* weaken TLS only for use with silly proxies */ + curl_easy_setopt(curl, CURLOPT_PROXY_SSL_OPTIONS, CURLSSLOPT_ALLOW_BEAST | + CURLSSLOPT_NO_REVOKE); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSLVERSION (3), +.BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), +.BR CURLOPT_SSLVERSION (3), +.BR CURLOPT_SSL_CIPHER_LIST (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_VERIFYHOST.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_VERIFYHOST.3 new file mode 100644 index 0000000..08b9f54 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_VERIFYHOST.3 @@ -0,0 +1,73 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSL_VERIFYHOST.md +.TH CURLOPT_PROXY_SSL_VERIFYHOST 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SSL_VERIFYHOST \- verify the proxy certificate\(aqs name against host +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_VERIFYHOST, + long verify); +.fi +.SH DESCRIPTION +Pass a long set to 2L as asking curl to \fIverify\fP in the HTTPS proxy\(aqs +certificate name fields against the proxy name. + +This option determines whether libcurl verifies that the proxy cert contains +the correct name for the name it is known as. + +When \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP is 2, the proxy certificate must +indicate that the server is the proxy to which you meant to connect to, or the +connection fails. + +Curl considers the proxy the intended one when the Common Name field or a +Subject Alternate Name field in the certificate matches the hostname in the +proxy string which you told curl to use. + +If \fIverify\fP value is set to 1: + +In 7.28.0 and earlier: treated as a debug option of some sorts, not supported +anymore due to frequently leading to programmer mistakes. + +From 7.28.1 to 7.65.3: setting it to 1 made \fIcurl_easy_setopt(3)\fP return +an error and leaving the flag untouched. + +From 7.66.0: treats 1 and 2 the same. + +When the \fIverify\fP value is 0L, the connection succeeds regardless of the +names used in the certificate. Use that ability with caution! + +See also \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP to verify the digital signature +of the proxy certificate. +.SH DEFAULT +2 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the default value: strict name check please */ + curl_easy_setopt(curl, CURLOPT_PROXY_SSL_VERIFYHOST, 2L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not. + +If 1 is set as argument, \fICURLE_BAD_FUNCTION_ARGUMENT\fP is returned. +.SH SEE ALSO +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_PROXY_CAINFO (3), +.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_VERIFYPEER.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_VERIFYPEER.3 new file mode 100644 index 0000000..4c604a8 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_SSL_VERIFYPEER.3 @@ -0,0 +1,73 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSL_VERIFYPEER.md +.TH CURLOPT_PROXY_SSL_VERIFYPEER 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_SSL_VERIFYPEER \- verify the proxy\(aqs SSL certificate +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_VERIFYPEER, + long verify); +.fi +.SH DESCRIPTION +Pass a long as parameter set to 1L to enable or 0L to disable. + +This option tells curl to verify the authenticity of the HTTPS proxy\(aqs +certificate. A value of 1 means curl verifies; 0 (zero) means it does not. + +This is the proxy version of \fICURLOPT_SSL_VERIFYPEER(3)\fP that is used for +ordinary HTTPS servers. + +When negotiating a TLS or SSL connection, the server sends a certificate +indicating its identity. Curl verifies whether the certificate is authentic, +i.e. that you can trust that the server is who the certificate says it is. +This trust is based on a chain of digital signatures, rooted in certification +authority (CA) certificates you supply. curl uses a default bundle of CA +certificates (the path for that is determined at build time) and you can +specify alternate certificates with the \fICURLOPT_PROXY_CAINFO(3)\fP option or +the \fICURLOPT_PROXY_CAPATH(3)\fP option. + +When \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is enabled, and the verification +fails to prove that the certificate is authentic, the connection fails. When +the option is zero, the peer certificate verification succeeds regardless. + +Authenticating the certificate is not enough to be sure about the server. You +typically also want to ensure that the server is the server you mean to be +talking to. Use \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP for that. The check that the +hostname in the certificate is valid for the hostname you are connecting to is +done independently of the \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. + +WARNING: disabling verification of the certificate allows bad guys to +man\-in\-the\-middle the communication without you knowing it. Disabling +verification makes the communication insecure. Just having encryption on a +transfer is not enough as you cannot be sure that you are communicating with +the correct end\-point. +.SH DEFAULT +1 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the default value: strict certificate check please */ + curl_easy_setopt(curl, CURLOPT_PROXY_SSL_VERIFYPEER, 1L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLS13_CIPHERS.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLS13_CIPHERS.3 new file mode 100644 index 0000000..ca77ea3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLS13_CIPHERS.3 @@ -0,0 +1,75 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_TLS13_CIPHERS.md +.TH CURLOPT_PROXY_TLS13_CIPHERS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_TLS13_CIPHERS \- ciphers suites for proxy TLS 1.3 +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLS13_CIPHERS, + char *list); +.fi +.SH DESCRIPTION +Pass a char pointer, pointing to a null\-terminated string holding the list of +cipher suites to use for the TLS 1.3 connection to a proxy. The list must be +syntactically correct, it consists of one or more cipher suite strings +separated by colons. + +For setting TLS 1.2 (1.1, 1.0) ciphers see \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP. + +A valid example of a cipher list is: +.nf +"TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256" +.fi + +Find more details about cipher lists on this URL: + + https://curl.se/docs/ssl\-ciphers.html + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL, use internal built\-in list +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL, Schannel, mbedTLS, rustls and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLS13_CIPHERS, + "TLS_CHACHA20_POLY1305_SHA256"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +OpenSSL support added in 7.61.0, available when built with OpenSSL >= 1.1.1. +Schannel support added in 7.87.0. +LibreSSL support added in 8.3.0, available when built with LibreSSL >= 3.4.1. +wolfSSL support added in 8.10.0. +mbedTLS support added in 8.10.0, available when built with mbedTLS >= 3.6.0. +Rustls support added in 8.10.0. + +Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites where set +by using the \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP option. +.SH AVAILABILITY +Added in curl 7.61.0 +.SH RETURN VALUE +Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSLVERSION (3), +.BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), +.BR CURLOPT_SSLVERSION (3), +.BR CURLOPT_SSL_CIPHER_LIST (3), +.BR CURLOPT_TLS13_CIPHERS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 new file mode 100644 index 0000000..a90f2d0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_TLSAUTH_PASSWORD.md +.TH CURLOPT_PROXY_TLSAUTH_PASSWORD 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_TLSAUTH_PASSWORD \- password to use for proxy TLS authentication +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_PASSWORD, + char *pwd); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should point to the null\-terminated +password to use for the TLS authentication method specified with the +\fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP option. Requires that the +\fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP option also be set. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY_TLSAUTH_TYPE (3), +.BR CURLOPT_PROXY_TLSAUTH_USERNAME (3), +.BR CURLOPT_TLSAUTH_TYPE (3), +.BR CURLOPT_TLSAUTH_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLSAUTH_TYPE.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLSAUTH_TYPE.3 new file mode 100644 index 0000000..4c22d2a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLSAUTH_TYPE.3 @@ -0,0 +1,60 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_TLSAUTH_TYPE.md +.TH CURLOPT_PROXY_TLSAUTH_TYPE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_TLSAUTH_TYPE \- HTTPS proxy TLS authentication methods +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_TYPE, + char *type); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. The string should be +the method of the TLS authentication used for the HTTPS connection. Supported +method is "SRP". + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to restore to internal default. + +The application does not have to keep the string around after setting this +option. +.IP SRP +TLS\-SRP authentication. Secure Remote Password authentication for TLS is +defined in RFC 5054 and provides mutual authentication if both sides have a +shared secret. To use TLS\-SRP, you must also set the +\fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP and \fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP +options. +.SH DEFAULT +blank +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_PROXY_TLSAUTH_PASSWORD (3), +.BR CURLOPT_PROXY_TLSAUTH_USERNAME (3), +.BR CURLOPT_TLSAUTH_PASSWORD (3), +.BR CURLOPT_TLSAUTH_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLSAUTH_USERNAME.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLSAUTH_USERNAME.3 new file mode 100644 index 0000000..6b7473c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TLSAUTH_USERNAME.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_TLSAUTH_USERNAME.md +.TH CURLOPT_PROXY_TLSAUTH_USERNAME 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_TLSAUTH_USERNAME \- username to use for proxy TLS authentication +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_USERNAME, + char *user); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should point to the null\-terminated +username to use for the HTTPS proxy TLS authentication method specified with +the \fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP option. Requires that the +\fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP option also be set. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.52.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY_TLSAUTH_PASSWORD (3), +.BR CURLOPT_PROXY_TLSAUTH_TYPE (3), +.BR CURLOPT_TLSAUTH_PASSWORD (3), +.BR CURLOPT_TLSAUTH_TYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TRANSFER_MODE.3 b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TRANSFER_MODE.3 new file mode 100644 index 0000000..e159acb --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PROXY_TRANSFER_MODE.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PROXY_TRANSFER_MODE.md +.TH CURLOPT_PROXY_TRANSFER_MODE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PROXY_TRANSFER_MODE \- append FTP transfer mode to URL for proxy +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TRANSFER_MODE, + long enabled); +.fi +.SH DESCRIPTION +Pass a long. If the value is set to 1 (one), it tells libcurl to set the +transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by +appending ;type=a or ;type=i to the URL. Without this setting, or it being set +to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT(3)\fP has no effect when +doing FTP via a proxy. Beware that not all proxies support this feature. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/old-server/file.txt"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:80"); + curl_easy_setopt(curl, CURLOPT_PROXY_TRANSFER_MODE, 1L); + curl_easy_setopt(curl, CURLOPT_TRANSFERTEXT, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.18.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the +enabled value is not supported. +.SH SEE ALSO +.BR CURLOPT_CRLF (3), +.BR CURLOPT_HTTPPROXYTUNNEL (3), +.BR CURLOPT_PROXY (3), +.BR CURLOPT_TRANSFERTEXT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_PUT.3 b/3rdparty/curl/share/man/man3/CURLOPT_PUT.3 new file mode 100644 index 0000000..7b063b2 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_PUT.3 @@ -0,0 +1,70 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_PUT.md +.TH CURLOPT_PUT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_PUT \- make an HTTP PUT request +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PUT, long put); +.fi +.SH DESCRIPTION +A parameter set to 1 tells the library to use HTTP PUT to transfer data. The +data should be set with \fICURLOPT_READDATA(3)\fP and +\fICURLOPT_INFILESIZE(3)\fP. + +This option is \fBdeprecated\fP since version 7.12.1. Use \fICURLOPT_UPLOAD(3)\fP. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +static size_t read_cb(char *ptr, size_t size, size_t nmemb, void *userdata) +{ + FILE *src = userdata; + /* copy as much data as possible into the 'ptr' buffer, but no more than + 'size' * 'nmemb' bytes */ + size_t retcode = fread(ptr, size, nmemb, src); + + return retcode; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + FILE *src = fopen("local-file", "r"); + curl_off_t fsize; /* set this to the size of the input file */ + + /* we want to use our own read function */ + curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); + + /* enable PUT */ + curl_easy_setopt(curl, CURLOPT_PUT, 1L); + + /* specify target */ + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); + + /* now specify which pointer to pass to our callback */ + curl_easy_setopt(curl, CURLOPT_READDATA, src); + + /* Set the size of the file to upload */ + curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize); + + /* Now run off and do what you have been told */ + curl_easy_perform(curl); + } +} +.fi +.SH DEPRECATED +Deprecated since 7.12.1. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTPGET (3), +.BR CURLOPT_MIMEPOST (3), +.BR CURLOPT_POSTFIELDS (3), +.BR CURLOPT_UPLOAD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_QUICK_EXIT.3 b/3rdparty/curl/share/man/man3/CURLOPT_QUICK_EXIT.3 new file mode 100644 index 0000000..2a5018e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_QUICK_EXIT.3 @@ -0,0 +1,41 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_QUICK_EXIT.md +.TH CURLOPT_QUICK_EXIT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_QUICK_EXIT \- allow to exit quickly +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_QUICK_EXIT, + long value); +.fi +.SH DESCRIPTION +Pass a long as a parameter, 1L meaning that when recovering from a timeout, +libcurl should skip lengthy cleanups that are intended to avoid all kinds of +leaks (threads etc.), as the caller program is about to call exit() anyway. +This allows for a swift termination after a DNS timeout for example, by +canceling and/or forgetting about a resolver thread, at the expense of a +possible (though short\-lived) leak of associated resources. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_QUICK_EXIT, 1L); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.87.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_FAILONERROR (3), +.BR CURLOPT_RESOLVE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_QUOTE.3 b/3rdparty/curl/share/man/man3/CURLOPT_QUOTE.3 new file mode 100644 index 0000000..902d02c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_QUOTE.3 @@ -0,0 +1,121 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_QUOTE.md +.TH CURLOPT_QUOTE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_QUOTE \- (S)FTP commands to run before transfer +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_QUOTE, + struct curl_slist *cmds); +.fi +.SH DESCRIPTION +Pass a pointer to a linked list of FTP or SFTP commands to pass to the server +prior to your request. This is done before any other commands are issued (even +before the CWD command for FTP). The linked list should be a fully valid list +of \(aqstruct curl_slist\(aq structs properly filled in with text strings. Use +\fIcurl_slist_append(3)\fP to append strings (commands) to the list, and clear +the entire list afterwards with \fIcurl_slist_free_all(3)\fP. + +Using this option multiple times makes the last set list override the previous +ones. Set it to NULL to disable its use again. libcurl does not copy the list, +it needs to be kept around until after the transfer has completed. + +When speaking to an FTP server, prefix the command with an asterisk (*) to +make libcurl continue even if the command fails as by default libcurl stops at +first failure. + +The set of valid FTP commands depends on the server (see RFC 959 for a list of +mandatory commands). + +libcurl does not inspect, parse or "understand" the commands passed to the +server using this option. If you change connection state, working directory or +similar using quote commands, libcurl does not know about it. + +The path arguments for FTP or SFTP can use single or double quotes to +distinguish a space from being the parameter separator or being a part of the +path. e.g. rename with sftp using a quote command like this: + +.nf +"rename 'test/_upload.txt' 'test/Hello World.txt'" +.fi +.SH SFTP commands +.IP "atime date file" +The atime command sets the last access time of the file named by the file +operand. The date expression can be all sorts of date strings, see the +\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0) +.IP "chgrp group file" +The chgrp command sets the group ID of the file named by the file operand to +the group ID specified by the group operand. The group operand is a decimal +integer group ID. +.IP "chmod mode file" +The chmod command modifies the file mode bits of the specified file. The +mode operand is an octal integer mode number. +.IP "chown user file" +The chown command sets the owner of the file named by the file operand to the +user ID specified by the user operand. The user operand is a decimal +integer user ID. +.IP "ln source_file target_file" +The \fBln\fP and \fBsymlink\fP commands create a symbolic link at the +target_file location pointing to the source_file location. +.IP "mkdir directory_name" +The mkdir command creates the directory named by the directory_name operand. +.IP "mtime date file" +The mtime command sets the last modification time of the file named by the +file operand. The date expression can be all sorts of date strings, see the +\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0) +.IP pwd +The \fBpwd\fP command returns the absolute path of the current working +directory. +.IP "rename source target" +The rename command renames the file or directory named by the source +operand to the destination path named by the target operand. +.IP "rm file" +The rm command removes the file specified by the file operand. +.IP "rmdir directory" +The rmdir command removes the directory entry specified by the directory +operand, provided it is empty. +.IP "statvfs file" +The statvfs command returns statistics on the file system in which specified +file resides. (Added in 7.49.0) +.IP "symlink source_file target_file" +See ln. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects ftp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + struct curl_slist *cmdlist = NULL; + cmdlist = curl_slist_append(cmdlist, "RNFR source-name"); + cmdlist = curl_slist_append(cmdlist, "RNTO new-name"); + + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); + + /* pass in the FTP commands to run before the transfer */ + curl_easy_setopt(curl, CURLOPT_QUOTE, cmdlist); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } + + curl_slist_free_all(cmdlist); +} +.fi +.SH HISTORY +SFTP support added in 7.16.3. *\-prefix for SFTP added in 7.24.0 +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_CUSTOMREQUEST (3), +.BR CURLOPT_DIRLISTONLY (3), +.BR CURLOPT_POSTQUOTE (3), +.BR CURLOPT_PREQUOTE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RANDOM_FILE.3 b/3rdparty/curl/share/man/man3/CURLOPT_RANDOM_FILE.3 new file mode 100644 index 0000000..e36f50f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RANDOM_FILE.3 @@ -0,0 +1,22 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RANDOM_FILE.md +.TH CURLOPT_RANDOM_FILE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RANDOM_FILE \- file to read random data from +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RANDOM_FILE, char *path); +.fi +.SH DESCRIPTION +Deprecated option. It serves no purpose anymore. +.SH DEFAULT +NULL, not used +.SH DEPRECATED +Deprecated since 7.84.0. +.SH AVAILABILITY +Added in curl 7.7 +.SH RETURN VALUE +Returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_EGDSOCKET (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RANGE.3 b/3rdparty/curl/share/man/man3/CURLOPT_RANGE.3 new file mode 100644 index 0000000..3d44916 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RANGE.3 @@ -0,0 +1,66 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RANGE.md +.TH CURLOPT_RANGE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RANGE \- byte range to request +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RANGE, char *range); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should contain the specified range you +want to retrieve. It should be in the format "X\-Y", where either X or Y may be +left out and X and Y are byte indexes. + +HTTP transfers also support several intervals, separated with commas as in +\fI"X\-Y,N\-M"\fP. Using this kind of multiple intervals causes the HTTP server +to send the response document in pieces (using standard MIME separation +techniques). Unfortunately, the HTTP standard (RFC 7233 section 3.1) allows +servers to ignore range requests so even when you set \fICURLOPT_RANGE(3)\fP +for a request, you may end up getting the full response sent back. + +For RTSP, the formatting of a range should follow RFC 2326 Section 12.29. For +RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges should be given in +\fBnpt\fP, \fButc\fP, or \fBsmpte\fP formats. + +For HTTP PUT uploads this option should not be used, since it may conflict with +other options. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects file, ftp, http, rtsp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* get the first 200 bytes */ + curl_easy_setopt(curl, CURLOPT_RANGE, "0-199"); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +FILE since 7.18.0, RTSP since 7.20.0 +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK on success or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_MAXFILESIZE_LARGE (3), +.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), +.BR CURLOPT_RESUME_FROM (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_READDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_READDATA.3 new file mode 100644 index 0000000..9575106 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_READDATA.3 @@ -0,0 +1,58 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_READDATA.md +.TH CURLOPT_READDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_READDATA \- pointer passed to the read callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READDATA, void *pointer); +.fi +.SH DESCRIPTION +Data \fIpointer\fP to pass to the file read function. If you use the +\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you get as input in +the fourth argument to the callback. + +If you do not specify a read callback but instead rely on the default internal +read function, this data must be a valid readable FILE * (cast to \(aqvoid *\(aq). + +If you are using libcurl as a DLL on Windows, you must use the +\fICURLOPT_READFUNCTION(3)\fP callback if you set this option, otherwise you +might experience crashes. +.SH DEFAULT +stdin +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct MyData { + void *custom; +}; + +int main(void) +{ + CURL *curl = curl_easy_init(); + struct MyData this; + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* pass pointer that gets passed in to the + CURLOPT_READFUNCTION callback */ + curl_easy_setopt(curl, CURLOPT_READDATA, &this); + + curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +This option was once known by the older name CURLOPT_INFILE, the name +\fICURLOPT_READDATA(3)\fP was introduced in 7.9.7. +.SH AVAILABILITY +Added in curl 7.9.7 +.SH RETURN VALUE +This returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_HEADERDATA (3), +.BR CURLOPT_READFUNCTION (3), +.BR CURLOPT_WRITEDATA (3), +.BR CURLOPT_WRITEFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_READFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_READFUNCTION.3 new file mode 100644 index 0000000..8aaf284 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_READFUNCTION.3 @@ -0,0 +1,104 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_READFUNCTION.md +.TH CURLOPT_READFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_READFUNCTION \- read callback for data uploads +.SH SYNOPSIS +.nf +#include + +size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, as the prototype shows above. + +This callback function gets called by libcurl as soon as it needs to read data +in order to send it to the peer \- like if you ask it to upload or post data to +the server. The data area pointed at by the pointer \fIbuffer\fP should be +filled up with at most \fIsize\fP multiplied with \fInitems\fP number of bytes +by your function. \fIsize\fP is always 1. + +Set the \fIuserdata\fP argument with the \fICURLOPT_READDATA(3)\fP option. + +Your function must return the actual number of bytes that it stored in the +data area pointed at by the pointer \fIbuffer\fP. Returning 0 signals +end\-of\-file to the library and causes it to stop the current transfer. + +If you stop the current transfer by returning 0 "pre\-maturely" (i.e before the +server expected it, like when you have said you would upload N bytes and you +upload less than N bytes), you may experience that the server "hangs" waiting +for the rest of the data that is not sent. + +The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current +operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error +code from the transfer. + +The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this +connection to pause. See \fIcurl_easy_pause(3)\fP for further details. + +\fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data +that the callback wants, or it is considered the final packet by the server +end and the transfer ends there. + +If you set this callback pointer to NULL, or do not set it at all, the default +internal read function is used. It is doing an fread() on the FILE * userdata +set with \fICURLOPT_READDATA(3)\fP. + +You can set the total size of the data you are sending by using +\fICURLOPT_INFILESIZE_LARGE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP, +depending on the type of transfer. For some transfer types it may be required +and it allows for better error checking. +.SH DEFAULT +fread(3) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +size_t read_callback(char *ptr, size_t size, size_t nmemb, void *userdata) +{ + FILE *readhere = (FILE *)userdata; + curl_off_t nread; + + /* copy as much data as possible into the 'ptr' buffer, but no more than + 'size' * 'nmemb' bytes! */ + size_t retcode = fread(ptr, size, nmemb, readhere); + + nread = (curl_off_t)retcode; + + fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T + " bytes from file\\n", nread); + return retcode; +} + +int main(int argc, char **argv) +{ + FILE *file = fopen(argv[1], "rb"); + CURLcode result; + + CURL *curl = curl_easy_init(); + if(curl) { + /* set callback to use */ + curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback); + + /* pass in suitable argument to callback */ + curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file); + + result = curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT +was added in 7.12.1. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +This returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_POST (3), +.BR CURLOPT_READDATA (3), +.BR CURLOPT_SEEKFUNCTION (3), +.BR CURLOPT_UPLOAD (3), +.BR CURLOPT_UPLOAD_BUFFERSIZE (3), +.BR CURLOPT_WRITEFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_REDIR_PROTOCOLS.3 b/3rdparty/curl/share/man/man3/CURLOPT_REDIR_PROTOCOLS.3 new file mode 100644 index 0000000..dbaae53 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_REDIR_PROTOCOLS.3 @@ -0,0 +1,95 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_REDIR_PROTOCOLS.md +.TH CURLOPT_REDIR_PROTOCOLS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_REDIR_PROTOCOLS \- protocols allowed to redirect to +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REDIR_PROTOCOLS, long bitmask); +.fi +.SH DESCRIPTION +This option is deprecated. We strongly recommend using +\fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP instead because this option cannot +control all available protocols! + +Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask +limits what protocols libcurl may use in a transfer that it follows to in a +redirect when \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This allows you to +limit specific transfers to only be allowed to use a subset of protocols in +redirections. + +Protocols denied by \fICURLOPT_PROTOCOLS(3)\fP are not overridden by this +option. + +By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). +\fICURLPROTO_ALL\fP enables all protocols on redirect, including those +otherwise disabled for security. + +These are the available protocol defines: +.nf +CURLPROTO_DICT +CURLPROTO_FILE +CURLPROTO_FTP +CURLPROTO_FTPS +CURLPROTO_GOPHER +CURLPROTO_HTTP +CURLPROTO_HTTPS +CURLPROTO_IMAP +CURLPROTO_IMAPS +CURLPROTO_LDAP +CURLPROTO_LDAPS +CURLPROTO_POP3 +CURLPROTO_POP3S +CURLPROTO_RTMP +CURLPROTO_RTMPE +CURLPROTO_RTMPS +CURLPROTO_RTMPT +CURLPROTO_RTMPTE +CURLPROTO_RTMPTS +CURLPROTO_RTSP +CURLPROTO_SCP +CURLPROTO_SFTP +CURLPROTO_SMB +CURLPROTO_SMBS +CURLPROTO_SMTP +CURLPROTO_SMTPS +CURLPROTO_TELNET +CURLPROTO_TFTP +.fi +.SH DEFAULT +HTTP, HTTPS, FTP and FTPS (Added in 7.65.2). + +Older versions defaulted to all protocols except FILE, SCP and since 7.40.0 +SMB and SMBS. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(int argc, char **argv) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* pass in the URL from an external source */ + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + + /* only allow redirects to HTTP and HTTPS URLs */ + curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS, + CURLPROTO_HTTP | CURLPROTO_HTTPS); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH DEPRECATED +Deprecated since 7.85.0. +.SH AVAILABILITY +Added in curl 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_SCHEME (3), +.BR CURLOPT_DEFAULT_PROTOCOL (3), +.BR CURLOPT_PROTOCOLS (3), +.BR CURLOPT_REDIR_PROTOCOLS_STR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_REDIR_PROTOCOLS_STR.3 b/3rdparty/curl/share/man/man3/CURLOPT_REDIR_PROTOCOLS_STR.3 new file mode 100644 index 0000000..bc51ad7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_REDIR_PROTOCOLS_STR.3 @@ -0,0 +1,79 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_REDIR_PROTOCOLS_STR.md +.TH CURLOPT_REDIR_PROTOCOLS_STR 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_REDIR_PROTOCOLS_STR \- protocols allowed to redirect to +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REDIR_PROTOCOLS_STR, + char *spec); +.fi +.SH DESCRIPTION +Pass a pointer to a string that holds a comma\-separated list of case +insensitive protocol names (URL schemes). That list limits what protocols +libcurl may use in a transfer that it follows to in a redirect when +\fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This option allows applications to limit +specific transfers to only be allowed to use a subset of protocols in +redirections. + +Protocols denied by \fICURLOPT_PROTOCOLS_STR(3)\fP are not overridden by this +option. + +By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects (since +7.65.2). + +These are the available protocols: + +DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, +MQTT, POP3, POP3S, RTMP, RTMPE, RTMPS, RTMPT, RTMPTE, RTMPTS, RTSP, SCP, SFTP, +SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS, WSS + +You can set "ALL" as a short\-cut to enable all protocols. Note that by setting +all, you may enable protocols that were not supported the day you write this +but are introduced in a future libcurl version. + +If trying to set a non\-existing protocol or if no matching protocol at all is +set, it returns error. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to restore to internal default. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +HTTP, HTTPS, FTP and FTPS (Added in 7.65.2). + +Older versions defaulted to all protocols except FILE, SCP and since 7.40.0 +SMB and SMBS. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(int argc, char **argv) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* pass in the URL from an external source */ + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + + /* only allow redirects to HTTP and HTTPS URLs */ + curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS_STR, "http,https"); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.85.0 +.SH RETURN VALUE +Returns CURLE_UNKNOWN_OPTION if the option is not implemented, +CURLE_UNSUPPORTED_PROTOCOL if a listed protocol is not supported or disabled, +CURLE_BAD_FUNCTION_ARGUMENT if no protocol is listed else CURLE_OK. +.SH SEE ALSO +.BR CURLINFO_SCHEME (3), +.BR CURLOPT_DEFAULT_PROTOCOL (3), +.BR CURLOPT_PROTOCOLS (3), +.BR CURLOPT_PROTOCOLS_STR (3), +.BR CURLOPT_REDIR_PROTOCOLS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_REFERER.3 b/3rdparty/curl/share/man/man3/CURLOPT_REFERER.3 new file mode 100644 index 0000000..6a49190 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_REFERER.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_REFERER.md +.TH CURLOPT_REFERER 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_REFERER \- the HTTP referer header +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REFERER, char *where); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. It is used to set the +Referer: header field in the HTTP request sent to the remote server. You can +set any custom header with \fICURLOPT_HTTPHEADER(3)\fP. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* tell it where we found the link to this place */ + curl_easy_setopt(curl, CURLOPT_REFERER, "https://example.org/me.html"); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP support is enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLINFO_REDIRECT_URL (3), +.BR CURLINFO_REFERER (3), +.BR CURLOPT_HTTPHEADER (3), +.BR CURLOPT_USERAGENT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_REQUEST_TARGET.3 b/3rdparty/curl/share/man/man3/CURLOPT_REQUEST_TARGET.3 new file mode 100644 index 0000000..b6c060d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_REQUEST_TARGET.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_REQUEST_TARGET.md +.TH CURLOPT_REQUEST_TARGET 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_REQUEST_TARGET \- alternative target for this request +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REQUEST_TARGET, string); +.fi +.SH DESCRIPTION +Pass a char pointer to string which libcurl uses in the upcoming request +instead of the path as extracted from the URL. + +libcurl passes on the verbatim string in its request without any filter or +other safe guards. That includes white space and control characters. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/*"); + curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "OPTIONS"); + + /* issue an OPTIONS * request (no leading slash) */ + curl_easy_setopt(curl, CURLOPT_REQUEST_TARGET, "*"); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.55.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CUSTOMREQUEST (3), +.BR CURLOPT_HTTPGET (3), +.BR CURLOPT_PATH_AS_IS (3), +.BR CURLOPT_URL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RESOLVE.3 b/3rdparty/curl/share/man/man3/CURLOPT_RESOLVE.3 new file mode 100644 index 0000000..9f83d3e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RESOLVE.3 @@ -0,0 +1,106 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RESOLVE.md +.TH CURLOPT_RESOLVE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RESOLVE \- provide custom hostname to IP address resolves +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVE, + struct curl_slist *hosts); +.fi +.SH DESCRIPTION +Pass a pointer to a linked list of strings with hostname resolve information +to use for requests with this handle. The linked list should be a fully valid +list of \fBstruct curl_slist\fP structs properly filled in. Use +\fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to clean up +an entire list. + +libcurl does not copy the list, it needs to be kept around until after the +transfer has completed. + +Each resolve rule to add should be written using the format + +.nf +[+]HOST:PORT:ADDRESS[,ADDRESS] +.fi + +HOST is the name libcurl wants to resolve, PORT is the port number of the +service where libcurl wants to connect to the HOST and ADDRESS is one or more +numerical IP addresses. If you specify multiple IP addresses they need to be +separated by comma. If libcurl is built to support IPv6, each of the ADDRESS +entries can of course be either IPv4 or IPv6 style addressing. + +Specify the host as a single ampersand (\fI*\fP) to match all names. This wildcard +is resolved last so any resolve with a specific host and port number is given +priority. + +This option effectively populates the DNS cache with entries for the host+port +pair so redirects and everything that operations against the HOST+PORT instead +use your provided ADDRESS. + +The optional leading plus (\fI+\fP) specifies that the new entry should timeout. +Entries added without the leading plus character never times out whereas +entries added with \fI+HOST:...\fP times out just like ordinary DNS cache entries. + +If the DNS cache already has an entry for the given host+port pair, the new +entry overrides the former one. + +An ADDRESS provided by this option is only used if not restricted by the +setting of \fICURLOPT_IPRESOLVE(3)\fP to a different IP version. + +To remove names from the DNS cache again, to stop providing these fake +resolves, include a string in the linked list that uses the format + +.nf +-HOST:PORT +.fi + +The entry to remove must be prefixed with a dash, and the hostname and port +number must exactly match what was added previously. + +Using this option multiple times makes the last set list override the previous +ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl; + struct curl_slist *host = NULL; + host = curl_slist_append(NULL, "example.com:443:127.0.0.1"); + + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_RESOLVE, host); + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } + + curl_slist_free_all(host); +} +.fi +.SH HISTORY +Added in 7.21.3. Removal support added in 7.42.0. + +Support for providing the ADDRESS within [brackets] was added in 7.57.0. + +Support for providing multiple IP addresses per entry was added in 7.59.0. + +Support for adding non\-permanent entries by using the "+" prefix was added in +7.75.0. +.SH AVAILABILITY +Added in curl 7.21.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CONNECT_TO (3), +.BR CURLOPT_DNS_CACHE_TIMEOUT (3), +.BR CURLOPT_IPRESOLVE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RESOLVER_START_DATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_RESOLVER_START_DATA.3 new file mode 100644 index 0000000..2a6c237 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RESOLVER_START_DATA.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RESOLVER_START_DATA.md +.TH CURLOPT_RESOLVER_START_DATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RESOLVER_START_DATA \- pointer passed to the resolver start callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVER_START_DATA, + void *pointer); +.fi +.SH DESCRIPTION +Pass a \fIpointer\fP is be untouched by libcurl and passed as the third +argument in the resolver start callback set with +\fICURLOPT_RESOLVER_START_FUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +static int resolver_start_cb(void *resolver_state, void *reserved, + void *userdata) +{ + (void)reserved; + printf("Received resolver_state=%p userdata=%p\\n", + resolver_state, userdata); + return 0; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, resolver_start_cb); + curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl); + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.59.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_PREREQFUNCTION (3), +.BR CURLOPT_RESOLVER_START_FUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RESOLVER_START_FUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_RESOLVER_START_FUNCTION.3 new file mode 100644 index 0000000..98c3a67 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RESOLVER_START_FUNCTION.3 @@ -0,0 +1,67 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RESOLVER_START_FUNCTION.md +.TH CURLOPT_RESOLVER_START_FUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RESOLVER_START_FUNCTION \- callback called before a new name resolve is started +.SH SYNOPSIS +.nf +#include + +int resolver_start_cb(void *resolver_state, void *reserved, void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, + CURLOPT_RESOLVER_START_FUNCTION, + resolver_start_cb); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl every time before a new resolve +request is started. + +\fIresolver_state\fP points to a backend\-specific resolver state. Currently only +the ares resolver backend has a resolver state. It can be used to set up any +desired option on the ares channel before it is used, for example setting up +socket callback options. + +\fIreserved\fP is reserved. + +\fIuserdata\fP is the user pointer set with the +\fICURLOPT_RESOLVER_START_DATA(3)\fP option. + +The callback must return 0 on success. Returning a non\-zero value causes the +resolve to fail. +.SH DEFAULT +NULL (No callback) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +static int start_cb(void *resolver_state, void *reserved, + void *userdata) +{ + (void)reserved; + printf("Received resolver_state=%p userdata=%p\\n", + resolver_state, userdata); + return 0; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, start_cb); + curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl); + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.59.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_PREREQFUNCTION (3), +.BR CURLOPT_RESOLVER_START_DATA (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RESUME_FROM.3 b/3rdparty/curl/share/man/man3/CURLOPT_RESUME_FROM.3 new file mode 100644 index 0000000..16b4ecf --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RESUME_FROM.3 @@ -0,0 +1,59 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RESUME_FROM.md +.TH CURLOPT_RESUME_FROM 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RESUME_FROM \- offset to resume transfer from +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESUME_FROM, long from); +.fi +.SH DESCRIPTION +Pass a long as parameter. It contains the offset in number of bytes that you +want the transfer to start from. Set this option to 0 to make the transfer +start from the beginning (effectively disabling resume). For FTP, set this +option to \-1 to make the transfer start from the end of the target file +(useful to continue an interrupted upload). + +When doing uploads with FTP, the resume position is where in the local/source +file libcurl should try to resume the upload from and it then appends the +source file to the remote target file. + +If you need to resume a transfer beyond the 2GB limit, use +\fICURLOPT_RESUME_FROM_LARGE(3)\fP instead. +.SH DEFAULT +0, not used +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + long size_of_file; + + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); + + /* resume upload at byte index 200 */ + curl_easy_setopt(curl, CURLOPT_RESUME_FROM, 200L); + + /* ask for upload */ + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + /* set total data amount to expect */ + curl_easy_setopt(curl, CURLOPT_INFILESIZE, size_of_file); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_INFILESIZE (3), +.BR CURLOPT_RANGE (3), +.BR CURLOPT_RESUME_FROM_LARGE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RESUME_FROM_LARGE.3 b/3rdparty/curl/share/man/man3/CURLOPT_RESUME_FROM_LARGE.3 new file mode 100644 index 0000000..c4a565a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RESUME_FROM_LARGE.3 @@ -0,0 +1,58 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RESUME_FROM_LARGE.md +.TH CURLOPT_RESUME_FROM_LARGE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RESUME_FROM_LARGE \- offset to resume transfer from +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESUME_FROM_LARGE, + curl_off_t from); +.fi +.SH DESCRIPTION +Pass a curl_off_t as parameter. It contains the offset in number of bytes that +you want the transfer to start from. Set this option to 0 to make the transfer +start from the beginning (effectively disabling resume). For FTP, set this +option to \-1 to make the transfer start from the end of the target file +(useful to continue an interrupted upload). + +When doing uploads with FTP, the resume position is where in the local/source +file libcurl should try to resume the upload from and it appends the source +file to the remote target file. +.SH DEFAULT +0, not used +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_off_t resume_position; /* get it somehow */ + curl_off_t file_size; /* get it somehow as well */ + + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); + + /* resuming upload at this position, possibly beyond 2GB */ + curl_easy_setopt(curl, CURLOPT_RESUME_FROM_LARGE, resume_position); + + /* ask for upload */ + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + /* set total data amount to expect */ + curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, file_size); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.11.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_INFILESIZE_LARGE (3), +.BR CURLOPT_RANGE (3), +.BR CURLOPT_RESUME_FROM (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RTSP_CLIENT_CSEQ.3 b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_CLIENT_CSEQ.3 new file mode 100644 index 0000000..a8436e9 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_CLIENT_CSEQ.3 @@ -0,0 +1,41 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RTSP_CLIENT_CSEQ.md +.TH CURLOPT_RTSP_CLIENT_CSEQ 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RTSP_CLIENT_CSEQ \- RTSP client CSEQ number +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_CLIENT_CSEQ, long cseq); +.fi +.SH DESCRIPTION +Pass a long to set the CSEQ number to issue for the next RTSP request. Useful +if the application is resuming a previously broken connection. The CSEQ +increments from this new number henceforth. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + curl_easy_setopt(curl, CURLOPT_RTSP_CLIENT_CSEQ, 1234L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RTSP_CLIENT_CSEQ (3), +.BR CURLINFO_RTSP_SERVER_CSEQ (3), +.BR CURLOPT_RTSP_REQUEST (3), +.BR CURLOPT_RTSP_SERVER_CSEQ (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RTSP_REQUEST.3 b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_REQUEST.3 new file mode 100644 index 0000000..ad01620 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_REQUEST.3 @@ -0,0 +1,97 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RTSP_REQUEST.md +.TH CURLOPT_RTSP_REQUEST 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RTSP_REQUEST \- RTSP request +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_REQUEST, long request); +.fi +.SH DESCRIPTION +Tell libcurl what kind of RTSP request to make. Pass one of the following RTSP +enum values as a long in the \fIrequest\fP argument. Unless noted otherwise, +commands require the Session ID to be initialized. +.IP CURL_RTSPREQ_OPTIONS +Used to retrieve the available methods of the server. The application is +responsible for parsing and obeying the response. The session ID is not needed +for this method. +.IP CURL_RTSPREQ_DESCRIBE +Used to get the low level description of a stream. The application should note +what formats it understands in the \fI\(aqAccept:\(aq\fP header. Unless set manually, +libcurl automatically adds in \fI\(aqAccept: application/sdp\(aq\fP. Time\-condition +headers are added to Describe requests if the \fICURLOPT_TIMECONDITION(3)\fP +option is used. (The session ID is not needed for this method) +.IP CURL_RTSPREQ_ANNOUNCE +When sent by a client, this method changes the description of the session. For +example, if a client is using the server to record a meeting, the client can +use Announce to inform the server of all the meta\-information about the +session. ANNOUNCE acts like an HTTP PUT or POST just like +\fICURL_RTSPREQ_SET_PARAMETER\fP +.IP CURL_RTSPREQ_SETUP +Setup is used to initialize the transport layer for the session. The +application must set the desired Transport options for a session by using the +\fICURLOPT_RTSP_TRANSPORT(3)\fP option prior to calling setup. If no session +ID is currently set with \fICURLOPT_RTSP_SESSION_ID(3)\fP, libcurl extracts +and uses the session ID in the response to this request. The session ID is not +needed for this method. +.IP CURL_RTSPREQ_PLAY +Send a Play command to the server. Use the \fICURLOPT_RANGE(3)\fP option to +modify the playback time (e.g. \fInpt=10\-15\fP). +.IP CURL_RTSPREQ_PAUSE +Send a Pause command to the server. Use the \fICURLOPT_RANGE(3)\fP option with +a single value to indicate when the stream should be +halted. (e.g. \fInpt=25\fP) +.IP CURL_RTSPREQ_TEARDOWN +This command terminates an RTSP session. Simply closing a connection does not +terminate the RTSP session since it is valid to control an RTSP session over +different connections. +.IP CURL_RTSPREQ_GET_PARAMETER +Retrieve a parameter from the server. By default, libcurl adds a +\fIContent\-Type: text/parameters\fP header on all non\-empty requests unless a +custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST (see +\fICURL_RTSPREQ_SET_PARAMETER\fP). Applications wishing to send a heartbeat +message (e.g. in the presence of a server\-specified timeout) should send use +an empty GET_PARAMETER request. +.IP CURL_RTSPREQ_SET_PARAMETER +Set a parameter on the server. By default, libcurl uses a *Content\-Type: +text/parameters* header unless a custom one is set. The interaction with +SET_PARAMETER is much like an HTTP PUT or POST. An application may either use +\fICURLOPT_UPLOAD(3)\fP with \fICURLOPT_READDATA(3)\fP like an HTTP PUT, or it may use +\fICURLOPT_POSTFIELDS(3)\fP like an HTTP POST. No chunked transfers are allowed, so +the application must set the \fICURLOPT_INFILESIZE(3)\fP in the former and +\fICURLOPT_POSTFIELDSIZE(3)\fP in the latter. Also, there is no use of multi\-part +POSTs within RTSP. +.IP CURL_RTSPREQ_RECORD +Used to tell the server to record a session. Use the \fICURLOPT_RANGE(3)\fP +option to modify the record time. +.IP CURL_RTSPREQ_RECEIVE +This is a special request because it does not send any data to the server. The +application may call this function in order to receive interleaved RTP +data. It returns after processing one read buffer of data in order to give the +application a chance to run. +.SH DEFAULT +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + /* ask for options! */ + curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_OPTIONS); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_RTSP_SESSION_ID (3), +.BR CURLOPT_RTSP_STREAM_URI (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RTSP_SERVER_CSEQ.3 b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_SERVER_CSEQ.3 new file mode 100644 index 0000000..ff01b80 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_SERVER_CSEQ.3 @@ -0,0 +1,40 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RTSP_SERVER_CSEQ.md +.TH CURLOPT_RTSP_SERVER_CSEQ 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RTSP_SERVER_CSEQ \- RTSP server CSEQ number +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SERVER_CSEQ, long cseq); +.fi +.SH DESCRIPTION +Pass a long to set the CSEQ number to expect for the next RTSP Server to +Client request. \fBNOTE\fP: this feature (listening for Server requests) is +unimplemented. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + curl_easy_setopt(curl, CURLOPT_RTSP_SERVER_CSEQ, 1234L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_RTSP_SERVER_CSEQ (3), +.BR CURLOPT_RTSP_CLIENT_CSEQ (3), +.BR CURLOPT_RTSP_STREAM_URI (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RTSP_SESSION_ID.3 b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_SESSION_ID.3 new file mode 100644 index 0000000..24da31a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_SESSION_ID.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RTSP_SESSION_ID.md +.TH CURLOPT_RTSP_SESSION_ID 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RTSP_SESSION_ID \- RTSP session ID +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SESSION_ID, char *id); +.fi +.SH DESCRIPTION +Pass a char pointer as a parameter to set the value of the current RTSP +Session ID for the handle. Useful for resuming an in\-progress session. Once +this value is set to any non\-NULL value, libcurl returns +\fICURLE_RTSP_SESSION_ERROR\fP if ID received from the server does not match. If +unset (or set to NULL), libcurl automatically sets the ID the first time the +server sets it in a response. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + char *prev_id; /* saved from before somehow */ + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + curl_easy_setopt(curl, CURLOPT_RTSP_SESSION_ID, prev_id); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_RTSP_REQUEST (3), +.BR CURLOPT_RTSP_STREAM_URI (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RTSP_STREAM_URI.3 b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_STREAM_URI.3 new file mode 100644 index 0000000..271690e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_STREAM_URI.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RTSP_STREAM_URI.md +.TH CURLOPT_RTSP_STREAM_URI 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RTSP_STREAM_URI \- RTSP stream URI +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_STREAM_URI, char *URI); +.fi +.SH DESCRIPTION +Set the stream \fIURI\fP to operate on by passing a char * . For example, a single +session may be controlling \fIrtsp://foo/twister/audio\fP and +\fIrtsp://foo/twister/video\fP and the application can switch to the appropriate +stream using this option. If unset, libcurl defaults to operating on generic +server options by passing \(aq*\(aq in the place of the RTSP Stream URI. This option +is distinct from \fICURLOPT_URL(3)\fP. When working with RTSP, the +\fICURLOPT_RTSP_STREAM_URI(3)\fP indicates what URL to send to the server in the +request header while the \fICURLOPT_URL(3)\fP indicates where to make the connection +to. (e.g. the \fICURLOPT_URL(3)\fP for the above examples might be set to +\fIrtsp://foo/twister\fP + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +\&"*" +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + curl_easy_setopt(curl, CURLOPT_RTSP_STREAM_URI, + "rtsp://foo.example.com/twister/video"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_RTSP_REQUEST (3), +.BR CURLOPT_RTSP_TRANSPORT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_RTSP_TRANSPORT.3 b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_TRANSPORT.3 new file mode 100644 index 0000000..252dac9 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_RTSP_TRANSPORT.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_RTSP_TRANSPORT.md +.TH CURLOPT_RTSP_TRANSPORT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_RTSP_TRANSPORT \- RTSP Transport: header +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_TRANSPORT, + char *transport); +.fi +.SH DESCRIPTION +Pass a char pointer to tell libcurl what to pass for the Transport: header for +this RTSP session. This is mainly a convenience method to avoid needing to set +a custom Transport: header for every SETUP request. The application must set a +Transport: header before issuing a SETUP request. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects rtsp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_SETUP); + curl_easy_setopt(curl, CURLOPT_RTSP_TRANSPORT, + "RTP/AVP;unicast;client_port=4588-4589"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_RTSP_REQUEST (3), +.BR CURLOPT_RTSP_SESSION_ID (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SASL_AUTHZID.3 b/3rdparty/curl/share/man/man3/CURLOPT_SASL_AUTHZID.3 new file mode 100644 index 0000000..01496a5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SASL_AUTHZID.3 @@ -0,0 +1,57 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SASL_AUTHZID.md +.TH CURLOPT_SASL_AUTHZID 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SASL_AUTHZID \- authorization identity (identity to act as) +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_AUTHZID, char *authzid); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should be pointing to the +null\-terminated authorization identity (\fIauthzid\fP) for the transfer. Only +applicable to the PLAIN SASL authentication mechanism where it is optional. + +When not specified only the authentication identity (\fIauthcid\fP) as specified +by the username is sent to the server, along with the password. The server +derives a \fIauthzid\fP from the \fIauthcid\fP when not provided, which it then uses +internally. + +When the \fIauthzid\fP is specified, the use of which is server dependent, it can +be used to access another user\(aqs inbox, that the user has been granted access +to, or a shared mailbox for example. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +blank +.SH PROTOCOLS +This functionality affects imap only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "imap://example.com/"); + curl_easy_setopt(curl, CURLOPT_USERNAME, "Kurt"); + curl_easy_setopt(curl, CURLOPT_PASSWORD, "xipj3plmq"); + curl_easy_setopt(curl, CURLOPT_SASL_AUTHZID, "Ursel"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.66.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_PASSWORD (3), +.BR CURLOPT_USERNAME (3), +.BR CURLOPT_USERPWD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SASL_IR.3 b/3rdparty/curl/share/man/man3/CURLOPT_SASL_IR.3 new file mode 100644 index 0000000..a4ecad6 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SASL_IR.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SASL_IR.md +.TH CURLOPT_SASL_IR 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SASL_IR \- send initial response in first packet +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_IR, long enable); +.fi +.SH DESCRIPTION +Pass a long. If the value is 1, curl sends the initial response to the server +in the first authentication packet in order to reduce the number of ping pong +requests. Only applicable to the following supporting SASL authentication +mechanisms: + +* Login +* Plain +* GSSAPI +* NTLM +* OAuth 2.0 + +Note: Whilst IMAP supports this option there is no need to explicitly set it, +as libcurl can determine the feature itself when the server supports the +SASL\-IR CAPABILITY. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_SASL_IR, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.31.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_MAIL_AUTH (3), +.BR CURLOPT_MAIL_FROM (3), +.BR CURLOPT_SASL_AUTHZID (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SEEKDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_SEEKDATA.3 new file mode 100644 index 0000000..944b7c6 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SEEKDATA.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SEEKDATA.md +.TH CURLOPT_SEEKDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SEEKDATA \- pointer passed to the seek callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKDATA, void *pointer); +.fi +.SH DESCRIPTION +Data \fIpointer\fP to pass to the seek callback function. If you use the +\fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you get as input. +.SH DEFAULT +If you do not set this, NULL is passed to the callback. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +#include /* for lseek() */ + +struct data { + int our_fd; +}; + +static int seek_cb(void *clientp, curl_off_t offset, int origin) +{ + struct data *d = (struct data *)clientp; + lseek(d->our_fd, offset, origin); + return CURL_SEEKFUNC_OK; +} + +int main(void) +{ + struct data seek_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_SEEKFUNCTION, seek_cb); + curl_easy_setopt(curl, CURLOPT_SEEKDATA, &seek_data); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.18.0 +.SH RETURN VALUE +.SH SEE ALSO +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_IOCTLFUNCTION (3), +.BR CURLOPT_SEEKFUNCTION (3), +.BR CURLOPT_STDERR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SEEKFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_SEEKFUNCTION.3 new file mode 100644 index 0000000..1e66fb0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SEEKFUNCTION.3 @@ -0,0 +1,81 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SEEKFUNCTION.md +.TH CURLOPT_SEEKFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SEEKFUNCTION \- user callback for seeking in input stream +.SH SYNOPSIS +.nf +#include + +/* These are the return codes for the seek callbacks */ +#define CURL_SEEKFUNC_OK 0 +#define CURL_SEEKFUNC_FAIL 1 /* fail the entire transfer */ +#define CURL_SEEKFUNC_CANTSEEK 2 /* tell libcurl seeking cannot be done, so + libcurl might try other means instead */ + +int seek_callback(void *clientp, curl_off_t offset, int origin); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKFUNCTION, seek_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This function gets called by libcurl to seek to a certain position in the +input stream and can be used to fast forward a file in a resumed upload +(instead of reading all uploaded bytes with the normal read +function/callback). It is also called to rewind a stream when data has already +been sent to the server and needs to be sent again. This may happen when doing +an HTTP PUT or POST with a multi\-pass authentication method, or when an +existing HTTP connection is reused too late and the server closes the +connection. The function shall work like fseek(3) or lseek(3) and it gets +SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP, although libcurl +currently only passes SEEK_SET. + +\fIclientp\fP is the pointer you set with \fICURLOPT_SEEKDATA(3)\fP. + +The callback function must return \fICURL_SEEKFUNC_OK\fP on success, +\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or +\fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl +is free to work around the problem if possible. The latter can sometimes be +done by instead reading from the input or similar. + +If you forward the input arguments directly to fseek(3) or lseek(3), note that +the data type for \fIoffset\fP is not the same as defined for curl_off_t on +many systems! +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +#include /* for lseek */ + +struct data { + int our_fd; +}; +static int seek_cb(void *clientp, curl_off_t offset, int origin) +{ + struct data *d = (struct data *)clientp; + lseek(d->our_fd, offset, origin); + return CURL_SEEKFUNC_OK; +} + +int main(void) +{ + struct data seek_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_SEEKFUNCTION, seek_cb); + curl_easy_setopt(curl, CURLOPT_SEEKDATA, &seek_data); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.18.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_IOCTLFUNCTION (3), +.BR CURLOPT_SEEKDATA (3), +.BR CURLOPT_STDERR (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SERVER_RESPONSE_TIMEOUT.3 b/3rdparty/curl/share/man/man3/CURLOPT_SERVER_RESPONSE_TIMEOUT.3 new file mode 100644 index 0000000..a6c32a9 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SERVER_RESPONSE_TIMEOUT.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SERVER_RESPONSE_TIMEOUT.md +.TH CURLOPT_SERVER_RESPONSE_TIMEOUT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SERVER_RESPONSE_TIMEOUT \- time allowed to wait for server response +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVER_RESPONSE_TIMEOUT, + long timeout); +.fi +.SH DESCRIPTION +Pass a long. Causes libcurl to set a \fItimeout\fP period (in seconds) on the +amount of time that the server is allowed to take in order to send a response +message for a command before the session is considered dead. While libcurl is +waiting for a response, this value overrides \fICURLOPT_TIMEOUT(3)\fP. It is +recommended that if used in conjunction with \fICURLOPT_TIMEOUT(3)\fP, you set +\fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP to a value smaller than +\fICURLOPT_TIMEOUT(3)\fP. + +This option was formerly known as CURLOPT_FTP_RESPONSE_TIMEOUT. +.SH DEFAULT +None +.SH PROTOCOLS +This functionality affects ftp, imap, pop3, scp, sftp and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/slow.txt"); + /* wait no more than 23 seconds */ + curl_easy_setopt(curl, CURLOPT_SERVER_RESPONSE_TIMEOUT, 23L); + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if supported, and CURLE_UNKNOWN_OPTION if not. Returns +CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value or a value that when +converted to milliseconds is too large. +.SH SEE ALSO +.BR CURLOPT_CONNECTTIMEOUT (3), +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 b/3rdparty/curl/share/man/man3/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 new file mode 100644 index 0000000..dd66ab5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md +.TH CURLOPT_SERVER_RESPONSE_TIMEOUT_MS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SERVER_RESPONSE_TIMEOUT_MS \- time allowed to wait for server response +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, + long timeout); +.fi +.SH DESCRIPTION +Pass a long. Causes libcurl to set a \fItimeout\fP period (in milliseconds) on the +amount of time that the server is allowed to take in order to send a response +message for a command before the session is considered dead. While libcurl is +waiting for a response, this value overrides \fICURLOPT_TIMEOUT(3)\fP. It is +recommended that if used in conjunction with \fICURLOPT_TIMEOUT(3)\fP, you set +\fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP to a value smaller than +\fICURLOPT_TIMEOUT(3)\fP. + +The maximum accepted value is 2147483648. + +This is the millisecond version of \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP. +.SH DEFAULT +None +.SH PROTOCOLS +This functionality affects ftp, imap, pop3, scp, sftp and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/slow.txt"); + /* wait no more than 237 milliseconds */ + curl_easy_setopt(curl, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, 237L); + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 8.6.0 +.SH RETURN VALUE +Returns CURLE_OK if supported, and CURLE_UNKNOWN_OPTION if not. Returns +CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value or a value that when +converted to milliseconds is too large. +.SH SEE ALSO +.BR CURLOPT_CONNECTTIMEOUT (3), +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SERVICE_NAME.3 b/3rdparty/curl/share/man/man3/CURLOPT_SERVICE_NAME.3 new file mode 100644 index 0000000..588578b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SERVICE_NAME.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SERVICE_NAME.md +.TH CURLOPT_SERVICE_NAME 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SERVICE_NAME \- authentication service name +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVICE_NAME, char *name); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter to a string holding the \fIname\fP of the service +for DIGEST\-MD5, SPNEGO and Kerberos 5 authentication mechanisms. The default +service names are "ftp", "HTTP", "imap", "ldap", "pop" and "smtp". This option +allows you to change them. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +See above +.SH PROTOCOLS +This functionality affects ftp, http, imap, ldap, pop3 and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SERVICE_NAME, "custom"); + ret = curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.43.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY (3), +.BR CURLOPT_PROXYTYPE (3), +.BR CURLOPT_PROXY_SERVICE_NAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SHARE.3 b/3rdparty/curl/share/man/man3/CURLOPT_SHARE.3 new file mode 100644 index 0000000..0593b43 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SHARE.3 @@ -0,0 +1,67 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SHARE.md +.TH CURLOPT_SHARE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SHARE \- share handle to use +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SHARE, CURLSH *share); +.fi +.SH DESCRIPTION +Pass a \fIshare\fP handle as a parameter. The share handle must have been +created by a previous call to \fIcurl_share_init(3)\fP. Setting this option, +makes this curl handle use the data from the shared handle instead of keeping +the data to itself. This enables several curl handles to share data. If the +curl handles are used simultaneously in multiple threads, you \fBMUST\fP use +the locking methods in the share handle. See \fIcurl_share_setopt(3)\fP for +details. + +If you add a share that is set to share cookies, your easy handle uses that +cookie cache and get the cookie engine enabled. If you stop sharing an object +that was using cookies (or change to another object that does not share +cookies), the easy handle gets its cookie engine disabled. + +Data that the share object is not set to share is dealt with the usual way, as +if no share was used. + +Set this option to NULL again to stop using that share object. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + CURL *curl2 = curl_easy_init(); /* a second handle */ + if(curl) { + CURLcode res; + CURLSH *shobject = curl_share_init(); + curl_share_setopt(shobject, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_COOKIEFILE, ""); + curl_easy_setopt(curl, CURLOPT_SHARE, shobject); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + + /* the second handle shares cookies from the first */ + curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/second"); + curl_easy_setopt(curl2, CURLOPT_COOKIEFILE, ""); + curl_easy_setopt(curl2, CURLOPT_SHARE, shobject); + res = curl_easy_perform(curl2); + curl_easy_cleanup(curl2); + + curl_share_cleanup(shobject); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_COOKIE (3), +.BR CURLSHOPT_SHARE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SOCKOPTDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_SOCKOPTDATA.3 new file mode 100644 index 0000000..7aa3a9b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SOCKOPTDATA.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SOCKOPTDATA.md +.TH CURLOPT_SOCKOPTDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SOCKOPTDATA \- pointer to pass to sockopt callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTDATA, void *pointer); +.fi +.SH DESCRIPTION +Pass a \fIpointer\fP that is untouched by libcurl and passed as the first +argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +static int sockopt_callback(void *clientp, curl_socket_t curlfd, + curlsocktype purpose) +{ + int val = *(int *)clientp; + setsockopt((int)curlfd, SOL_SOCKET, SO_RCVBUF, + (const char *)&val, sizeof(val)); + return CURL_SOCKOPT_OK; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + int recvbuffersize = 256 * 1024; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + + /* call this function to set options for the socket */ + curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); + curl_easy_setopt(curl, CURLOPT_SOCKOPTDATA, &recvbuffersize); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.0 +.SH RETURN VALUE +Returns \fICURLE_OK\fP if the option is supported, and \fICURLE_UNKNOWN_OPTION\fP if not. +.SH SEE ALSO +.BR CURLOPT_OPENSOCKETFUNCTION (3), +.BR CURLOPT_SOCKOPTFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SOCKOPTFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_SOCKOPTFUNCTION.3 new file mode 100644 index 0000000..6f796f4 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SOCKOPTFUNCTION.3 @@ -0,0 +1,110 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SOCKOPTFUNCTION.md +.TH CURLOPT_SOCKOPTFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SOCKOPTFUNCTION \- callback for setting socket options +.SH SYNOPSIS +.nf +#include + +typedef enum { + CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */ + CURLSOCKTYPE_ACCEPT, /* socket created by accept() call */ + CURLSOCKTYPE_LAST /* never use */ +} curlsocktype; + +#define CURL_SOCKOPT_OK 0 +#define CURL_SOCKOPT_ERROR 1 /* causes libcurl to abort and return + CURLE_ABORTED_BY_CALLBACK */ +#define CURL_SOCKOPT_ALREADY_CONNECTED 2 + +int sockopt_callback(void *clientp, + curl_socket_t curlfd, + curlsocktype purpose); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +When set, this callback function gets called by libcurl when the socket has +been created, but before the connect call to allow applications to change +specific socket options. The callback\(aqs \fIpurpose\fP argument identifies the +exact purpose for this particular socket: + +\fICURLSOCKTYPE_IPCXN\fP for actively created connections or since 7.28.0 +\fICURLSOCKTYPE_ACCEPT\fP for FTP when the connection was setup with PORT/EPSV +(in earlier versions these sockets were not passed to this callback). + +Future versions of libcurl may support more purposes. libcurl passes the newly +created socket descriptor to the callback in the \fIcurlfd\fP parameter so +additional setsockopt() calls can be done at the user\(aqs discretion. + +The \fIclientp\fP pointer contains whatever user\-defined value set using the +\fICURLOPT_SOCKOPTDATA(3)\fP function. + +Return \fICURL_SOCKOPT_OK\fP from the callback on success. Return +\fICURL_SOCKOPT_ERROR\fP from the callback function to signal an unrecoverable +error to the library and it closes the socket and returns +\fICURLE_COULDNT_CONNECT\fP. Alternatively, the callback function can return +\fICURL_SOCKOPT_ALREADY_CONNECTED\fP, to tell libcurl that the socket is +already connected and then libcurl does no attempt to connect. This allows an +application to pass in an already connected socket with +\fICURLOPT_OPENSOCKETFUNCTION(3)\fP and then have this function make libcurl +not attempt to connect (again). +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +/* make libcurl use the already established socket 'sockfd' */ + +static curl_socket_t opensocket(void *clientp, + curlsocktype purpose, + struct curl_sockaddr *address) +{ + curl_socket_t sockfd; + sockfd = *(curl_socket_t *)clientp; + /* the actual externally set socket is passed in via the OPENSOCKETDATA + option */ + return sockfd; +} + +static int sockopt_callback(void *clientp, curl_socket_t curlfd, + curlsocktype purpose) +{ + /* This return code was added in libcurl 7.21.5 */ + return CURL_SOCKOPT_ALREADY_CONNECTED; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + int sockfd; /* our custom file descriptor */ + /* libcurl thinks that you connect to the host + * and port that you specify in the URL option. */ + curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999"); + /* call this function to get a socket */ + curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket); + curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd); + + /* call this function to set options for the socket */ + curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_OPENSOCKETFUNCTION (3), +.BR CURLOPT_SEEKFUNCTION (3), +.BR CURLOPT_SOCKOPTDATA (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SOCKS5_AUTH.3 b/3rdparty/curl/share/man/man3/CURLOPT_SOCKS5_AUTH.3 new file mode 100644 index 0000000..1360c78 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SOCKS5_AUTH.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SOCKS5_AUTH.md +.TH CURLOPT_SOCKS5_AUTH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SOCKS5_AUTH \- methods for SOCKS5 proxy authentication +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_AUTH, long bitmask); +.fi +.SH DESCRIPTION +Pass a long as parameter, which is set to a bitmask, to tell libcurl which +authentication method(s) are allowed for SOCKS5 proxy authentication. The only +supported flags are \fICURLAUTH_BASIC\fP, which allows username/password +authentication, \fICURLAUTH_GSSAPI\fP, which allows GSS\-API authentication, and +\fICURLAUTH_NONE\fP, which allows no authentication. Set the actual username and +password with the \fICURLOPT_PROXYUSERPWD(3)\fP option. +.SH DEFAULT +CURLAUTH_BASIC|CURLAUTH_GSSAPI +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* request to use a SOCKS5 proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://user:pass@myproxy.com"); + + /* enable username/password authentication only */ + curl_easy_setopt(curl, CURLOPT_SOCKS5_AUTH, (long)CURLAUTH_BASIC); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.55.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_NOT_BUILT_IN if the bitmask contains unsupported flags. +.SH SEE ALSO +.BR CURLOPT_PROXY (3), +.BR CURLOPT_PROXYTYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SOCKS5_GSSAPI_NEC.3 b/3rdparty/curl/share/man/man3/CURLOPT_SOCKS5_GSSAPI_NEC.3 new file mode 100644 index 0000000..e36f8f3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SOCKS5_GSSAPI_NEC.3 @@ -0,0 +1,42 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SOCKS5_GSSAPI_NEC.md +.TH CURLOPT_SOCKS5_GSSAPI_NEC 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SOCKS5_GSSAPI_NEC \- SOCKS proxy GSSAPI negotiation protection +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_NEC, long nec); +.fi +.SH DESCRIPTION +Pass a long set to 1 to enable or 0 to disable. As part of the GSSAPI +negotiation a protection mode is negotiated. The RFC 1961 says in section +4.3/4.4 it should be protected, but the NEC reference implementation does not. +If enabled, this option allows the unprotected exchange of the protection mode +negotiation. +.SH DEFAULT +? +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://proxy"); + curl_easy_setopt(curl, CURLOPT_SOCKS5_GSSAPI_NEC, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_PROXY (3), +.BR CURLOPT_PROXY_SERVICE_NAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 b/3rdparty/curl/share/man/man3/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 new file mode 100644 index 0000000..04861f6 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SOCKS5_GSSAPI_SERVICE.md +.TH CURLOPT_SOCKS5_GSSAPI_SERVICE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SOCKS5_GSSAPI_SERVICE \- SOCKS5 proxy authentication service name +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_SERVICE, + char *name); +.fi +.SH DESCRIPTION +Deprecated since 7.49.0. Use \fICURLOPT_PROXY_SERVICE_NAME(3)\fP instead. + +Pass a char pointer as parameter to a string holding the \fIname\fP of the +service. The default service name for a SOCKS5 server is \fIrcmd\fP. This option +allows you to change it. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +See above +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://proxy"); + curl_easy_setopt(curl, CURLOPT_SOCKS5_GSSAPI_SERVICE, "rcmd-special"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH DEPRECATED +Deprecated since 7.49.0 +.SH AVAILABILITY +Added in curl 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY (3), +.BR CURLOPT_PROXYTYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSH_AUTH_TYPES.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSH_AUTH_TYPES.3 new file mode 100644 index 0000000..20b7f88 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSH_AUTH_TYPES.3 @@ -0,0 +1,46 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSH_AUTH_TYPES.md +.TH CURLOPT_SSH_AUTH_TYPES 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSH_AUTH_TYPES \- auth types for SFTP and SCP +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_AUTH_TYPES, long bitmask); +.fi +.SH DESCRIPTION +Pass a long set to a bitmask consisting of one or more of +CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, +CURLSSH_AUTH_KEYBOARD and CURLSSH_AUTH_AGENT. + +Set \fICURLSSH_AUTH_ANY\fP to let libcurl pick a suitable one. Currently +CURLSSH_AUTH_HOST has no effect. If CURLSSH_AUTH_AGENT is used, libcurl +attempts to connect to ssh\-agent or pageant and let the agent attempt the +authentication. +.SH DEFAULT +CURLSSH_AUTH_ANY (all available) +.SH PROTOCOLS +This functionality affects scp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_AUTH_TYPES, + CURLSSH_AUTH_PUBLICKEY | CURLSSH_AUTH_KEYBOARD); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3), +.BR CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3), +.BR CURLOPT_SSH_PUBLIC_KEYFILE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSH_COMPRESSION.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSH_COMPRESSION.3 new file mode 100644 index 0000000..c989087 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSH_COMPRESSION.3 @@ -0,0 +1,43 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSH_COMPRESSION.md +.TH CURLOPT_SSH_COMPRESSION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSH_COMPRESSION \- enable SSH compression +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_COMPRESSION, long enable); +.fi +.SH DESCRIPTION +Pass a long as parameter set to 1L to enable or 0L to disable. + +Enables built\-in SSH compression. This is a request, not an order; the server +may or may not do it. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects scp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com"); + + /* enable built-in compression */ + curl_easy_setopt(curl, CURLOPT_SSH_COMPRESSION, 1L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_ACCEPT_ENCODING (3), +.BR CURLOPT_TRANSFER_ENCODING (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOSTKEYDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOSTKEYDATA.3 new file mode 100644 index 0000000..d99bc51 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOSTKEYDATA.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSH_HOSTKEYDATA.md +.TH CURLOPT_SSH_HOSTKEYDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSH_HOSTKEYDATA \- pointer to pass to the SSH host key callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOSTKEYDATA, void *pointer); +.fi +.SH DESCRIPTION +Pass a void * as parameter. This \fIpointer\fP is passed along untouched to +the callback set with \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects scp and sftp +.SH EXAMPLE +.nf +struct mine { + void *custom; +}; + +static int hostkeycb(void *clientp, /* CURLOPT_SSH_HOSTKEYDATA */ + int keytype, /* CURLKHTYPE */ + const char *key, /* host key to check */ + size_t keylen) /* length of the key */ +{ + /* 'clientp' points to the callback_data struct */ + /* investigate the situation and return the correct value */ + return CURLKHMATCH_OK; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct mine callback_data; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); + curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYFUNCTION, hostkeycb); + curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYDATA, &callback_data); + + curl_easy_perform(curl); + } +} +.fi +.SH NOTES +Works only with the libssh2 backend. +.SH AVAILABILITY +Added in curl 7.84.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_SSH_HOSTKEYFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOSTKEYFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOSTKEYFUNCTION.3 new file mode 100644 index 0000000..03881c7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOSTKEYFUNCTION.3 @@ -0,0 +1,75 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSH_HOSTKEYFUNCTION.md +.TH CURLOPT_SSH_HOSTKEYFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSH_HOSTKEYFUNCTION \- callback to check host key +.SH SYNOPSIS +.nf +#include + +int keycallback(void *clientp, + int keytype, + const char *key, + size_t keylen); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOSTKEYFUNCTION, + keycallback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. It overrides \fICURLOPT_SSH_KNOWNHOSTS(3)\fP. + +This callback gets called when the verification of the SSH host key is needed. + +\fBkey\fP is \fBkeylen\fP bytes long and is the key to check. \fBkeytype\fP +says what type it is, from the \fBCURLKHTYPE_\fP* series in the +\fBcurl_khtype\fP enum. + +\fBclientp\fP is a custom pointer set with \fICURLOPT_SSH_HOSTKEYDATA(3)\fP. + +The callback MUST return one of the following return codes to tell libcurl how +to act: +.IP CURLKHMATCH_OK +The host key is accepted, the connection should continue. +.IP CURLKHMATCH_MISMATCH +the host key is rejected, the connection is canceled. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects scp and sftp +.SH EXAMPLE +.nf +struct mine { + void *custom; +}; + +int hostkeycb(void *clientp, /* passed with CURLOPT_SSH_HOSTKEYDATA */ + int keytype, /* CURLKHTYPE */ + const char *key, /* host key to check */ + size_t keylen) /* length of the key */ +{ + /* 'clientp' points to the callback_data struct */ + /* investigate the situation and return the correct value */ + return CURLKHMATCH_OK; +} +int main(void) +{ + struct mine callback_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); + curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYFUNCTION, hostkeycb); + curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYDATA, &callback_data); + + curl_easy_perform(curl); + } +} +.fi +.SH NOTES +Work only with the libssh2 backend. +.SH AVAILABILITY +Added in curl 7.84.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_SSH_HOSTKEYDATA (3), +.BR CURLOPT_SSH_KNOWNHOSTS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 new file mode 100644 index 0000000..d6becfe --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md +.TH CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 \- MD5 checksum of SSH server public key +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5, + char *md5); +.fi +.SH DESCRIPTION +Pass a char pointer pointing to a string containing 32 hexadecimal digits. The +string should be the 128 bit MD5 checksum of the remote host\(aqs public key, and +libcurl aborts the connection to the host unless the MD5 checksum match. + +MD5 is a weak algorithm. We strongly recommend using +\fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP instead. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects scp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5, + "afe17cd62a0f3b61f1ab9cb22ba269a7"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.17.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_SSH_AUTH_TYPES (3), +.BR CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3), +.BR CURLOPT_SSH_KNOWNHOSTS (3), +.BR CURLOPT_SSH_PUBLIC_KEYFILE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 new file mode 100644 index 0000000..e8d6aef --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md +.TH CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 \- SHA256 hash of SSH server public key +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256, + char *sha256); +.fi +.SH DESCRIPTION +Pass a char pointer pointing to a string containing a Base64\-encoded SHA256 +hash of the remote host\(aqs public key. The transfer fails if the given hash +does not match the hash the remote host provides. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects scp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256, + "NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ="); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH NOTES +Requires the libssh2 backend. +.SH AVAILABILITY +Added in curl 7.80.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_SSH_AUTH_TYPES (3), +.BR CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3), +.BR CURLOPT_SSH_PUBLIC_KEYFILE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSH_KEYDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSH_KEYDATA.3 new file mode 100644 index 0000000..57f47c7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSH_KEYDATA.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSH_KEYDATA.md +.TH CURLOPT_SSH_KEYDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSH_KEYDATA \- pointer passed to the SSH key callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYDATA, void *pointer); +.fi +.SH DESCRIPTION +Pass a void * as parameter. This \fIpointer\fP is passed along verbatim to the +callback set with \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects scp and sftp +.SH EXAMPLE +.nf +struct mine { + void *custom; +}; +static int keycb(CURL *easy, + const struct curl_khkey *knownkey, + const struct curl_khkey *foundkey, + enum curl_khmatch match, + void *clientp) +{ + /* 'clientp' points to the callback_data struct */ + /* investigate the situation and return the correct value */ + return CURLKHSTAT_FINE_ADD_TO_FILE; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct mine callback_data; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); + curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb); + curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data); + curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts"); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.6 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_SSH_KEYDATA (3), +.BR CURLOPT_SSH_KNOWNHOSTS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSH_KEYFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSH_KEYFUNCTION.3 new file mode 100644 index 0000000..2eadb85 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSH_KEYFUNCTION.3 @@ -0,0 +1,121 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSH_KEYFUNCTION.md +.TH CURLOPT_SSH_KEYFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSH_KEYFUNCTION \- callback for known host matching logic +.SH SYNOPSIS +.nf +#include + +enum curl_khstat { + CURLKHSTAT_FINE_ADD_TO_FILE, + CURLKHSTAT_FINE, + CURLKHSTAT_REJECT, /* reject the connection, return an error */ + CURLKHSTAT_DEFER, /* do not accept it, but we cannot answer right + now. Causes a CURLE_PEER_FAILED_VERIFICATION error but + the connection is left intact */ + CURLKHSTAT_FINE_REPLACE +}; + +enum curl_khmatch { + CURLKHMATCH_OK, /* match */ + CURLKHMATCH_MISMATCH, /* host found, key mismatch! */ + CURLKHMATCH_MISSING, /* no matching host/key found */ +}; + +struct curl_khkey { + const char *key; /* points to a null-terminated string encoded with + base64 if len is zero, otherwise to the "raw" + data */ + size_t len; + enum curl_khtype keytype; +}; + +int ssh_keycallback(CURL *easy, + const struct curl_khkey *knownkey, + const struct curl_khkey *foundkey, + enum curl_khmatch match, + void *clientp); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYFUNCTION, + ssh_keycallback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +It gets called when the known_host matching has been done, to allow the +application to act and decide for libcurl how to proceed. The callback is only +called if \fICURLOPT_SSH_KNOWNHOSTS(3)\fP is also set. + +This callback function gets passed the CURL handle, the key from the +known_hosts file \fIknownkey\fP, the key from the remote site \fIfoundkey\fP, +info from libcurl on the matching status and a custom pointer (set with +\fICURLOPT_SSH_KEYDATA(3)\fP). It MUST return one of the following return +codes to tell libcurl how to act: +.IP CURLKHSTAT_FINE_REPLACE +The new host+key is accepted and libcurl replaces the old host+key into the +known_hosts file before continuing with the connection. This also adds the new +host+key combo to the known_host pool kept in memory if it was not already +present there. The adding of data to the file is done by completely replacing +the file with a new copy, so the permissions of the file must allow +this. (Added in 7.73.0) +.IP CURLKHSTAT_FINE_ADD_TO_FILE +The host+key is accepted and libcurl appends it to the known_hosts file before +continuing with the connection. This also adds the host+key combo to the +known_host pool kept in memory if it was not already present there. The adding +of data to the file is done by completely replacing the file with a new copy, +so the permissions of the file must allow this. +.IP CURLKHSTAT_FINE +The host+key is accepted libcurl continues with the connection. This also adds +the host+key combo to the known_host pool kept in memory if it was not already +present there. +.IP CURLKHSTAT_REJECT +The host+key is rejected. libcurl denies the connection to continue and it is +closed. +.IP CURLKHSTAT_DEFER +The host+key is rejected, but the SSH connection is asked to be kept alive. +This feature could be used when the app wants to return and act on the +host+key situation and then retry without needing the overhead of setting it +up from scratch again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects scp and sftp +.SH EXAMPLE +.nf +struct mine { + void *custom; +}; + +static int keycb(CURL *easy, + const struct curl_khkey *knownkey, + const struct curl_khkey *foundkey, + enum curl_khmatch match, + void *clientp) +{ + /* 'clientp' points to the callback_data struct */ + /* investigate the situation and return the correct value */ + return CURLKHSTAT_FINE_ADD_TO_FILE; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct mine callback_data; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); + curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb); + curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data); + curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts"); + + curl_easy_perform(curl); +} +} +.fi +.SH AVAILABILITY +Added in curl 7.19.6 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_SSH_KEYDATA (3), +.BR CURLOPT_SSH_KNOWNHOSTS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSH_KNOWNHOSTS.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSH_KNOWNHOSTS.3 new file mode 100644 index 0000000..21d64b6 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSH_KNOWNHOSTS.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSH_KNOWNHOSTS.md +.TH CURLOPT_SSH_KNOWNHOSTS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSH_KNOWNHOSTS \- filename holding the SSH known hosts +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KNOWNHOSTS, char *fname); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string holding the filename of the +known_host file to use. The known_hosts file should use the OpenSSH file +format as supported by libssh2. If this file is specified, libcurl only +accepts connections with hosts that are known and present in that file, with a +matching public key. Use \fICURLOPT_SSH_KEYFUNCTION(3)\fP to alter the default +behavior on host and key matches and mismatches. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects scp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, + "/home/clarkkent/.ssh/known_hosts"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.6 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_SSH_AUTH_TYPES (3), +.BR CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSH_PRIVATE_KEYFILE.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSH_PRIVATE_KEYFILE.3 new file mode 100644 index 0000000..3beb52f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSH_PRIVATE_KEYFILE.3 @@ -0,0 +1,55 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSH_PRIVATE_KEYFILE.md +.TH CURLOPT_SSH_PRIVATE_KEYFILE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSH_PRIVATE_KEYFILE \- private key file for SSH auth +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PRIVATE_KEYFILE, + char *filename); +.fi +.SH DESCRIPTION +Pass a char pointer pointing to a \fIfilename\fP for your private key. If not +used, libcurl defaults to \fB$HOME/.ssh/id_rsa\fP or \fB$HOME/.ssh/id_dsa\fP if +the HOME environment variable is set, and in the current directory if HOME is +not set. + +If the file is password\-protected, set the password with +\fICURLOPT_KEYPASSWD(3)\fP. + +The SSH library derives the public key from this private key when possible. If +the SSH library cannot derive the public key from the private one and no +public one is provided with \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP, the transfer +fails. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +As explained above +.SH PROTOCOLS +This functionality affects scp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_PRIVATE_KEYFILE, + "/home/clarkkent/.ssh/id_rsa"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "password"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_SSH_AUTH_TYPES (3), +.BR CURLOPT_SSH_PUBLIC_KEYFILE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSH_PUBLIC_KEYFILE.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSH_PUBLIC_KEYFILE.3 new file mode 100644 index 0000000..d12cb72 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSH_PUBLIC_KEYFILE.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSH_PUBLIC_KEYFILE.md +.TH CURLOPT_SSH_PUBLIC_KEYFILE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSH_PUBLIC_KEYFILE \- public key file for SSH auth +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PUBLIC_KEYFILE, + char *filename); +.fi +.SH DESCRIPTION +Pass a char pointer pointing to a \fIfilename\fP for your public key. If not used, +libcurl defaults to \fB$HOME/.ssh/id_dsa.pub\fP if the HOME environment variable +is set, and just "id_dsa.pub" in the current directory if HOME is not set. + +If NULL (or an empty string) is passed to this option, libcurl passes no +public key to the SSH library, which then rather derives it from the private +key. If the SSH library cannot derive the public key from the private one and +no public one is provided, the transfer fails. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects scp and sftp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_PUBLIC_KEYFILE, + "/home/clarkkent/.ssh/id_rsa.pub"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +The "" trick was added in 7.26.0 +.SH AVAILABILITY +Added in curl 7.16.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_SSH_AUTH_TYPES (3), +.BR CURLOPT_SSH_PRIVATE_KEYFILE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSLCERT.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSLCERT.3 new file mode 100644 index 0000000..b7894a1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSLCERT.3 @@ -0,0 +1,72 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSLCERT.md +.TH CURLOPT_SSLCERT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSLCERT \- SSL client certificate +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT, char *cert); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. The string should be +the filename of your client certificate. The default format is \fIP12\fP on Secure +Transport and \fIPEM\fP on other engines, and can be changed with +\fICURLOPT_SSLCERTTYPE(3)\fP. + +With Secure Transport, this can also be the nickname of the certificate you +wish to authenticate with as it is named in the security database. If you want +to use a file from the current directory, please precede it with \fI./\fP prefix, +in order to avoid confusion with a nickname. + +(Schannel only) Client certificates can be specified by a path expression to a +certificate store. (You can import \fIPFX\fP to a store first). You can use +\&"\\\\" to refer to a certificate +in the system certificates store, for example, +\fB"CurrentUser\\MY\\934a7ac6f8a5d5"\fP. The thumbprint is usually a SHA\-1 hex +string which you can see in certificate details. Following store locations are +supported: \fBCurrentUser\fP, \fBLocalMachine\fP, \fBCurrentService\fP, +\fBServices\fP, \fBCurrentUserGroupPolicy\fP, \fBLocalMachineGroupPolicy\fP, +\fBLocalMachineEnterprise\fP. Schannel also support P12 certificate file, with +the string \fIP12\fP specified with \fICURLOPT_SSLCERTTYPE(3)\fP. + +When using a client certificate, you most likely also need to provide a +private key with \fICURLOPT_SSLKEY(3)\fP. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_KEYPASSWD (3), +.BR CURLOPT_SSLCERTTYPE (3), +.BR CURLOPT_SSLKEY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSLCERTTYPE.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSLCERTTYPE.3 new file mode 100644 index 0000000..767f4d4 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSLCERTTYPE.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSLCERTTYPE.md +.TH CURLOPT_SSLCERTTYPE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSLCERTTYPE \- type of client SSL certificate +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERTTYPE, char *type); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. The string should be +the format of your certificate. + +Supported formats are "PEM" and "DER", except with Secure Transport or +Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or +later, or macOS 10.7 or later) and Schannel support "P12" for PKCS#12\-encoded +files. GnuTLS supports P12 starting with curl 8.11.0. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL restores back to internal default. +.SH DEFAULT +\&"PEM" +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "PEM"); + curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.3 +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_SSLCERT (3), +.BR CURLOPT_SSLKEY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSLCERT_BLOB.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSLCERT_BLOB.3 new file mode 100644 index 0000000..eb2be95 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSLCERT_BLOB.3 @@ -0,0 +1,64 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSLCERT_BLOB.md +.TH CURLOPT_SSLCERT_BLOB 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSLCERT_BLOB \- SSL client certificate from memory blob +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT_BLOB, + struct curl_blob *stblob); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_blob structure, which contains (pointer and size) a +client certificate. The format must be "P12" on Secure Transport or +Schannel. The format must be "P12" or "PEM" on OpenSSL. The format must be +\&"DER" or "PEM" on mbedTLS. The format must be specified with +\fICURLOPT_SSLCERTTYPE(3)\fP. + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. + +This option is an alternative to \fICURLOPT_SSLCERT(3)\fP which instead +expects a filename as input. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL +.SH EXAMPLE +.nf + +extern char *certificateData; /* point to data */ +extern size_t filesize; /* size of data */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob stblob; + stblob.data = certificateData; + stblob.len = filesize; + stblob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLCERT_BLOB, &stblob); + curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "P12"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.71.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_KEYPASSWD (3), +.BR CURLOPT_SSLCERTTYPE (3), +.BR CURLOPT_SSLKEY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSLENGINE.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSLENGINE.3 new file mode 100644 index 0000000..9ca9f7d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSLENGINE.3 @@ -0,0 +1,59 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSLENGINE.md +.TH CURLOPT_SSLENGINE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSLENGINE \- SSL engine identifier +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE, char *id); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. It is used as the +identifier for the crypto engine you want to use for your private key. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLENGINE, "dynamic"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.3 +.SH RETURN VALUE +CURLE_OK \- Engine found. + +CURLE_SSL_ENGINE_NOTFOUND \- Engine not found, or OpenSSL was not built with +engine support. + +CURLE_SSL_ENGINE_INITFAILED \- Engine found but initialization failed. + +CURLE_NOT_BUILT_IN \- Option not built in, OpenSSL is not the SSL backend. + +CURLE_UNKNOWN_OPTION \- Option not recognized. + +CURLE_OUT_OF_MEMORY \- Insufficient heap space. +.SH SEE ALSO +.BR CURLINFO_SSL_ENGINES (3), +.BR CURLOPT_SSLENGINE_DEFAULT (3), +.BR CURLOPT_SSLKEY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSLENGINE_DEFAULT.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSLENGINE_DEFAULT.3 new file mode 100644 index 0000000..44ad665 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSLENGINE_DEFAULT.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSLENGINE_DEFAULT.md +.TH CURLOPT_SSLENGINE_DEFAULT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSLENGINE_DEFAULT \- make SSL engine default +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE_DEFAULT, long val); +.fi +.SH DESCRIPTION +Pass a long set to 1 to make the already specified crypto engine the default +for (asymmetric) crypto operations. + +This option has no effect unless set after \fICURLOPT_SSLENGINE(3)\fP. +.SH DEFAULT +None +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLENGINE, "dynamic"); + curl_easy_setopt(curl, CURLOPT_SSLENGINE_DEFAULT, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.3 +.SH RETURN VALUE +CURLE_OK \- Engine set as default. + +CURLE_SSL_ENGINE_SETFAILED \- Engine could not be set as default. + +CURLE_NOT_BUILT_IN \- Option not built in, OpenSSL is not the SSL backend. + +CURLE_UNKNOWN_OPTION \- Option not recognized. + +CURLE_OUT_OF_MEMORY \- Insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_SSLCERT (3), +.BR CURLOPT_SSLENGINE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSLKEY.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSLKEY.3 new file mode 100644 index 0000000..aeaa7eb --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSLKEY.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSLKEY.md +.TH CURLOPT_SSLKEY 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSLKEY \- private key file for TLS and SSL client cert +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEY, char *keyfile); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. The string should be +the filename of your private key. The default format is "PEM" and can be +changed with \fICURLOPT_SSLKEYTYPE(3)\fP. + +(Windows, iOS and macOS) This option is ignored by Secure Transport and +Schannel SSL backends because they expect the private key to be already present +in the key\-chain or PKCS#12 file containing the certificate. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL, Schannel, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.3 +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_SSLCERT (3), +.BR CURLOPT_SSLKEYTYPE (3), +.BR CURLOPT_SSLKEY_BLOB (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSLKEYTYPE.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSLKEYTYPE.3 new file mode 100644 index 0000000..e6a6053 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSLKEYTYPE.3 @@ -0,0 +1,57 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSLKEYTYPE.md +.TH CURLOPT_SSLKEYTYPE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSLKEYTYPE \- type of the private key file +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEYTYPE, char *type); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. The string should be +the format of your private key. Supported formats are "PEM", "DER" and "ENG". + +The format "ENG" enables you to load the private key from a crypto engine. In +this case \fICURLOPT_SSLKEY(3)\fP is used as an identifier passed to the engine. You +have to set the crypto engine with \fICURLOPT_SSLENGINE(3)\fP. "DER" format key file +currently does not work because of a bug in OpenSSL. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to restore to internal default. +.SH DEFAULT +\&"PEM" +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +BearSSL, OpenSSL and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_SSLKEYTYPE, "PEM"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.3 +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSLKEYTYPE (3), +.BR CURLOPT_SSLCERT (3), +.BR CURLOPT_SSLKEY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSLKEY_BLOB.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSLKEY_BLOB.3 new file mode 100644 index 0000000..c0dec6c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSLKEY_BLOB.3 @@ -0,0 +1,69 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSLKEY_BLOB.md +.TH CURLOPT_SSLKEY_BLOB 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSLKEY_BLOB \- private key for client cert from memory blob +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEY_BLOB, + struct curl_blob *blob); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_blob structure, which contains information (pointer +and size) for a private key. Compatible with OpenSSL. The format (like "PEM") +must be specified with \fICURLOPT_SSLKEYTYPE(3)\fP. + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. + +This option is an alternative to \fICURLOPT_SSLKEY(3)\fP which instead expects a +filename as input. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL and wolfSSL +.SH EXAMPLE +.nf + +extern char *certificateData; /* point to cert */ +extern size_t filesize; /* size of cert */ + +extern char *privateKeyData; /* point to key */ +extern size_t privateKeySize; /* size of key */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob blob; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + blob.data = certificateData; + blob.len = filesize; + blob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_SSLCERT_BLOB, &blob); + curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "PEM"); + + blob.data = privateKeyData; + blob.len = privateKeySize; + curl_easy_setopt(curl, CURLOPT_SSLKEY_BLOB, &blob); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); + curl_easy_setopt(curl, CURLOPT_SSLKEYTYPE, "PEM"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.71.0 +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_SSLKEY (3), +.BR CURLOPT_SSLKEYTYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSLVERSION.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSLVERSION.3 new file mode 100644 index 0000000..cc88f32 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSLVERSION.3 @@ -0,0 +1,105 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSLVERSION.md +.TH CURLOPT_SSLVERSION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSLVERSION \- preferred TLS/SSL version +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLVERSION, long version); +.fi +.SH DESCRIPTION +Pass a long as parameter to control which version range of SSL/TLS versions to +use. + +The SSL and TLS versions have typically developed from the most insecure +version to be more and more secure in this order through history: SSL v2, +SSLv3, TLS v1.0, TLS v1.1, TLS v1.2 and the most recent TLS v1.3. + +Use one of the available defines for this purpose. The available options are: +.IP CURL_SSLVERSION_DEFAULT +The default acceptable version range. The minimum acceptable version is by +default TLS v1.0 since 7.39.0 (unless the TLS library has a stricter rule). +.IP CURL_SSLVERSION_TLSv1 +TLS v1.0 or later +.IP CURL_SSLVERSION_SSLv2 +SSL v2 \- refused +.IP CURL_SSLVERSION_SSLv3 +SSL v3 \- refused +.IP CURL_SSLVERSION_TLSv1_0 +TLS v1.0 or later (Added in 7.34.0) +.IP CURL_SSLVERSION_TLSv1_1 +TLS v1.1 or later (Added in 7.34.0) +.IP CURL_SSLVERSION_TLSv1_2 +TLS v1.2 or later (Added in 7.34.0) +.IP CURL_SSLVERSION_TLSv1_3 +TLS v1.3 or later (Added in 7.52.0) +.PP +The maximum TLS version can be set by using \fIone\fP of the +CURL_SSLVERSION_MAX_ macros below. It is also possible to OR \fIone\fP of the +CURL_SSLVERSION_ macros with \fIone\fP of the CURL_SSLVERSION_MAX_ macros. +.IP CURL_SSLVERSION_MAX_DEFAULT +The flag defines the maximum supported TLS version by libcurl, or the default +value from the SSL library is used. libcurl uses a sensible default maximum, +which was TLS v1.2 up to before 7.61.0 and is TLS v1.3 since then \- assuming +the TLS library support it. (Added in 7.54.0) +.IP CURL_SSLVERSION_MAX_TLSv1_0 +The flag defines maximum supported TLS version as TLS v1.0. +(Added in 7.54.0) +.IP CURL_SSLVERSION_MAX_TLSv1_1 +The flag defines maximum supported TLS version as TLS v1.1. +(Added in 7.54.0) +.IP CURL_SSLVERSION_MAX_TLSv1_2 +The flag defines maximum supported TLS version as TLS v1.2. +(Added in 7.54.0) +.IP CURL_SSLVERSION_MAX_TLSv1_3 +The flag defines maximum supported TLS version as TLS v1.3. +(Added in 7.54.0) +.PP +In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were +documented to allow \fIonly\fP the specified TLS version, but behavior was +inconsistent depending on the TLS library. +.SH DEFAULT +CURL_SSLVERSION_DEFAULT +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* ask libcurl to use TLS version 1.0 or later */ + curl_easy_setopt(curl, CURLOPT_SSLVERSION, (long)CURL_SSLVERSION_TLSv1); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +SSLv2 is disabled by default since 7.18.1. Other SSL versions availability may +vary depending on which backend libcurl has been built to use. + +SSLv3 is disabled by default since 7.39.0. + +SSLv2 and SSLv3 are refused completely since curl 7.77.0 + +Since 8.10.0 wolfSSL is fully supported. Before 8.10.0 the MAX macros were not +supported with wolfSSL and the other macros did not set a minimum, but +restricted the TLS version to only the specified one. + +Rustls support added in 8.10.0. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTP_VERSION (3), +.BR CURLOPT_IPRESOLVE (3), +.BR CURLOPT_PROXY_SSLVERSION (3), +.BR CURLOPT_USE_SSL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_CIPHER_LIST.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_CIPHER_LIST.3 new file mode 100644 index 0000000..ce5b7b3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_CIPHER_LIST.3 @@ -0,0 +1,79 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_CIPHER_LIST.md +.TH CURLOPT_SSL_CIPHER_LIST 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_CIPHER_LIST \- ciphers to use for TLS +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CIPHER_LIST, char *list); +.fi +.SH DESCRIPTION +Pass a char pointer, pointing to a null\-terminated string holding the list of +cipher suites to use for the TLS 1.2 (1.1, 1.0) connection. The list must +be syntactically correct, it consists of one or more cipher suite strings +separated by colons. + +For setting TLS 1.3 ciphers see \fICURLOPT_TLS13_CIPHERS(3)\fP. + +A valid example of a cipher list is: +.nf +"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:" +"ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305" +.fi + +For Schannel, you can use this option to set algorithms but not specific +cipher suites. Refer to the ciphers lists document for algorithms. + +Find more details about cipher lists on this URL: + + https://curl.se/docs/ssl\-ciphers.html + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL, use built\-in list +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +BearSSL, OpenSSL, Schannel, Secure Transport, mbedTLS, rustls and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSL_CIPHER_LIST, + "ECDHE-ECDSA-CHACHA20-POLY1305:" + "ECDHE-RSA-CHACHA20-POLY1305"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +OpenSSL support added in 7.9. +wolfSSL support added in 7.53.0. +Schannel support added in 7.61.0. +Secure Transport support added in 7.77.0. +BearSSL support added in 7.83.0. +mbedTLS support added in 8.8.0. +Rustls support added in 8.10.0. + +Since curl 8.10.0 returns CURLE_NOT_BUILT_IN when not supported. +.SH AVAILABILITY +Added in curl 7.9 +.SH RETURN VALUE +Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), +.BR CURLOPT_PROXY_TLS13_CIPHERS (3), +.BR CURLOPT_SSLVERSION (3), +.BR CURLOPT_TLS13_CIPHERS (3), +.BR CURLOPT_USE_SSL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_CTX_DATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_CTX_DATA.3 new file mode 100644 index 0000000..a7ec0da --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_CTX_DATA.3 @@ -0,0 +1,108 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_CTX_DATA.md +.TH CURLOPT_SSL_CTX_DATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_CTX_DATA \- pointer passed to SSL context callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_DATA, void *pointer); +.fi +.SH DESCRIPTION +Data \fIpointer\fP to pass to the ssl context callback set by the option +\fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you get as third +parameter. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +BearSSL, OpenSSL, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +/* OpenSSL specific */ + +#include +#include +#include + +static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm) +{ + X509_STORE *store; + X509 *cert = NULL; + BIO *bio; + char *mypem = parm; + /* get a BIO */ + bio = BIO_new_mem_buf(mypem, -1); + /* use it to read the PEM formatted certificate from memory into an + * X509 structure that SSL can use + */ + PEM_read_bio_X509(bio, &cert, 0, NULL); + if(!cert) + printf("PEM_read_bio_X509 failed...\\n"); + + /* get a pointer to the X509 certificate store (which may be empty) */ + store = SSL_CTX_get_cert_store((SSL_CTX *)sslctx); + + /* add our certificate to this store */ + if(X509_STORE_add_cert(store, cert) == 0) + printf("error adding certificate\\n"); + + /* decrease reference counts */ + X509_free(cert); + BIO_free(bio); + + /* all set to go */ + return CURLE_OK; +} + +int main(void) +{ + CURL *ch; + CURLcode rv; + char *mypem = /* example CA cert PEM - shortened */ + "-----BEGIN CERTIFICATE-----\\n" + "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\\n" + "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\\n" + "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\\n" + "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\\n" + "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\\n" + "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\\n" + "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\\n" + "-----END CERTIFICATE-----\\n"; + + curl_global_init(CURL_GLOBAL_ALL); + ch = curl_easy_init(); + + curl_easy_setopt(ch, CURLOPT_SSLCERTTYPE, "PEM"); + curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L); + curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/"); + + curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function); + curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem); + rv = curl_easy_perform(ch); + if(!rv) + printf("*** transfer succeeded ***\\n"); + else + printf("*** transfer failed ***\\n"); + + curl_easy_cleanup(ch); + curl_global_cleanup(); + return rv; +} +.fi +.SH HISTORY +Added in 7.11.0 for OpenSSL, in 7.42.0 for wolfSSL, in 7.54.0 for mbedTLS, +in 7.83.0 in BearSSL. +.SH AVAILABILITY +Added in curl 7.10.6 +.SH RETURN VALUE +CURLE_OK if supported; or an error such as: + +CURLE_NOT_BUILT_IN \- Not supported by the SSL backend + +CURLE_UNKNOWN_OPTION +.SH SEE ALSO +.BR CURLOPT_SSLVERSION (3), +.BR CURLOPT_SSL_CTX_FUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_CTX_FUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_CTX_FUNCTION.3 new file mode 100644 index 0000000..1567894 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_CTX_FUNCTION.3 @@ -0,0 +1,154 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_CTX_FUNCTION.md +.TH CURLOPT_SSL_CTX_FUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_CTX_FUNCTION \- SSL context callback +.SH SYNOPSIS +.nf +#include + +CURLcode ssl_ctx_callback(CURL *curl, void *ssl_ctx, void *clientp); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_FUNCTION, + ssl_ctx_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl just before the initialization +of an SSL connection after having processed all other SSL related options to +give a last chance to an application to modify the behavior of the SSL +initialization. The \fIssl_ctx\fP parameter is a pointer to the SSL library\(aqs +\fISSL_CTX\fP for OpenSSL or wolfSSL, a pointer to \fImbedtls_ssl_config\fP for +mbedTLS or a pointer to \fIbr_ssl_client_context\fP for BearSSL. If an error is +returned from the callback no attempt to establish a connection is made and +the perform operation returns the callback\(aqs error code. Set the \fIclientp\fP +argument passed in to this callback with the \fICURLOPT_SSL_CTX_DATA(3)\fP option. + +This function gets called for all new connections made to a server, during the +SSL negotiation. While \fIssl_ctx\fP points to a newly initialized object each +time, the pointer may still be the same as in a prior call. + +To use this callback, a non\-trivial amount of knowledge of your SSL library is +necessary. For example, you can use this function to call library\-specific +callbacks to add additional validation code for certificates, and even to +change the actual URI of an HTTPS request. + +For OpenSSL, asynchronous certificate verification via \fISSL_set_retry_verify\fP +is supported. (Added in 8.3.0) + +The \fICURLOPT_SSL_CTX_FUNCTION(3)\fP callback allows the application to reach in +and modify SSL details in the connection without libcurl itself knowing +anything about it, which then subsequently can lead to libcurl unknowingly +reusing SSL connections with different properties. To remedy this you may set +\fICURLOPT_FORBID_REUSE(3)\fP from the callback function. + +If you are using DNS\-over\-HTTPS (DoH) via \fICURLOPT_DOH_URL(3)\fP then this +callback is also called for those transfers and the curl handle is set to an +internal handle. \fBThis behavior is subject to change.\fP We recommend setting +\fICURLOPT_PRIVATE(3)\fP on your curl handle so you can identify it correctly in the +context callback. If you have a reason to modify DoH SSL context please let us +know on the curl\-library mailing list because we are considering removing this +capability. + +libcurl does not guarantee the lifetime of the passed in object once this +callback function has returned. Your application must not assume that it can +keep using the SSL context or data derived from it once this function is +completed. + +For libcurl builds using TLS backends that support CA caching and +\fICURLOPT_CA_CACHE_TIMEOUT(3)\fP is not set to zero, multiple calls to this +callback may be done with the same CA store in memory. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +BearSSL, OpenSSL, mbedTLS and wolfSSL +.SH EXAMPLE +.nf +/* OpenSSL specific */ + +#include +#include +#include + +static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm) +{ + X509_STORE *store; + X509 *cert = NULL; + BIO *bio; + char *mypem = parm; + /* get a BIO */ + bio = BIO_new_mem_buf(mypem, -1); + /* use it to read the PEM formatted certificate from memory into an + * X509 structure that SSL can use + */ + PEM_read_bio_X509(bio, &cert, 0, NULL); + if(!cert) + printf("PEM_read_bio_X509 failed...\\n"); + + /* get a pointer to the X509 certificate store (which may be empty) */ + store = SSL_CTX_get_cert_store((SSL_CTX *)sslctx); + + /* add our certificate to this store */ + if(X509_STORE_add_cert(store, cert) == 0) + printf("error adding certificate\\n"); + + /* decrease reference counts */ + X509_free(cert); + BIO_free(bio); + + /* all set to go */ + return CURLE_OK; +} + +int main(void) +{ + CURL *ch; + CURLcode rv; + char *mypem = /* example CA cert PEM - shortened */ + "-----BEGIN CERTIFICATE-----\\n" + "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\\n" + "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\\n" + "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\\n" + "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\\n" + "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\\n" + "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\\n" + "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\\n" + "-----END CERTIFICATE-----\\n"; + + curl_global_init(CURL_GLOBAL_ALL); + ch = curl_easy_init(); + + curl_easy_setopt(ch, CURLOPT_SSLCERTTYPE, "PEM"); + curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L); + curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/"); + + curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function); + curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem); + rv = curl_easy_perform(ch); + if(!rv) + printf("*** transfer succeeded ***\\n"); + else + printf("*** transfer failed ***\\n"); + + curl_easy_cleanup(ch); + curl_global_cleanup(); + return rv; +} +.fi +.SH AVAILABILITY +Added in curl 7.10.6 +.SH RETURN VALUE +CURLE_OK if supported; or an error such as: + +CURLE_NOT_BUILT_IN \- Not supported by the SSL backend +.SH SEE ALSO +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_CAINFO_BLOB (3), +.BR CURLOPT_CA_CACHE_TIMEOUT (3), +.BR CURLOPT_SSL_CTX_DATA (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_EC_CURVES.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_EC_CURVES.3 new file mode 100644 index 0000000..1b4a2c7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_EC_CURVES.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_EC_CURVES.md +.TH CURLOPT_SSL_EC_CURVES 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_EC_CURVES \- key exchange curves +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_EC_CURVES, char *list); +.fi +.SH DESCRIPTION +Pass a string as parameter with a colon delimited list of Elliptic curve (EC) +algorithms. This option defines the client\(aqs key exchange algorithms in the +SSL handshake (if the SSL backend libcurl is built to use supports it). + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to restore back to internal default. +.SH DEFAULT +\&"", embedded in SSL backend +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSL_EC_CURVES, "X25519:P-521"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.73.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_SSL_CIPHER_LIST (3), +.BR CURLOPT_SSL_OPTIONS (3), +.BR CURLOPT_TLS13_CIPHERS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_ENABLE_ALPN.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_ENABLE_ALPN.3 new file mode 100644 index 0000000..f92bf44 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_ENABLE_ALPN.3 @@ -0,0 +1,41 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_ENABLE_ALPN.md +.TH CURLOPT_SSL_ENABLE_ALPN 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_ENABLE_ALPN \- Application Layer Protocol Negotiation +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_ENABLE_ALPN, long npn); +.fi +.SH DESCRIPTION +Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This +option enables/disables ALPN in the SSL handshake (if the SSL backend libcurl +is built to use supports it), which can be used to negotiate http2. +.SH DEFAULT +1, enabled +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSL_ENABLE_ALPN, 0L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.36.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_SSL_ENABLE_NPN (3), +.BR CURLOPT_SSL_OPTIONS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_ENABLE_NPN.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_ENABLE_NPN.3 new file mode 100644 index 0000000..f3d4db9 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_ENABLE_NPN.3 @@ -0,0 +1,45 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_ENABLE_NPN.md +.TH CURLOPT_SSL_ENABLE_NPN 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_ENABLE_NPN \- use NPN +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_ENABLE_NPN, long npn); +.fi +.SH DESCRIPTION +Deprecated since 7.86.0. Setting this option has no function. + +Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This +option enables/disables NPN in the SSL handshake (if the SSL backend libcurl +is built to use supports it), which can be used to negotiate http2. +.SH DEFAULT +1, enabled +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSL_ENABLE_NPN, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH DEPRECATED +Deprecated since 7.86.0. +.SH AVAILABILITY +Added in curl 7.36.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_SSL_ENABLE_ALPN (3), +.BR CURLOPT_SSL_OPTIONS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_FALSESTART.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_FALSESTART.3 new file mode 100644 index 0000000..800992c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_FALSESTART.3 @@ -0,0 +1,43 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_FALSESTART.md +.TH CURLOPT_SSL_FALSESTART 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_FALSESTART \- TLS false start +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_FALSESTART, long enable); +.fi +.SH DESCRIPTION +Pass a long as parameter set to 1L to enable or 0 to disable. + +This option determines whether libcurl should use false start during the TLS +handshake. False start is a mode where a TLS client starts sending application +data before verifying the server\(aqs Finished message, thus saving a round trip +when performing a full handshake. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +Secure Transport +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_SSL_FALSESTART, 1L); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.42.0 +.SH RETURN VALUE +Returns CURLE_OK if false start is supported by the SSL backend, otherwise +returns CURLE_NOT_BUILT_IN. +.SH SEE ALSO +.BR CURLOPT_TCP_FASTOPEN (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_OPTIONS.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_OPTIONS.3 new file mode 100644 index 0000000..c142439 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_OPTIONS.3 @@ -0,0 +1,85 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_OPTIONS.md +.TH CURLOPT_SSL_OPTIONS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_OPTIONS \- SSL behavior options +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_OPTIONS, long bitmask); +.fi +.SH DESCRIPTION +Pass a long with a bitmask to tell libcurl about specific SSL +behaviors. Available bits: +.IP CURLSSLOPT_ALLOW_BEAST +Tells libcurl to not attempt to use any workarounds for a security flaw in the +SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0, +the SSL layer libcurl uses may use a work\-around for this flaw although it +might cause interoperability problems with some (older) SSL implementations. +WARNING: avoiding this work\-around lessens the security, and by setting this +option to 1 you ask for exactly that. This option is only supported for Secure +Transport and OpenSSL. +.IP CURLSSLOPT_NO_REVOKE +Tells libcurl to disable certificate revocation checks for those SSL backends +where such behavior is present. This option is only supported for Schannel +(the native Windows SSL library), with an exception in the case of Windows\(aq +Untrusted Publishers block list which it seems cannot be bypassed. (Added in +7.44.0) +.IP CURLSSLOPT_NO_PARTIALCHAIN +Tells libcurl to not accept "partial" certificate chains, which it otherwise +does by default. This option is only supported for OpenSSL and fails the +certificate verification if the chain ends with an intermediate certificate +and not with a root cert. (Added in 7.68.0) +.IP CURLSSLOPT_REVOKE_BEST_EFFORT +Tells libcurl to ignore certificate revocation checks in case of missing or +offline distribution points for those SSL backends where such behavior is +present. This option is only supported for Schannel (the native Windows SSL +library). If combined with \fICURLSSLOPT_NO_REVOKE\fP, the latter takes +precedence. (Added in 7.70.0) +.IP CURLSSLOPT_NATIVE_CA +Tell libcurl to use the operating system\(aqs native CA store for certificate +verification. If you set this option and also set a CA certificate file or +directory then during verification those certificates are searched in addition +to the native CA store. + +Works with wolfSSL on Windows, Linux (Debian, Ubuntu, Gentoo, Fedora, RHEL), +macOS, Android and iOS (added in 8.3.0), with GnuTLS (added in 8.5.0) or on +Windows when built to use OpenSSL (Added in 7.71.0). +.IP CURLSSLOPT_AUTO_CLIENT_CERT +Tell libcurl to automatically locate and use a client certificate for +authentication, when requested by the server. This option is only supported +for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the +default behavior in libcurl with Schannel. Since the server can request any +certificate that supports client authentication in the OS certificate store it +could be a privacy violation and unexpected. +(Added in 7.77.0) +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* weaken TLS only for use with silly servers */ + curl_easy_setopt(curl, CURLOPT_SSL_OPTIONS, (long)CURLSSLOPT_ALLOW_BEAST | + CURLSSLOPT_NO_REVOKE); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.25.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSL_OPTIONS (3), +.BR CURLOPT_SSLVERSION (3), +.BR CURLOPT_SSL_CIPHER_LIST (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_SESSIONID_CACHE.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_SESSIONID_CACHE.3 new file mode 100644 index 0000000..e15569a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_SESSIONID_CACHE.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_SESSIONID_CACHE.md +.TH CURLOPT_SSL_SESSIONID_CACHE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_SESSIONID_CACHE \- use the SSL session\-ID cache +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_SESSIONID_CACHE, + long enabled); +.fi +.SH DESCRIPTION +Pass a long set to 0 to disable libcurl\(aqs use of SSL session\-ID caching. Set +this to 1 to enable it. By default all transfers are done using the cache +enabled. While nothing ever should get hurt by attempting to reuse SSL +session\-IDs, there seem to be or have been broken SSL implementations in the +wild that may require you to disable this in order for you to succeed. +.SH DEFAULT +1 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* switch off session-id use! */ + curl_easy_setopt(curl, CURLOPT_SSL_SESSIONID_CACHE, 0L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_DNS_CACHE_TIMEOUT (3), +.BR CURLOPT_MAXAGE_CONN (3), +.BR CURLOPT_MAXLIFETIME_CONN (3), +.BR CURLOPT_SSLVERSION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_VERIFYHOST.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_VERIFYHOST.3 new file mode 100644 index 0000000..ece859b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_VERIFYHOST.3 @@ -0,0 +1,95 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_VERIFYHOST.md +.TH CURLOPT_SSL_VERIFYHOST 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_VERIFYHOST \- verify the certificate\(aqs name against host +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYHOST, long verify); +.fi +.SH DESCRIPTION +Pass a long set to 2L to make libcurl verify the host in the server\(aqs TLS +certificate. + +When negotiating a TLS connection, the server sends a certificate indicating +its identity. + +When \fICURLOPT_SSL_VERIFYHOST(3)\fP is set to 1 or 2, the server certificate must +indicate that it was made for the hostname or address curl connects to, or the +connection fails. Simply put, it means it has to have the same name in the +certificate as is used in the URL you operate against. + +curl considers the server the intended one when the Common Name field or a +Subject Alternate Name field in the certificate matches the hostname in the +URL to which you told curl to connect. + +When the \fIverify\fP value is 0, the connection succeeds regardless of the names +in the certificate. Use that ability with caution, + +This option controls checking the server\(aqs certificate\(aqs claimed identity. The +separate \fICURLOPT_SSL_VERIFYPEER(3)\fP options enables/disables verification that +the certificate is signed by a trusted Certificate Authority. + +WARNING: disabling verification of the certificate allows bad guys to +man\-in\-the\-middle the communication without you knowing it. Disabling +verification makes the communication insecure. Just having encryption on a +transfer is not enough as you cannot be sure that you are communicating with +the correct end\-point. + +When libcurl uses secure protocols it trusts responses and allows for example +HSTS and Alt\-Svc information to be stored and used subsequently. Disabling +certificate verification can make libcurl trust and use such information from +malicious servers. +.SH MATCHING +A certificate can have the name as a wildcard. The only asterisk (\fI*\fP) must +then be the left\-most character and it must be followed by a period. The +wildcard must further contain more than one period as it cannot be set for a +top\-level domain. + +A certificate can be set for a numerical IP address (IPv4 or IPv6), but then +it should be a Subject Alternate Name kind and its type should correctly +identify the field as an IP address. +.SH LIMITATIONS +Secure Transport: If \fIverify\fP value is 0, then SNI is also disabled. SNI is a +TLS extension that sends the hostname to the server. The server may use that +information to do such things as sending back a specific certificate for the +hostname, or forwarding the request to a specific origin server. Some +hostnames may be inaccessible if SNI is not sent. +.SH DEFAULT +2 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the default value: strict name check please */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 2L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.8.1 +.SH HISTORY +In 7.28.0 and earlier: the value 1 was treated as a debug option of some +sorts, not supported anymore due to frequently leading to programmer mistakes. + +From 7.28.1 to 7.65.3: setting it to 1 made \fIcurl_easy_setopt(3)\fP return +an error and leaving the flag untouched. + +From 7.66.0: libcurl treats 1 and 2 to this option the same. +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_PINNEDPUBLICKEY (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_VERIFYPEER.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_VERIFYPEER.3 new file mode 100644 index 0000000..7736b71 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_VERIFYPEER.3 @@ -0,0 +1,79 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_VERIFYPEER.md +.TH CURLOPT_SSL_VERIFYPEER 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_VERIFYPEER \- verify the peer\(aqs SSL certificate +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYPEER, long verify); +.fi +.SH DESCRIPTION +Pass a long as parameter to enable or disable. + +This option determines whether curl verifies the authenticity of the peer\(aqs +certificate. A value of 1 means curl verifies; 0 (zero) means it does not. + +When negotiating a TLS or SSL connection, the server sends a certificate +indicating its identity. Curl verifies whether the certificate is authentic, +i.e. that you can trust that the server is who the certificate says it is. +This trust is based on a chain of digital signatures, rooted in certification +authority (CA) certificates you supply. curl uses a default bundle of CA +certificates (the path for that is determined at build time) and you can +specify alternate certificates with the \fICURLOPT_CAINFO(3)\fP option or the +\fICURLOPT_CAPATH(3)\fP option. + +When \fICURLOPT_SSL_VERIFYPEER(3)\fP is enabled, and the verification fails to +prove that the certificate is signed by a CA, the connection fails. + +When this option is disabled (set to zero), the CA certificates are not loaded +and the peer certificate verification is simply skipped. + +Authenticating the certificate is not enough to be sure about the server. You +typically also want to ensure that the server is the server you mean to be +talking to. Use \fICURLOPT_SSL_VERIFYHOST(3)\fP for that. The check that the host +name in the certificate is valid for the hostname you are connecting to is +done independently of the \fICURLOPT_SSL_VERIFYPEER(3)\fP option. + +WARNING: disabling verification of the certificate allows bad guys to +man\-in\-the\-middle the communication without you knowing it. Disabling +verification makes the communication insecure. Just having encryption on a +transfer is not enough as you cannot be sure that you are communicating with +the correct end\-point. + +When libcurl uses secure protocols it trusts responses and allows for example +HSTS and Alt\-Svc information to be stored and used subsequently. Disabling +certificate verification can make libcurl trust and use such information from +malicious servers. +.SH DEFAULT +1 \- enabled +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +All TLS backends support this option. +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the default value: strict certificate check please */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.4.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_CAINFO (3), +.BR CURLINFO_CAPATH (3), +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), +.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), +.BR CURLOPT_SSL_VERIFYHOST (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SSL_VERIFYSTATUS.3 b/3rdparty/curl/share/man/man3/CURLOPT_SSL_VERIFYSTATUS.3 new file mode 100644 index 0000000..0b226d3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SSL_VERIFYSTATUS.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SSL_VERIFYSTATUS.md +.TH CURLOPT_SSL_VERIFYSTATUS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SSL_VERIFYSTATUS \- verify the certificate\(aqs status +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYSTATUS, long verify); +.fi +.SH DESCRIPTION +Pass a long as parameter set to 1 to enable or 0 to disable. + +This option determines whether libcurl verifies the status of the server cert +using the "Certificate Status Request" TLS extension (aka. OCSP stapling). + +Note that if this option is enabled but the server does not support the TLS +extension, the verification fails. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* ask for OCSP stapling! */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYSTATUS, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.41.0 +.SH RETURN VALUE +Returns CURLE_OK if OCSP stapling is supported by the SSL backend, otherwise +returns CURLE_NOT_BUILT_IN. +.SH SEE ALSO +.BR CURLOPT_CAINFO (3), +.BR CURLOPT_SSL_VERIFYHOST (3), +.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_STDERR.3 b/3rdparty/curl/share/man/man3/CURLOPT_STDERR.3 new file mode 100644 index 0000000..662807a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_STDERR.3 @@ -0,0 +1,44 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_STDERR.md +.TH CURLOPT_STDERR 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_STDERR \- redirect stderr to another stream +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STDERR, FILE *stream); +.fi +.SH DESCRIPTION +Pass a FILE * as parameter. Tell libcurl to use this \fIstream\fP instead of +stderr when showing the progress meter and displaying \fICURLOPT_VERBOSE(3)\fP +data. + +If you are using libcurl as a Windows DLL, this option causes an exception and +a crash in the library since it cannot access a FILE * passed on from the +application. A work\-around is to instead use \fICURLOPT_DEBUGFUNCTION(3)\fP. +.SH DEFAULT +stderr +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + FILE *filep = fopen("dump", "wb"); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_STDERR, filep); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_NOPROGRESS (3), +.BR CURLOPT_VERBOSE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_STREAM_DEPENDS.3 b/3rdparty/curl/share/man/man3/CURLOPT_STREAM_DEPENDS.3 new file mode 100644 index 0000000..bf1bf8d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_STREAM_DEPENDS.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_STREAM_DEPENDS.md +.TH CURLOPT_STREAM_DEPENDS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_STREAM_DEPENDS \- stream this transfer depends on +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_DEPENDS, + CURL *dephandle); +.fi +.SH DESCRIPTION +Pass a CURL pointer in \fIdephandle\fP to identify the stream within the same +connection that this stream is depending upon. This option clears the +exclusive bit and is mutually exclusive to the \fICURLOPT_STREAM_DEPENDS_E(3)\fP +option. + +The spec says "Including a dependency expresses a preference to allocate +resources to the identified stream rather than to the dependent stream." + +This option can be set during transfer. + +\fIdephandle\fP must not be the same as \fIhandle\fP, that makes this function return +an error. It must be another easy handle, and it also needs to be a handle of +a transfer that is about to be sent over the same HTTP/2 connection for this +option to have an actual effect. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + CURL *curl2 = curl_easy_init(); /* a second handle */ + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); + + /* the second depends on the first */ + curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); + curl_easy_setopt(curl2, CURLOPT_STREAM_DEPENDS, curl); + + /* then add both to a multi handle and transfer them! */ + } +} +.fi +.SH AVAILABILITY +Added in curl 7.46.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_PIPELINING (3), +.BR CURLOPT_HTTP_VERSION (3), +.BR CURLOPT_STREAM_DEPENDS_E (3), +.BR CURLOPT_STREAM_WEIGHT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_STREAM_DEPENDS_E.3 b/3rdparty/curl/share/man/man3/CURLOPT_STREAM_DEPENDS_E.3 new file mode 100644 index 0000000..dad4ed4 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_STREAM_DEPENDS_E.3 @@ -0,0 +1,59 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_STREAM_DEPENDS_E.md +.TH CURLOPT_STREAM_DEPENDS_E 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_STREAM_DEPENDS_E \- stream this transfer depends on exclusively +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_DEPENDS_E, + CURL *dephandle); +.fi +.SH DESCRIPTION +Pass a CURL pointer in \fIdephandle\fP to identify the stream within the same +connection that this stream is depending upon exclusively. That means it +depends on it and sets the Exclusive bit. + +The spec says "Including a dependency expresses a preference to allocate +resources to the identified stream rather than to the dependent stream." + +Setting a dependency with the exclusive flag for a reprioritized stream causes +all the dependencies of the new parent stream to become dependent on the +reprioritized stream. + +This option can be set during transfer. + +\fIdephandle\fP must not be the same as \fIhandle\fP, that makes this function return +an error. It must be another easy handle, and it also needs to be a handle of +a transfer that is about to be sent over the same HTTP/2 connection for this +option to have an actual effect. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + CURL *curl2 = curl_easy_init(); /* a second handle */ + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); + + /* the second depends on the first */ + curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); + curl_easy_setopt(curl2, CURLOPT_STREAM_DEPENDS_E, curl); + + /* then add both to a multi handle and transfer them! */ + } +} +.fi +.SH AVAILABILITY +Added in curl 7.46.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_PIPELINING (3), +.BR CURLOPT_HTTP_VERSION (3), +.BR CURLOPT_STREAM_DEPENDS (3), +.BR CURLOPT_STREAM_WEIGHT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_STREAM_WEIGHT.3 b/3rdparty/curl/share/man/man3/CURLOPT_STREAM_WEIGHT.3 new file mode 100644 index 0000000..f041542 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_STREAM_WEIGHT.3 @@ -0,0 +1,59 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_STREAM_WEIGHT.md +.TH CURLOPT_STREAM_WEIGHT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_STREAM_WEIGHT \- numerical stream weight +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_WEIGHT, long weight); +.fi +.SH DESCRIPTION +Set the long \fIweight\fP to a number between 1 and 256. + +When using HTTP/2, this option sets the individual weight for this particular +stream used by the easy \fIhandle\fP. Setting and using weights only makes +sense and is only usable when doing multiple streams over the same +connections, which thus implies that you use \fICURLMOPT_PIPELINING(3)\fP. + +This option can be set during transfer and causes the updated weight info get +sent to the server the next time an HTTP/2 frame is sent to the server. + +See section 5.3 of RFC 7540 for protocol details. + +Streams with the same parent should be allocated resources proportionally +based on their weight. If you have two streams going, stream A with weight 16 +and stream B with weight 32, stream B gets two thirds (32/48) of the available +bandwidth (assuming the server can send off the data equally for both +streams). +.SH DEFAULT +16 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + CURL *curl2 = curl_easy_init(); /* a second handle */ + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); + curl_easy_setopt(curl, CURLOPT_STREAM_WEIGHT, 10L); + + /* the second has twice the weight */ + curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); + curl_easy_setopt(curl2, CURLOPT_STREAM_WEIGHT, 20L); + + /* then add both to a multi handle and transfer them! */ + } +} +.fi +.SH AVAILABILITY +Added in curl 7.46.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLMOPT_PIPELINING (3), +.BR CURLOPT_PIPEWAIT (3), +.BR CURLOPT_STREAM_DEPENDS (3), +.BR CURLOPT_STREAM_DEPENDS_E (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 b/3rdparty/curl/share/man/man3/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 new file mode 100644 index 0000000..46708df --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 @@ -0,0 +1,82 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_SUPPRESS_CONNECT_HEADERS.md +.TH CURLOPT_SUPPRESS_CONNECT_HEADERS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_SUPPRESS_CONNECT_HEADERS \- suppress proxy CONNECT response headers +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SUPPRESS_CONNECT_HEADERS, long onoff); +.fi +.SH DESCRIPTION +When \fICURLOPT_HTTPPROXYTUNNEL(3)\fP is used and a CONNECT request is made, +suppress proxy CONNECT response headers from the user callback functions +\fICURLOPT_HEADERFUNCTION(3)\fP and \fICURLOPT_WRITEFUNCTION(3)\fP. + +Proxy CONNECT response headers can complicate header processing since it is +essentially a separate set of headers. You can enable this option to suppress +those headers. + +For example let\(aqs assume an HTTPS URL is to be retrieved via CONNECT. On +success there would normally be two sets of headers, and each header line sent +to the header function and/or the write function. The data given to the +callbacks would look like this: + +.nf +HTTP/1.1 200 Connection established +{headers} +\&... + +HTTP/1.1 200 OK +Content-Type: application/json +{headers} +\&... + +{body} +\&... +.fi + +However by enabling this option the CONNECT response headers are suppressed, +so the data given to the callbacks would look like this: + +.nf +HTTP/1.1 200 OK +Content-Type: application/json +{headers} +\&... + +{body} +\&... +.fi +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_HEADER, 1L); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://foo:3128"); + curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L); + curl_easy_setopt(curl, CURLOPT_SUPPRESS_CONNECT_HEADERS, 1L); + + curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.54.0 +.SH RETURN VALUE +CURLE_OK or an error such as CURLE_UNKNOWN_OPTION. +.SH SEE ALSO +.BR CURLOPT_HEADER (3), +.BR CURLOPT_HTTPPROXYTUNNEL (3), +.BR CURLOPT_PROXY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TCP_FASTOPEN.3 b/3rdparty/curl/share/man/man3/CURLOPT_TCP_FASTOPEN.3 new file mode 100644 index 0000000..aa537a1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TCP_FASTOPEN.3 @@ -0,0 +1,44 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TCP_FASTOPEN.md +.TH CURLOPT_TCP_FASTOPEN 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TCP_FASTOPEN \- TCP Fast Open +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_FASTOPEN, long enable); +.fi +.SH DESCRIPTION +Pass a long as parameter set to 1L to enable or 0 to disable. + +TCP Fast Open (RFC 7413) is a mechanism that allows data to be carried in the +SYN and SYN\-ACK packets and consumed by the receiving end during the initial +connection handshake, saving up to one full round\-trip time (RTT). + +Beware: the TLS session cache does not work when TCP Fast Open is enabled. TCP +Fast Open is also known to be problematic on or across certain networks. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects tcp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_TCP_FASTOPEN, 1L); + curl_easy_perform(curl); + } +} +.fi +.SH NOTES +This option is only supported on Linux and macOS 10.11 or later. +.SH AVAILABILITY +Added in curl 7.49.0 +.SH RETURN VALUE +Returns CURLE_OK if fast open is supported by the operating system, otherwise +returns CURLE_NOT_BUILT_IN. +.SH SEE ALSO +.BR CURLOPT_SSL_FALSESTART (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPALIVE.3 b/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPALIVE.3 new file mode 100644 index 0000000..f2b5cd4 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPALIVE.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TCP_KEEPALIVE.md +.TH CURLOPT_TCP_KEEPALIVE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TCP_KEEPALIVE \- TCP keep\-alive probing +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPALIVE, long probe); +.fi +.SH DESCRIPTION +Pass a long. If set to 1, TCP keepalive probes are used. The delay and +frequency of these probes can be controlled by the +\fICURLOPT_TCP_KEEPIDLE(3)\fP, \fICURLOPT_TCP_KEEPINTVL(3)\fP, and \fICURLOPT_TCP_KEEPCNT(3)\fP +options, provided the operating system supports them. Set to 0 (default behavior) +to disable keepalive probes. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects tcp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable TCP keep-alive for this transfer */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); + + /* keep-alive idle time to 120 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); + + /* interval time between keep-alive probes: 60 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); + + /* maximum number of keep-alive probes: 3 */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.25.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), +.BR CURLOPT_TCP_KEEPCNT (3), +.BR CURLOPT_TCP_KEEPIDLE (3), +.BR CURLOPT_TCP_KEEPINTVL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPCNT.3 b/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPCNT.3 new file mode 100644 index 0000000..6353740 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPCNT.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TCP_KEEPCNT.md +.TH CURLOPT_TCP_KEEPCNT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TCP_KEEPCNT \- Maximum number of TCP keep\-alive probes +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPCNT, long cnt); +.fi +.SH DESCRIPTION +Pass a long. Sets the number of probes to send before dropping +the connection. Not all operating systems support this option. +(Added in 8.9.0) + +The maximum value this option accepts is INT_MAX or whatever your +system allows. +Any larger value is capped to this amount. +.SH DEFAULT +9 +.SH PROTOCOLS +This functionality affects tcp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable TCP keep-alive for this transfer */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); + + /* set keep-alive idle time to 120 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); + + /* interval time between keep-alive probes: 60 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); + + /* maximum number of keep-alive probes: 3 */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 8.9.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_TCP_KEEPALIVE (3), +.BR CURLOPT_TCP_KEEPIDLE (3), +.BR CURLOPT_TCP_KEEPINTVL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPIDLE.3 b/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPIDLE.3 new file mode 100644 index 0000000..87c4e58 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPIDLE.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TCP_KEEPIDLE.md +.TH CURLOPT_TCP_KEEPIDLE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TCP_KEEPIDLE \- TCP keep\-alive idle time wait +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPIDLE, long delay); +.fi +.SH DESCRIPTION +Pass a long. Sets the \fIdelay\fP, in seconds, to wait while the connection is +idle before sending keepalive probes. Not all operating systems support this +option. + +The maximum value this accepts is 2147483648. Any larger value is capped to +this amount. +.SH DEFAULT +60 +.SH PROTOCOLS +This functionality affects tcp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable TCP keep-alive for this transfer */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); + + /* set keep-alive idle time to 120 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); + + /* interval time between keep-alive probes: 60 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); + + /* maximum number of keep-alive probes: 3 */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.25.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_TCP_KEEPALIVE (3), +.BR CURLOPT_TCP_KEEPCNT (3), +.BR CURLOPT_TCP_KEEPINTVL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPINTVL.3 b/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPINTVL.3 new file mode 100644 index 0000000..8db1716 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TCP_KEEPINTVL.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TCP_KEEPINTVL.md +.TH CURLOPT_TCP_KEEPINTVL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TCP_KEEPINTVL \- TCP keep\-alive interval +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPINTVL, long interval); +.fi +.SH DESCRIPTION +Pass a long. Sets the interval, in seconds, to wait between sending keepalive +probes. Not all operating systems support this option. (Added in 7.25.0) + +The maximum value this accepts is 2147483648. Any larger value is capped to +this amount. +.SH DEFAULT +60 +.SH PROTOCOLS +This functionality affects tcp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable TCP keep-alive for this transfer */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); + + /* set keep-alive idle time to 120 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); + + /* interval time between keep-alive probes: 60 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); + + /* maximum number of keep-alive probes: 3 */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.25.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_TCP_KEEPALIVE (3), +.BR CURLOPT_TCP_KEEPCNT (3), +.BR CURLOPT_TCP_KEEPIDLE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TCP_NODELAY.3 b/3rdparty/curl/share/man/man3/CURLOPT_TCP_NODELAY.3 new file mode 100644 index 0000000..487fddb --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TCP_NODELAY.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TCP_NODELAY.md +.TH CURLOPT_TCP_NODELAY 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TCP_NODELAY \- the TCP_NODELAY option +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_NODELAY, long nodelay); +.fi +.SH DESCRIPTION +Pass a long specifying whether the \fITCP_NODELAY\fP option is to be set or +cleared (1L = set, 0 = clear). The option is set by default. This has no +effect after the connection has been established. + +Setting this option to 1L disables the Nagle algorithm on connections created +using this handle. The purpose of this algorithm is to minimize the number of +small packets on the network (where "small packets" means TCP segments less +than the Maximum Segment Size for the network). + +Maximizing the amount of data sent per TCP segment is good because it +amortizes the overhead of the send. However, in some cases small segments may +need to be sent without delay. This is less efficient than sending larger +amounts of data at a time, and can contribute to congestion on the network if +overdone. +.SH DEFAULT +1 +.SH PROTOCOLS +This functionality affects tcp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* leave Nagle enabled */ + curl_easy_setopt(curl, CURLOPT_TCP_NODELAY, 0); + curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +The default was changed to 1 from 0 in 7.50.2. +.SH AVAILABILITY +Added in curl 7.11.2 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_BUFFERSIZE (3), +.BR CURLOPT_SOCKOPTFUNCTION (3), +.BR CURLOPT_TCP_KEEPALIVE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TELNETOPTIONS.3 b/3rdparty/curl/share/man/man3/CURLOPT_TELNETOPTIONS.3 new file mode 100644 index 0000000..71c046d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TELNETOPTIONS.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TELNETOPTIONS.md +.TH CURLOPT_TELNETOPTIONS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TELNETOPTIONS \- set of telnet options +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TELNETOPTIONS, + struct curl_slist *cmds); +.fi +.SH DESCRIPTION +Provide a pointer to a curl_slist with variables to pass to the telnet +negotiations. The variables should be in the format . libcurl +supports the options \fBTTYPE\fP, \fBXDISPLOC\fP and \fBNEW_ENV\fP. See the TELNET +standard for details. + +Using this option multiple times makes the last set list override the previous +ones. Set it to NULL to disable its use again. + +libcurl does not copy the list, it needs to be kept around until after the +transfer has completed. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects telnet only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_slist *options; + options = curl_slist_append(NULL, "TTTYPE=vt100"); + options = curl_slist_append(options, "USER=foobar"); + curl_easy_setopt(curl, CURLOPT_URL, "telnet://example.com/"); + curl_easy_setopt(curl, CURLOPT_TELNETOPTIONS, options); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + curl_slist_free_all(options); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.7 +.SH RETURN VALUE +Returns CURLE_OK if TELNET is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_HTTPHEADER (3), +.BR CURLOPT_QUOTE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TFTP_BLKSIZE.3 b/3rdparty/curl/share/man/man3/CURLOPT_TFTP_BLKSIZE.3 new file mode 100644 index 0000000..5a582ca --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TFTP_BLKSIZE.3 @@ -0,0 +1,42 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TFTP_BLKSIZE.md +.TH CURLOPT_TFTP_BLKSIZE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TFTP_BLKSIZE \- TFTP block size +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_BLKSIZE, long blocksize); +.fi +.SH DESCRIPTION +Specify \fIblocksize\fP to use for TFTP data transmission. Valid range as per +RFC 2348 is 8\-65464 bytes. The default of 512 bytes is used if this option is +not specified. The specified block size is only used if supported by the +remote server. If the server does not return an option acknowledgment or +returns an option acknowledgment with no block size, the default of 512 bytes +is used. +.SH DEFAULT +512 +.SH PROTOCOLS +This functionality affects tftp only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "tftp://example.com/bootimage"); + /* try using larger blocks */ + curl_easy_setopt(curl, CURLOPT_TFTP_BLKSIZE, 2048L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_MAXFILESIZE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TFTP_NO_OPTIONS.3 b/3rdparty/curl/share/man/man3/CURLOPT_TFTP_NO_OPTIONS.3 new file mode 100644 index 0000000..88a796d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TFTP_NO_OPTIONS.3 @@ -0,0 +1,57 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TFTP_NO_OPTIONS.md +.TH CURLOPT_TFTP_NO_OPTIONS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TFTP_NO_OPTIONS \- send no TFTP options requests +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_NO_OPTIONS, long onoff); +.fi +.SH DESCRIPTION +Set \fIonoff\fP to 1L to exclude all TFTP options defined in RFC 2347, +RFC 2348 and RFC 2349 from read and write requests. + +This option improves interoperability with legacy servers that do not +acknowledge or properly implement TFTP options. When this option is used +\fICURLOPT_TFTP_BLKSIZE(3)\fP is ignored. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects tftp only +.SH EXAMPLE +.nf +size_t write_callback(char *ptr, size_t size, size_t nmemb, void *fp) +{ + return fwrite(ptr, size, nmemb, (FILE *)fp); +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + FILE *fp = fopen("foo.bin", "wb"); + if(fp) { + curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)fp); + curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback); + + curl_easy_setopt(curl, CURLOPT_URL, "tftp://example.com/foo.bin"); + + /* do not send TFTP options requests */ + curl_easy_setopt(curl, CURLOPT_TFTP_NO_OPTIONS, 1L); + + /* Perform the request */ + curl_easy_perform(curl); + + fclose(fp); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.48.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_TFTP_BLKSIZE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TIMECONDITION.3 b/3rdparty/curl/share/man/man3/CURLOPT_TIMECONDITION.3 new file mode 100644 index 0000000..1ba224f --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TIMECONDITION.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TIMECONDITION.md +.TH CURLOPT_TIMECONDITION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TIMECONDITION \- select condition for a time request +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMECONDITION, long cond); +.fi +.SH DESCRIPTION +Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE(3)\fP time +value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP +or \fICURL_TIMECOND_IFUNMODSINCE\fP. + +The last modification time of a file is not always known and in such instances +this feature has no effect even if the given time condition would not have +been met. \fIcurl_easy_getinfo(3)\fP with the \fICURLINFO_CONDITION_UNMET\fP +option can be used after a transfer to learn if a zero\-byte successful +\&"transfer" was due to this condition not matching. +.SH DEFAULT +CURL_TIMECOND_NONE (0) +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* January 1, 2020 is 1577833200 */ + curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); + + /* If-Modified-Since the above time stamp */ + curl_easy_setopt(curl, CURLOPT_TIMECONDITION, + (long)CURL_TIMECOND_IFMODSINCE); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLINFO_FILETIME (3), +.BR CURLOPT_TIMEVALUE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TIMEOUT.3 b/3rdparty/curl/share/man/man3/CURLOPT_TIMEOUT.3 new file mode 100644 index 0000000..80abc09 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TIMEOUT.3 @@ -0,0 +1,69 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TIMEOUT.md +.TH CURLOPT_TIMEOUT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TIMEOUT \- maximum time the transfer is allowed to complete +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT, long timeout); +.fi +.SH DESCRIPTION +Pass a long as parameter containing \fItimeout\fP \- the maximum time in +seconds that you allow the entire transfer operation to take. The whole thing, +from start to end. Normally, name lookups can take a considerable time and +limiting operations risk aborting perfectly normal operations. + +\fICURLOPT_TIMEOUT_MS(3)\fP is the same function but set in milliseconds. + +If both \fICURLOPT_TIMEOUT(3)\fP and \fICURLOPT_TIMEOUT_MS(3)\fP are set, the +value set last is used. + +Since this option puts a hard limit on how long time a request is allowed to +take, it has limited use in dynamic use cases with varying transfer +times. That is especially apparent when using the multi interface, which may +queue the transfer, and that time is included. You are advised to explore +\fICURLOPT_LOW_SPEED_LIMIT(3)\fP, \fICURLOPT_LOW_SPEED_TIME(3)\fP or using +\fICURLOPT_PROGRESSFUNCTION(3)\fP to implement your own timeout logic. + +The connection timeout set with \fICURLOPT_CONNECTTIMEOUT(3)\fP is included in +this general all\-covering timeout. + +With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 3 and \fICURLOPT_TIMEOUT(3)\fP set +to 5, the operation can never last longer than 5 seconds. + +With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 4 and \fICURLOPT_TIMEOUT(3)\fP set +to 2, the operation can never last longer than 2 seconds. + +This option may cause libcurl to use the SIGALRM signal to timeout system +calls on builds not using asynch DNS. In Unix\-like systems, this might cause +signals to be used unless \fICURLOPT_NOSIGNAL(3)\fP is set. +.SH DEFAULT +0 (zero) which means it never times out during transfer. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* complete within 20 seconds */ + curl_easy_setopt(curl, CURLOPT_TIMEOUT, 20L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative +value or a value that when converted to milliseconds is too large. +.SH SEE ALSO +.BR CURLOPT_CONNECTTIMEOUT (3), +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_TCP_KEEPALIVE (3), +.BR CURLOPT_TIMEOUT_MS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TIMEOUT_MS.3 b/3rdparty/curl/share/man/man3/CURLOPT_TIMEOUT_MS.3 new file mode 100644 index 0000000..2633d1b --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TIMEOUT_MS.3 @@ -0,0 +1,43 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TIMEOUT_MS.md +.TH CURLOPT_TIMEOUT_MS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TIMEOUT_MS \- maximum time the transfer is allowed to complete +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT_MS, long timeout); +.fi +.SH DESCRIPTION +Pass a long as parameter containing \fItimeout\fP \- the maximum time in +milliseconds that you allow the libcurl transfer operation to take. + +See \fICURLOPT_TIMEOUT(3)\fP for details. +.SH DEFAULT +0 (zero) which means it never times out during transfer. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* complete within 20000 milliseconds */ + curl_easy_setopt(curl, CURLOPT_TIMEOUT_MS, 20000L); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.16.2 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_CONNECTTIMEOUT (3), +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_TCP_KEEPALIVE (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TIMEVALUE.3 b/3rdparty/curl/share/man/man3/CURLOPT_TIMEVALUE.3 new file mode 100644 index 0000000..14f4d87 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TIMEVALUE.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TIMEVALUE.md +.TH CURLOPT_TIMEVALUE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TIMEVALUE \- time value for conditional +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEVALUE, long val); +.fi +.SH DESCRIPTION +Pass a long \fIval\fP as parameter. This should be the time counted as seconds +since 1 Jan 1970, and the time is used in a condition as specified with +\fICURLOPT_TIMECONDITION(3)\fP. + +On systems with 32\-bit \(aqlong\(aq variables (such as Windows), this option cannot +set dates beyond the year 2038. Consider \fICURLOPT_TIMEVALUE_LARGE(3)\fP +instead. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* January 1, 2020 is 1577833200 */ + curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); + + /* If-Modified-Since the above time stamp */ + curl_easy_setopt(curl, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_TIMECONDITION (3), +.BR CURLOPT_TIMEVALUE_LARGE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TIMEVALUE_LARGE.3 b/3rdparty/curl/share/man/man3/CURLOPT_TIMEVALUE_LARGE.3 new file mode 100644 index 0000000..60b9941 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TIMEVALUE_LARGE.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TIMEVALUE_LARGE.md +.TH CURLOPT_TIMEVALUE_LARGE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TIMEVALUE_LARGE \- time value for conditional +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEVALUE_LARGE, + curl_off_t val); +.fi +.SH DESCRIPTION +Pass a curl_off_t \fIval\fP as parameter. This should be the time counted as +seconds since 1 Jan 1970, and the time is used in a condition as specified +with \fICURLOPT_TIMECONDITION(3)\fP. + +The difference between this option and \fICURLOPT_TIMEVALUE(3)\fP is the type of the +argument. On systems where \(aqlong\(aq is only 32 bits wide, this option has to be +used to set dates beyond the year 2038. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* January 1, 2020 is 1577833200 */ + curl_easy_setopt(curl, CURLOPT_TIMEVALUE_LARGE, (curl_off_t)1577833200); + + /* If-Modified-Since the above time stamp */ + curl_easy_setopt(curl, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.59.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLINFO_FILETIME (3), +.BR CURLOPT_TIMECONDITION (3), +.BR CURLOPT_TIMEVALUE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TLS13_CIPHERS.3 b/3rdparty/curl/share/man/man3/CURLOPT_TLS13_CIPHERS.3 new file mode 100644 index 0000000..d78257c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TLS13_CIPHERS.3 @@ -0,0 +1,75 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TLS13_CIPHERS.md +.TH CURLOPT_TLS13_CIPHERS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TLS13_CIPHERS \- ciphers suites to use for TLS 1.3 +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLS13_CIPHERS, char *list); +.fi +.SH DESCRIPTION +Pass a char pointer, pointing to a null\-terminated string holding the list of +cipher suites to use for the TLS 1.3 connection. The list must be +syntactically correct, it consists of one or more cipher suite strings +separated by colons. + +For setting TLS 1.2 (1.1, 1.0) ciphers see \fICURLOPT_SSL_CIPHER_LIST(3)\fP. + +A valid example of a cipher list is: +.nf +"TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256" +.fi + +Find more details about cipher lists on this URL: + + https://curl.se/docs/ssl\-ciphers.html + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to restore to internal default. +.SH DEFAULT +NULL, use internal built\-in +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +OpenSSL, Schannel, mbedTLS, rustls and wolfSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_TLS13_CIPHERS, + "TLS_CHACHA20_POLY1305_SHA256"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +OpenSSL support added in 7.61.0, available when built with OpenSSL >= 1.1.1. +Schannel support added in 7.85.0. +LibreSSL support added in 8.3.0, available when built with LibreSSL >= 3.4.1. +wolfSSL support added in 8.10.0. +mbedTLS support added in 8.10.0, available when built with mbedTLS >= 3.6.0. +Rustls support added in 8.10.0. + +Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites where set +by using the \fICURLOPT_SSL_CIPHER_LIST(3)\fP option. +.SH AVAILABILITY +Added in curl 7.61.0 +.SH RETURN VALUE +Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSLVERSION (3), +.BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), +.BR CURLOPT_PROXY_TLS13_CIPHERS (3), +.BR CURLOPT_SSLVERSION (3), +.BR CURLOPT_SSL_CIPHER_LIST (3), +.BR CURLOPT_USE_SSL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TLSAUTH_PASSWORD.3 b/3rdparty/curl/share/man/man3/CURLOPT_TLSAUTH_PASSWORD.3 new file mode 100644 index 0000000..9837b55 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TLSAUTH_PASSWORD.3 @@ -0,0 +1,55 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TLSAUTH_PASSWORD.md +.TH CURLOPT_TLSAUTH_PASSWORD 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TLSAUTH_PASSWORD \- password to use for TLS authentication +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_PASSWORD, char *pwd); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should point to the null\-terminated +password to use for the TLS authentication method specified with the +\fICURLOPT_TLSAUTH_TYPE(3)\fP option. Requires that the \fICURLOPT_TLSAUTH_USERNAME(3)\fP +option also be set. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. + +This feature relies on TLS SRP which does not work with TLS 1.3. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.21.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PROXY_TLSAUTH_PASSWORD (3), +.BR CURLOPT_TLSAUTH_TYPE (3), +.BR CURLOPT_TLSAUTH_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TLSAUTH_TYPE.3 b/3rdparty/curl/share/man/man3/CURLOPT_TLSAUTH_TYPE.3 new file mode 100644 index 0000000..14e407a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TLSAUTH_TYPE.3 @@ -0,0 +1,56 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TLSAUTH_TYPE.md +.TH CURLOPT_TLSAUTH_TYPE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TLSAUTH_TYPE \- TLS authentication methods +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_TYPE, char *type); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. The string should be +the method of the TLS authentication. Supported method is "SRP". + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to restore to internal default. + +The application does not have to keep the string around after setting this +option. +.IP SRP +TLS\-SRP authentication. Secure Remote Password authentication for TLS is +defined in RFC 5054 and provides mutual authentication if both sides have a +shared secret. To use TLS\-SRP, you must also set the +\fICURLOPT_TLSAUTH_USERNAME(3)\fP and \fICURLOPT_TLSAUTH_PASSWORD(3)\fP options. + +TLS SRP does not work with TLS 1.3. +.SH DEFAULT +blank +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.21.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_TLSAUTH_PASSWORD (3), +.BR CURLOPT_TLSAUTH_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TLSAUTH_USERNAME.3 b/3rdparty/curl/share/man/man3/CURLOPT_TLSAUTH_USERNAME.3 new file mode 100644 index 0000000..deaf6e1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TLSAUTH_USERNAME.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TLSAUTH_USERNAME.md +.TH CURLOPT_TLSAUTH_USERNAME 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TLSAUTH_USERNAME \- username to use for TLS authentication +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_USERNAME, char *user); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should point to the null\-terminated +username to use for the TLS authentication method specified with the +\fICURLOPT_TLSAUTH_TYPE(3)\fP option. Requires that the \fICURLOPT_TLSAUTH_PASSWORD(3)\fP +option also be set. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. + +This feature relies on TLS SRP which does not work with TLS 1.3. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +This option works only with the following TLS backends: +GnuTLS and OpenSSL +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.21.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_TLSAUTH_PASSWORD (3), +.BR CURLOPT_TLSAUTH_TYPE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TRAILERDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_TRAILERDATA.3 new file mode 100644 index 0000000..cb4decc --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TRAILERDATA.3 @@ -0,0 +1,38 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TRAILERDATA.md +.TH CURLOPT_TRAILERDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TRAILERDATA \- pointer passed to trailing headers callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERDATA, void *userdata); +.fi +.SH DESCRIPTION +Data pointer to be passed to the HTTP trailer callback function. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +struct MyData { + void *custom; +}; + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct MyData data; + curl_easy_setopt(curl, CURLOPT_TRAILERDATA, &data); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.64.0 +.SH RETURN VALUE +Returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_TRAILERFUNCTION (3), +.BR CURLOPT_WRITEFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TRAILERFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_TRAILERFUNCTION.3 new file mode 100644 index 0000000..61f98dd --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TRAILERFUNCTION.3 @@ -0,0 +1,91 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TRAILERFUNCTION.md +.TH CURLOPT_TRAILERFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TRAILERFUNCTION \- callback for sending trailing headers +.SH SYNOPSIS +.nf +#include + +int curl_trailer_callback(struct curl_slist ** list, void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERFUNCTION, + curl_trailer_callback *func); +.fi +.SH DESCRIPTION +Pass a pointer to a callback function. + +This callback function is called once right before sending the final CR LF in +an HTTP chunked transfer to fill a list of trailing headers to be sent before +finishing the HTTP transfer. + +You can set the userdata argument with the \fICURLOPT_TRAILERDATA(3)\fP +option. + +The trailing headers included in the linked list must not be CRLF\-terminated, +because libcurl adds the appropriate line termination characters after each +header item. + +If you use \fIcurl_slist_append(3)\fP to add trailing headers to the \fIcurl_slist\fP +then libcurl duplicates the strings, and frees the \fIcurl_slist\fP once the +trailers have been sent. + +If one of the trailing header fields is not formatted correctly it is ignored +and an info message is emitted. + +The return value can either be \fBCURL_TRAILERFUNC_OK\fP or +\fBCURL_TRAILERFUNC_ABORT\fP which would respectively instruct libcurl to +either continue with sending the trailers or to abort the request. + +If you set this option to NULL, then the transfer proceeds as usual +without any interruptions. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +static int trailer_cb(struct curl_slist **tr, void *data) +{ + /* libcurl frees the list */ + *tr = curl_slist_append(*tr, "My-super-awesome-trailer: trailer-stuff"); + return CURL_TRAILERFUNC_OK; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + + /* Set the URL of the request */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* Now set it as a put */ + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + /* Assuming we have a function that returns the data to be pushed + Let that function be read_cb */ + curl_easy_setopt(curl, CURLOPT_READFUNCTION, trailer_cb); + + struct curl_slist *headers = NULL; + headers = curl_slist_append(headers, "Trailer: My-super-awesome-trailer"); + res = curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); + + /* Set the trailers filling callback */ + curl_easy_setopt(curl, CURLOPT_TRAILERFUNCTION, trailer_cb); + + /* Perform the transfer */ + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + + curl_slist_free_all(headers); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.64.0 +.SH RETURN VALUE +Returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_TRAILERDATA (3), +.BR CURLOPT_WRITEFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TRANSFERTEXT.3 b/3rdparty/curl/share/man/man3/CURLOPT_TRANSFERTEXT.3 new file mode 100644 index 0000000..bc74c37 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TRANSFERTEXT.3 @@ -0,0 +1,44 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TRANSFERTEXT.md +.TH CURLOPT_TRANSFERTEXT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TRANSFERTEXT \- request a text based transfer for FTP +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFERTEXT, long text); +.fi +.SH DESCRIPTION +A parameter set to 1 tells the library to use ASCII mode for FTP transfers, +instead of the default binary transfer. For Win32 systems it does not set the +stdout to binary mode. This option can be usable when transferring text data +between systems with different views on certain characters, such as newlines +or similar. + +libcurl does not do a complete ASCII conversion when doing ASCII transfers +over FTP. This is a known limitation/flaw that nobody has rectified. libcurl +simply sets the mode to ASCII and performs a standard transfer. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/textfile"); + curl_easy_setopt(curl, CURLOPT_TRANSFERTEXT, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1.1 +.SH RETURN VALUE +Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CRLF (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_TRANSFER_ENCODING.3 b/3rdparty/curl/share/man/man3/CURLOPT_TRANSFER_ENCODING.3 new file mode 100644 index 0000000..66dcb72 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_TRANSFER_ENCODING.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_TRANSFER_ENCODING.md +.TH CURLOPT_TRANSFER_ENCODING 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_TRANSFER_ENCODING \- ask for HTTP Transfer Encoding +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFER_ENCODING, + long enable); +.fi +.SH DESCRIPTION +Pass a long set to 1L to \fIenable\fP or 0 to disable. + +Adds a request for compressed Transfer Encoding in the outgoing HTTP +request. If the server supports this and so desires, it can respond with the +HTTP response sent using a compressed Transfer\-Encoding that is automatically +uncompressed by libcurl on reception. + +Transfer\-Encoding differs slightly from the Content\-Encoding you ask for with +\fICURLOPT_ACCEPT_ENCODING(3)\fP in that a Transfer\-Encoding is strictly meant +to be for the transfer and thus MUST be decoded before the data arrives in the +client. Traditionally, Transfer\-Encoding has been much less used and supported +by both HTTP clients and HTTP servers. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_TRANSFER_ENCODING, 1L); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.21.6 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_ACCEPT_ENCODING (3), +.BR CURLOPT_HTTP_TRANSFER_DECODING (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_UNIX_SOCKET_PATH.3 b/3rdparty/curl/share/man/man3/CURLOPT_UNIX_SOCKET_PATH.3 new file mode 100644 index 0000000..4c6e651 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_UNIX_SOCKET_PATH.3 @@ -0,0 +1,68 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_UNIX_SOCKET_PATH.md +.TH CURLOPT_UNIX_SOCKET_PATH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_UNIX_SOCKET_PATH \- Unix domain socket +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNIX_SOCKET_PATH, char *path); +.fi +.SH DESCRIPTION +Enables the use of Unix domain sockets as connection endpoint and sets the +path to \fIpath\fP. If \fIpath\fP is NULL, then Unix domain sockets are +disabled. + +When enabled, curl connects to the Unix domain socket instead of establishing +a TCP connection to the host. Since no network connection is created, curl +does not resolve the DNS hostname in the URL. + +The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms +it might be even less. + +Proxy and TCP options such as \fICURLOPT_TCP_NODELAY(3)\fP are not supported. Proxy +options such as \fICURLOPT_PROXY(3)\fP have no effect either as these are +TCP\-oriented, and asking a proxy server to connect to a certain Unix domain +socket is not possible. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL \- no Unix domain sockets are used. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_UNIX_SOCKET_PATH, "/tmp/httpd.sock"); + curl_easy_setopt(curl, CURLOPT_URL, "http://localhost/"); + + curl_easy_perform(curl); + } +} +.fi + +If you are on Linux and somehow have a need for paths larger than 107 bytes, +you can use the proc filesystem to bypass the limitation: + +.nf + int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY); + char path[108]; + snprintf(path, sizeof(path), "/proc/self/fd/%d/httpd.sock", dirfd); + curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path); + /* Be sure to keep dirfd valid until you discard the handle */ +.fi +.SH AVAILABILITY +Added in curl 7.40.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_ABSTRACT_UNIX_SOCKET (3), +.BR CURLOPT_OPENSOCKETFUNCTION (3), +.BR unix (7) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_UNRESTRICTED_AUTH.3 b/3rdparty/curl/share/man/man3/CURLOPT_UNRESTRICTED_AUTH.3 new file mode 100644 index 0000000..b39b028 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_UNRESTRICTED_AUTH.3 @@ -0,0 +1,64 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_UNRESTRICTED_AUTH.md +.TH CURLOPT_UNRESTRICTED_AUTH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_UNRESTRICTED_AUTH \- send credentials to other hosts too +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNRESTRICTED_AUTH, + long goahead); +.fi +.SH DESCRIPTION +Set the long \fIgohead\fP parameter to 1L to make libcurl continue to send +authentication (user+password) credentials or explicitly set cookie headers +when following locations, even when the host changes. This option is +meaningful only when setting \fICURLOPT_FOLLOWLOCATION(3)\fP. + +Further, when this option is not used or set to \fB0L\fP, libcurl does not send +custom nor internally generated \fIAuthentication:\fP or \fICookie:\fP headers on +requests done to other hosts than the one used for the initial URL. Another +host means that one or more of hostname, protocol scheme or port number +changed. + +By default, libcurl only sends \fIAuthentication:\fP or explicitly set \fICookie:\fP +headers to the initial host as given in the original URL, to avoid leaking +username + password to other sites. + +This option should be used with caution: when curl follows redirects it +blindly fetches the next URL as instructed by the server. Setting +\fICURLOPT_UNRESTRICTED_AUTH(3)\fP to 1L makes curl trust the server and sends +possibly sensitive credentials to any host the server points to, possibly +again and again as the following hosts can keep redirecting to new hosts. + +Due to the way HTTP works, almost any header can be made to contain data a +client may not want to pass on to other servers than the initially intended +host and for all other headers than the two mentioned above, there is no +protection from this happening when libcurl is told to follow redirects. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + curl_easy_setopt(curl, CURLOPT_UNRESTRICTED_AUTH, 1L); + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.10.4 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLINFO_REDIRECT_COUNT (3), +.BR CURLOPT_FOLLOWLOCATION (3), +.BR CURLOPT_MAXREDIRS (3), +.BR CURLOPT_REDIR_PROTOCOLS_STR (3), +.BR CURLOPT_USERPWD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_UPKEEP_INTERVAL_MS.3 b/3rdparty/curl/share/man/man3/CURLOPT_UPKEEP_INTERVAL_MS.3 new file mode 100644 index 0000000..04ca5fc --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_UPKEEP_INTERVAL_MS.3 @@ -0,0 +1,61 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_UPKEEP_INTERVAL_MS.md +.TH CURLOPT_UPKEEP_INTERVAL_MS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_UPKEEP_INTERVAL_MS \- connection upkeep interval +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPKEEP_INTERVAL_MS, + long upkeep_interval_ms); +.fi +.SH DESCRIPTION +Some protocols have "connection upkeep" mechanisms. These mechanisms usually +send some traffic on existing connections in order to keep them alive; this +can prevent connections from being closed due to overzealous firewalls, for +example. + +The user needs to explicitly call \fIcurl_easy_upkeep(3)\fP in order to +perform the upkeep work. + +Currently the only protocol with a connection upkeep mechanism is HTTP/2: when +the connection upkeep interval is exceeded and \fIcurl_easy_upkeep(3)\fP +is called, an HTTP/2 PING frame is sent on the connection. +.SH DEFAULT +CURL_UPKEEP_INTERVAL_DEFAULT (currently defined as 60000L, which is 60 seconds) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* Make a connection to an HTTP/2 server. */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the interval to 30000ms / 30s */ + curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L); + + curl_easy_perform(curl); + + /* Perform more work here. */ + + /* While the connection is being held open, curl_easy_upkeep() can be + called. If curl_easy_upkeep() is called and the time since the last + upkeep exceeds the interval, then an HTTP/2 PING is sent. */ + curl_easy_upkeep(curl); + + /* Perform more work here. */ + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.62.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_TCP_KEEPALIVE (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_UPLOAD.3 b/3rdparty/curl/share/man/man3/CURLOPT_UPLOAD.3 new file mode 100644 index 0000000..735183a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_UPLOAD.3 @@ -0,0 +1,76 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_UPLOAD.md +.TH CURLOPT_UPLOAD 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_UPLOAD \- data upload +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPLOAD, long upload); +.fi +.SH DESCRIPTION +The long parameter \fIupload\fP set to 1 tells the library to prepare for and +perform an upload. The \fICURLOPT_READDATA(3)\fP and \fICURLOPT_INFILESIZE(3)\fP or +\fICURLOPT_INFILESIZE_LARGE(3)\fP options are also interesting for uploads. If the +protocol is HTTP, uploading means using the PUT request unless you tell +libcurl otherwise. + +Using PUT with HTTP 1.1 implies the use of a "Expect: 100\-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. + +If you use PUT to an HTTP 1.1 server, you can upload data without knowing the +size before starting the transfer. The library enables this by adding a header +\&"Transfer\-Encoding: chunked". With HTTP 1.0 or if you prefer not to use +chunked transfer, you must specify the size of the data with +\fICURLOPT_INFILESIZE(3)\fP or \fICURLOPT_INFILESIZE_LARGE(3)\fP. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +static size_t read_cb(char *ptr, size_t size, size_t nmemb, void *userdata) +{ + FILE *src = userdata; + /* copy as much data as possible into the 'ptr' buffer, but no more than + 'size' * 'nmemb' bytes */ + size_t retcode = fread(ptr, size, nmemb, src); + + return retcode; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + FILE *src = fopen("local-file", "r"); + curl_off_t fsize; /* set this to the size of the input file */ + + /* we want to use our own read function */ + curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); + + /* enable uploading */ + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + /* specify target */ + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); + + /* now specify which pointer to pass to our callback */ + curl_easy_setopt(curl, CURLOPT_READDATA, src); + + /* Set the size of the file to upload */ + curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize); + + /* Now run off and do what you have been told! */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_INFILESIZE_LARGE (3), +.BR CURLOPT_PUT (3), +.BR CURLOPT_READFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_UPLOAD_BUFFERSIZE.3 b/3rdparty/curl/share/man/man3/CURLOPT_UPLOAD_BUFFERSIZE.3 new file mode 100644 index 0000000..38dc235 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_UPLOAD_BUFFERSIZE.3 @@ -0,0 +1,59 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_UPLOAD_BUFFERSIZE.md +.TH CURLOPT_UPLOAD_BUFFERSIZE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_UPLOAD_BUFFERSIZE \- upload buffer size +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPLOAD_BUFFERSIZE, long size); +.fi +.SH DESCRIPTION +Pass a long specifying your preferred \fIsize\fP (in bytes) for the upload +buffer in libcurl. It makes libcurl uses a larger buffer that gets passed to +the next layer in the stack to get sent off. In some setups and for some +protocols, there is a huge performance benefit of having a larger upload +buffer. + +This is just treated as a request, not an order. You cannot be guaranteed to +actually get the given size. + +The upload buffer size is by default 64 kilobytes. The maximum buffer size +allowed to be set is 2 megabytes. The minimum buffer size allowed to be set is +16 kilobytes. + +The upload buffer is allocated on\-demand \- so if the handle is not used for +upload, this buffer is not allocated at all. + +DO NOT set this option on a handle that is currently used for an active +transfer as that may lead to unintended consequences. +.SH DEFAULT +65536 bytes +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/foo.bin"); + + /* ask libcurl to allocate a larger upload buffer */ + curl_easy_setopt(curl, CURLOPT_UPLOAD_BUFFERSIZE, 120000L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.62.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_BUFFERSIZE (3), +.BR CURLOPT_READFUNCTION (3), +.BR CURLOPT_TCP_NODELAY (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_URL.3 b/3rdparty/curl/share/man/man3/CURLOPT_URL.3 new file mode 100644 index 0000000..18af32a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_URL.3 @@ -0,0 +1,123 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_URL.md +.TH CURLOPT_URL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_URL \- URL for this transfer +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL); +.fi +.SH DESCRIPTION +Pass in a pointer to the \fIURL\fP to work with. The parameter should be a +char * to a null\-terminated string which must be URL\-encoded in the following +format: + +scheme://host:port/path + +For a greater explanation of the format please see RFC 3986. + +libcurl does not validate the syntax or use the URL until the transfer is +started. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP might +still return \fICURLE_OK\fP. + +If the given URL is missing a scheme name (such as "http://" or "ftp://" etc) +then libcurl guesses based on the host. If the outermost subdomain name +matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol gets used, +otherwise HTTP is used. Since 7.45.0 guessing can be disabled by setting a +default protocol, see \fICURLOPT_DEFAULT_PROTOCOL(3)\fP for details. + +Should the protocol, either as specified by the URL scheme or deduced by +libcurl from the hostname, not be supported by libcurl then +\fICURLE_UNSUPPORTED_PROTOCOL\fP is returned from either the \fIcurl_easy_perform(3)\fP +or \fIcurl_multi_perform(3)\fP functions when you call them. Use +\fIcurl_version_info(3)\fP for detailed information of which protocols are supported +by the build of libcurl you are using. + +\fICURLOPT_PROTOCOLS_STR(3)\fP can be used to limit what protocols libcurl may +use for this transfer, independent of what libcurl has been compiled to +support. That may be useful if you accept the URL from an external source and +want to limit the accessibility. + +The \fICURLOPT_URL(3)\fP string is ignored if \fICURLOPT_CURLU(3)\fP is set. + +Either \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP must be set before a +transfer is started. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. Note however that +libcurl needs a URL set to be able to performed a transfer. + +The parser used for handling the URL set with \fICURLOPT_URL(3)\fP is the same +that \fIcurl_url_set(3)\fP uses. +.SH ENCODING +The string pointed to in the \fICURLOPT_URL(3)\fP argument is generally +expected to be a sequence of characters using an ASCII compatible encoding. + +If libcurl is built with IDN support, the server name part of the URL can use +an "international name" by using the current encoding (according to locale) or +UTF\-8 (when WinIDN is used; or a Windows Unicode build using libidn2). + +If libcurl is built without IDN support, the server name is used exactly as +specified when passed to the name resolver functions. +.SH DEFAULT +NULL. If this option is not set, no transfer can be performed. +.SH SECURITY CONCERNS +Applications may at times find it convenient to allow users to specify URLs +for various purposes and that string would then end up fed to this option. + +Getting a URL from an external untrusted party brings several security +concerns: + +If you have an application that runs as or in a server application, getting an +unfiltered URL can easily trick your application to access a local resource +instead of a remote. Protecting yourself against localhost accesses is hard +when accepting user provided URLs. + +Such custom URLs can also access other ports than you planned as port numbers +are part of the regular URL format. The combination of a local host and a +custom port number can allow external users to play tricks with your local +services. + +Accepting external URLs may also use other protocols than http:// or other +common ones. Restrict what accept with \fICURLOPT_PROTOCOLS_STR(3)\fP. + +User provided URLs can also be made to point to sites that redirect further on +(possibly to other protocols too). Consider your +\fICURLOPT_FOLLOWLOCATION(3)\fP and \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP settings. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient +heap space. + +Note that \fIcurl_easy_setopt(3)\fP does not parse the given string so given a +bad URL, it is not detected until \fIcurl_easy_perform(3)\fP or similar is +called. +.SH SEE ALSO +.BR CURLINFO_REDIRECT_URL (3), +.BR CURLOPT_CURLU (3), +.BR CURLOPT_FORBID_REUSE (3), +.BR CURLOPT_FRESH_CONNECT (3), +.BR CURLOPT_PATH_AS_IS (3), +.BR CURLOPT_PROTOCOLS_STR (3), +.BR curl_easy_perform (3), +.BR curl_url_get (3), +.BR curl_url_set (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_USERAGENT.3 b/3rdparty/curl/share/man/man3/CURLOPT_USERAGENT.3 new file mode 100644 index 0000000..bdc739e --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_USERAGENT.3 @@ -0,0 +1,48 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_USERAGENT.md +.TH CURLOPT_USERAGENT 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_USERAGENT \- HTTP user\-agent header +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERAGENT, char *ua); +.fi +.SH DESCRIPTION +Pass a pointer to a null\-terminated string as parameter. It is used to set the +User\-Agent: header field in the HTTP request sent to the remote server. You +can also set any custom header with \fICURLOPT_HTTPHEADER(3)\fP. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL, no User\-Agent: header is used. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_USERAGENT, "Dark Secret Ninja/1.0"); + + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_CUSTOMREQUEST (3), +.BR CURLOPT_HTTPHEADER (3), +.BR CURLOPT_REFERER (3), +.BR CURLOPT_REQUEST_TARGET (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_USERNAME.3 b/3rdparty/curl/share/man/man3/CURLOPT_USERNAME.3 new file mode 100644 index 0000000..420d977 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_USERNAME.3 @@ -0,0 +1,70 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_USERNAME.md +.TH CURLOPT_USERNAME 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_USERNAME \- username to use in authentication +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERNAME, + char *username); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should be pointing to the +null\-terminated username to use for the transfer. + +\fICURLOPT_USERNAME(3)\fP sets the username to be used in protocol +authentication. You should not use this option together with the (older) +\fICURLOPT_USERPWD(3)\fP option. + +When using Kerberos V5 authentication with a Windows based server, you should +include the domain name in order for the server to successfully obtain a +Kerberos Ticket. If you do not then the initial part of the authentication +handshake may fail. + +When using NTLM, the username can be specified simply as the username without +the domain name should the server be part of a single domain and forest. + +To include the domain name use either Down\-Level Logon Name or UPN (User +Principal Name) formats. For example, \fBEXAMPLE\user\fP and +\fBuser@example.com\fP respectively. + +Some HTTP servers (on Windows) support inclusion of the domain for Basic +authentication as well. + +To specify the password and login options, along with the username, use the +\fICURLOPT_PASSWORD(3)\fP and \fICURLOPT_LOGIN_OPTIONS(3)\fP options. + +The application does not have to keep the string around after setting this +option. +.SH DEFAULT +blank +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + curl_easy_setopt(curl, CURLOPT_USERNAME, "clark"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.19.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_HTTPAUTH (3), +.BR CURLOPT_PASSWORD (3), +.BR CURLOPT_PROXYAUTH (3), +.BR CURLOPT_USERPWD (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_USERPWD.3 b/3rdparty/curl/share/man/man3/CURLOPT_USERPWD.3 new file mode 100644 index 0000000..3317f9d --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_USERPWD.3 @@ -0,0 +1,79 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_USERPWD.md +.TH CURLOPT_USERPWD 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_USERPWD \- username and password to use in authentication +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERPWD, char *userpwd); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, pointing to a null\-terminated login details +string for the connection. The format of which is: [username]:[password]. + +When using Kerberos V5 authentication with a Windows based server, you should +specify the username part with the domain name in order for the server to +successfully obtain a Kerberos Ticket. If you do not then the initial part of +the authentication handshake may fail. + +When using NTLM, the username can be specified simply as the username without +the domain name should the server be part of a single domain and forest. + +To specify the domain name use either Down\-Level Logon Name or UPN (User +Principal Name) formats. For example \fBEXAMPLE\user\fP and \fBuser@example.com\fP +respectively. + +Some HTTP servers (on Windows) support inclusion of the domain for Basic +authentication as well. + +When using HTTP and \fICURLOPT_FOLLOWLOCATION(3)\fP, libcurl might perform several +requests to possibly different hosts. libcurl only sends this user and +password information to hosts using the initial hostname (unless +\fICURLOPT_UNRESTRICTED_AUTH(3)\fP is set), so if libcurl follows redirects to other +hosts, it does not send the user and password to those. This is enforced to +prevent accidental information leakage. + +Use \fICURLOPT_HTTPAUTH(3)\fP to specify the authentication method for HTTP +based connections or \fICURLOPT_LOGIN_OPTIONS(3)\fP to control IMAP, POP3 and +SMTP options. + +The user and password strings are not URL decoded, so there is no way to send +in a username containing a colon using this option. Use \fICURLOPT_USERNAME(3)\fP +for that, or include it in the URL. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + curl_easy_setopt(curl, CURLOPT_USERPWD, "clark:kent"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK on success or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_PASSWORD (3), +.BR CURLOPT_PROXYUSERPWD (3), +.BR CURLOPT_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_USE_SSL.3 b/3rdparty/curl/share/man/man3/CURLOPT_USE_SSL.3 new file mode 100644 index 0000000..2fe3395 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_USE_SSL.3 @@ -0,0 +1,59 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_USE_SSL.md +.TH CURLOPT_USE_SSL 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_USE_SSL \- request using SSL / TLS for the transfer +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USE_SSL, long level); +.fi +.SH DESCRIPTION +Pass a long using one of the values from below, to make libcurl use your +desired \fIlevel\fP of SSL for the transfer. + +These are all protocols that start out plain text and get "upgraded" to SSL +using the STARTTLS command. + +This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc. +.IP CURLUSESSL_NONE +do not attempt to use SSL. +.IP CURLUSESSL_TRY +Try using SSL, proceed as normal otherwise. Note that server may close the +connection if the negotiation does not succeed. +.IP CURLUSESSL_CONTROL +Require SSL for the control connection or fail with \fICURLE_USE_SSL_FAILED\fP. +.IP CURLUSESSL_ALL +Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP. +.SH DEFAULT +CURLUSESSL_NONE +.SH PROTOCOLS +This functionality affects ftp, imap, pop3 and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/file.ext"); + + /* require use of SSL for this, or fail */ + curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH HISTORY +This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants were +known as CURLFTPSSL_* Handled by LDAP since 7.81.0. Fully supported by the +OpenLDAP backend only. +.SH AVAILABILITY +Added in curl 7.17.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_PROXY_SSLVERSION (3), +.BR CURLOPT_SSLVERSION (3), +.BR CURLOPT_SSL_OPTIONS (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_VERBOSE.3 b/3rdparty/curl/share/man/man3/CURLOPT_VERBOSE.3 new file mode 100644 index 0000000..dfe7b12 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_VERBOSE.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_VERBOSE.md +.TH CURLOPT_VERBOSE 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_VERBOSE \- verbose mode +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_VERBOSE, long onoff); +.fi +.SH DESCRIPTION +Set the \fIonoff\fP parameter to 1 to make the library display a lot of +verbose information about its operations on this \fIhandle\fP. Useful for +libcurl and/or protocol debugging and understanding. The verbose information +is sent to stderr, or the stream set with \fICURLOPT_STDERR(3)\fP. + +You hardly ever want this enabled in production use, you almost always want +this used when you debug/report problems. + +To also get all the protocol data sent and received, consider using the +\fICURLOPT_DEBUGFUNCTION(3)\fP. +.SH DEFAULT +0, meaning disabled. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* ask libcurl to show us the verbose output */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_ERRORBUFFER (3), +.BR CURLOPT_STDERR (3), +.BR curl_global_trace (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_WILDCARDMATCH.3 b/3rdparty/curl/share/man/man3/CURLOPT_WILDCARDMATCH.3 new file mode 100644 index 0000000..2526ddf --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_WILDCARDMATCH.3 @@ -0,0 +1,92 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_WILDCARDMATCH.md +.TH CURLOPT_WILDCARDMATCH 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_WILDCARDMATCH \- directory wildcard transfers +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WILDCARDMATCH, long onoff); +.fi +.SH DESCRIPTION +Set \fIonoff\fP to 1 if you want to transfer multiple files according to a +filename pattern. The pattern can be specified as part of the \fICURLOPT_URL(3)\fP +option, using an \fBfnmatch\fP\-like pattern (Shell Pattern Matching) in the last +part of URL (filename). + +By default, libcurl uses its internal wildcard matching implementation. You +can provide your own matching function by the +\fICURLOPT_FNMATCH_FUNCTION(3)\fP option. + +A brief introduction of its syntax follows: +.IP "* - ASTERISK" +.nf +ftp://example.com/some/path/*.txt +.fi + +matches all \fI.txt\fP files in the root directory. Only two asterisks are allowed +within the same pattern string. +.IP "? - QUESTION MARK" +Question mark matches any (exactly one) character. + +.nf +ftp://example.com/some/path/photo?.jpg +.fi +.IP "[ - BRACKET EXPRESSION" +The left bracket opens a bracket expression. The question mark and asterisk have +no special meaning in a bracket expression. Each bracket expression ends by the +right bracket and matches exactly one character. Some examples follow: + +\fB[a\-zA\-Z0\-9]\fP or \fB[f\-gF\-G]\fP \- character interval + +\fB[abc]\fP \- character enumeration + +\fB[^abc]\fP or \fB[!abc]\fP \- negation + +\fB[[:name:]]\fP class expression. Supported classes are \fBalnum\fP,\fBlower\fP, +\fBspace\fP, \fBalpha\fP, \fBdigit\fP, \fBprint\fP, \fBupper\fP, \fBblank\fP, \fBgraph\fP, +\fBxdigit\fP. + +\fB[][\-!^]\fP \- special case \- matches only \(aq\-\(aq, \(aq]\(aq, \(aq[\(aq, \(aq!\(aq or \(aq^\(aq. These +characters have no special purpose. + +\fB[[]]\fP \- escape syntax. Matches \(aq[\(aq, \(aq]\(aq or \(aqe\(aq. + +Using the rules above, a filename pattern can be constructed: + +.nf +ftp://example.com/some/path/[a-z[:upper:]\\].jpg +.fi +.SH PROTOCOLS +This functionality affects ftp only +.SH EXAMPLE +.nf +extern long begin_cb(struct curl_fileinfo *, void *, int); +extern long end_cb(void *ptr); + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* turn on wildcard matching */ + curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); + + /* callback is called before download of concrete file started */ + curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, begin_cb); + + /* callback is called after data from the file have been transferred */ + curl_easy_setopt(curl, CURLOPT_CHUNK_END_FUNCTION, end_cb); + + /* See more on https://curl.se/libcurl/c/ftp-wildcard.html */ + } +} +.fi +.SH AVAILABILITY +Added in curl 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CHUNK_BGN_FUNCTION (3), +.BR CURLOPT_CHUNK_END_FUNCTION (3), +.BR CURLOPT_FNMATCH_FUNCTION (3), +.BR CURLOPT_URL (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_WRITEDATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_WRITEDATA.3 new file mode 100644 index 0000000..f6615c5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_WRITEDATA.3 @@ -0,0 +1,44 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_WRITEDATA.md +.TH CURLOPT_WRITEDATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_WRITEDATA \- pointer passed to the write callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEDATA, void *pointer); +.fi +.SH DESCRIPTION +A data \fIpointer\fP to pass to the write callback. If you use the +\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you get in that +callback\(aqs fourth and last argument. If you do not use a write callback, you +must make \fIpointer\fP a \(aqFILE \fI\(aq (cast to \(aqvoid \fP\(aq) as libcurl passes this +to \fIfwrite(3)\fP when writing data. + +The internal \fICURLOPT_WRITEFUNCTION(3)\fP writes the data to the FILE * +given with this option, or to stdout if this option has not been set. + +If you are using libcurl as a Windows DLL, you \fBMUST\fP use a +\fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you might experience +crashes. +.SH DEFAULT +stdout +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +A common technique is to use the write callback to store the incoming data +into a dynamically growing allocated buffer, and then this +\fICURLOPT_WRITEDATA(3)\fP is used to point to a struct or the buffer to store data +in. Like in the getinmemory example: +https://curl.se/libcurl/c/getinmemory.html +.SH HISTORY +This option was formerly known as CURLOPT_FILE, the name \fICURLOPT_WRITEDATA(3)\fP +was added in 7.9.7. +.SH AVAILABILITY +Added in curl 7.9.7 +.SH RETURN VALUE +This returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_HEADERDATA (3), +.BR CURLOPT_READDATA (3), +.BR CURLOPT_WRITEFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_WRITEFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_WRITEFUNCTION.3 new file mode 100644 index 0000000..ddde150 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_WRITEFUNCTION.3 @@ -0,0 +1,117 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_WRITEFUNCTION.md +.TH CURLOPT_WRITEFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_WRITEFUNCTION \- callback for writing received data +.SH SYNOPSIS +.nf +#include + +size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl as soon as there is data +received that needs to be saved. For most transfers, this callback gets called +many times and each invoke delivers another chunk of data. \fIptr\fP points to the +delivered data, and the size of that data is \fInmemb\fP; \fIsize\fP is always 1. + +The data passed to this function is not null\-terminated. + +The callback function is passed as much data as possible in all invokes, but +you must not make any assumptions. It may be one byte, it may be +thousands. The maximum amount of body data that is passed to the write +callback is defined in the curl.h header file: \fICURL_MAX_WRITE_SIZE\fP (the +usual default is 16K). If \fICURLOPT_HEADER(3)\fP is enabled, which makes header +data get passed to the write callback, you can get up to +\fICURL_MAX_HTTP_HEADER\fP bytes of header data passed into it. This usually means +100K. + +This function may be called with zero bytes data if the transferred file is +empty. + +Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option. + +Your callback should return the number of bytes actually taken care of. If +that amount differs from the amount passed to your callback function, it +signals an error condition to the library. This causes the transfer to get +aborted and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. + +You can also abort the transfer by returning CURL_WRITEFUNC_ERROR (added in +7.87.0), which makes \fICURLE_WRITE_ERROR\fP get returned. + +If the callback function returns CURL_WRITEFUNC_PAUSE it pauses this +transfer. See \fIcurl_easy_pause(3)\fP for further details. + +Set this option to NULL to get the internal default function used instead of +your callback. The internal default function writes the data to the FILE * +given with \fICURLOPT_WRITEDATA(3)\fP. + +This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to +do that. +.SH DEFAULT +fwrite(3) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +#include /* for realloc */ +#include /* for memcpy */ + +struct memory { + char *response; + size_t size; +}; + +static size_t cb(char *data, size_t size, size_t nmemb, void *clientp) +{ + size_t realsize = size * nmemb; + struct memory *mem = (struct memory *)clientp; + + char *ptr = realloc(mem->response, mem->size + realsize + 1); + if(!ptr) + return 0; /* out of memory! */ + + mem->response = ptr; + memcpy(&(mem->response[mem->size]), data, realsize); + mem->size += realsize; + mem->response[mem->size] = 0; + + return realsize; +} + +int main(void) +{ + struct memory chunk = {0}; + CURLcode res; + CURL *curl = curl_easy_init(); + if(curl) { + /* send all data to this function */ + curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, cb); + + /* we pass our 'chunk' struct to the callback function */ + curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk); + + /* send a request */ + res = curl_easy_perform(curl); + + /* remember to free the buffer */ + free(chunk.response); + + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +This returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_HEADERFUNCTION (3), +.BR CURLOPT_READFUNCTION (3), +.BR CURLOPT_WRITEDATA (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_WS_OPTIONS.3 b/3rdparty/curl/share/man/man3/CURLOPT_WS_OPTIONS.3 new file mode 100644 index 0000000..1ea524a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_WS_OPTIONS.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_WS_OPTIONS.md +.TH CURLOPT_WS_OPTIONS 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_WS_OPTIONS \- WebSocket behavior options +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WS_OPTIONS, long bitmask); +.fi +.SH DESCRIPTION +Pass a long with a bitmask to tell libcurl about specific WebSocket +behaviors. + +To detach a WebSocket connection and use the \fIcurl_ws_send(3)\fP and +\fIcurl_ws_recv(3)\fP functions after the HTTP upgrade procedure, set the +\fICURLOPT_CONNECT_ONLY(3)\fP option to 2L. + +Available bits in the bitmask +.IP "CURLWS_RAW_MODE (1)" +Deliver "raw" WebSocket traffic to the \fICURLOPT_WRITEFUNCTION(3)\fP +callback. + +In raw mode, libcurl does not handle pings or any other frame for the +application. +.SH DEFAULT +0 +.SH PROTOCOLS +This functionality affects ws only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ws://example.com/"); + /* tell curl we deal with all the WebSocket magic ourselves */ + curl_easy_setopt(curl, CURLOPT_WS_OPTIONS, (long)CURLWS_RAW_MODE); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.86.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_CONNECT_ONLY (3), +.BR curl_ws_recv (3), +.BR curl_ws_send (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_XFERINFODATA.3 b/3rdparty/curl/share/man/man3/CURLOPT_XFERINFODATA.3 new file mode 100644 index 0000000..fe38143 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_XFERINFODATA.3 @@ -0,0 +1,59 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_XFERINFODATA.md +.TH CURLOPT_XFERINFODATA 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_XFERINFODATA \- pointer passed to the progress callback +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFODATA, void *pointer); +.fi +.SH DESCRIPTION +Pass a \fIpointer\fP that is untouched by libcurl and passed as the first +argument in the progress callback set with \fICURLOPT_XFERINFOFUNCTION(3)\fP. + +This is an alias for \fICURLOPT_PROGRESSDATA(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct progress { + char *private; + size_t size; +}; + +static size_t progress_cb(void *clientp, + curl_off_t dltotal, + curl_off_t dlnow, + curl_off_t ultotal, + curl_off_t ulnow) +{ + struct progress *memory = clientp; + printf("private ptr: %p\\n", memory->private); + /* use the values */ + + return 0; /* all is good */ +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct progress data; + + /* pass struct to callback */ + curl_easy_setopt(curl, CURLOPT_XFERINFODATA, &data); + curl_easy_setopt(curl, CURLOPT_XFERINFOFUNCTION, progress_cb); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.32.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_NOPROGRESS (3), +.BR CURLOPT_VERBOSE (3), +.BR CURLOPT_XFERINFOFUNCTION (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_XFERINFOFUNCTION.3 b/3rdparty/curl/share/man/man3/CURLOPT_XFERINFOFUNCTION.3 new file mode 100644 index 0000000..483df75 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_XFERINFOFUNCTION.3 @@ -0,0 +1,103 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_XFERINFOFUNCTION.md +.TH CURLOPT_XFERINFOFUNCTION 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_XFERINFOFUNCTION \- progress meter callback +.SH SYNOPSIS +.nf +#include + +int progress_callback(void *clientp, + curl_off_t dltotal, + curl_off_t dlnow, + curl_off_t ultotal, + curl_off_t ulnow); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFOFUNCTION, + progress_callback); +.fi +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This function gets called by libcurl instead of its internal equivalent with a +frequent interval. While data is being transferred it gets called frequently, +and during slow periods like when nothing is being transferred it can slow +down to about one call per second. + +\fIclientp\fP is the pointer set with \fICURLOPT_XFERINFODATA(3)\fP, it is not +used by libcurl but is only passed along from the application to the callback. + +The callback gets told how much data libcurl is about to transfer and has +already transferred, in number of bytes. \fIdltotal\fP is the total number of +bytes libcurl expects to download in this transfer. \fIdlnow\fP is the number +of bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl +expects to upload in this transfer. \fIulnow\fP is the number of bytes +uploaded so far. + +Unknown/unused argument values passed to the callback are set to zero (like if +you only download data, the upload size remains 0). Many times the callback is +called one or more times first, before it knows the data sizes so a program +must be made to handle that. + +Return zero from the callback if everything is fine. + +Return 1 from this callback to make libcurl abort the transfer and return +\fICURLE_ABORTED_BY_CALLBACK\fP. + +If your callback function returns CURL_PROGRESSFUNC_CONTINUE it makes libcurl +to continue executing the default progress function. + +If you transfer data with the multi interface, this function is not called +during periods of idleness unless you call the appropriate libcurl function +that performs transfers. + +\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually +get called. +.SH DEFAULT +NULL \- use the internal progress meter. That is rarely wanted by users. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct progress { + char *private; + size_t size; +}; + +static size_t progress_callback(void *clientp, + curl_off_t dltotal, + curl_off_t dlnow, + curl_off_t ultotal, + curl_off_t ulnow) +{ + struct progress *memory = clientp; + printf("my ptr: %p\\n", memory->private); + + /* use the values */ + + return 0; /* all is good */ +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct progress data; + + /* pass struct to callback */ + curl_easy_setopt(curl, CURLOPT_XFERINFODATA, &data); + + /* enable progress callback getting called */ + curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L); + + curl_easy_setopt(curl, CURLOPT_XFERINFOFUNCTION, progress_callback); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.32.0 +.SH RETURN VALUE +Returns CURLE_OK. +.SH SEE ALSO +.BR CURLOPT_NOPROGRESS (3), +.BR CURLOPT_XFERINFODATA (3) diff --git a/3rdparty/curl/share/man/man3/CURLOPT_XOAUTH2_BEARER.3 b/3rdparty/curl/share/man/man3/CURLOPT_XOAUTH2_BEARER.3 new file mode 100644 index 0000000..776d232 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLOPT_XOAUTH2_BEARER.3 @@ -0,0 +1,51 @@ +.\" generated by cd2nroff 0.1 from CURLOPT_XOAUTH2_BEARER.md +.TH CURLOPT_XOAUTH2_BEARER 3 "2024-10-11" libcurl +.SH NAME +CURLOPT_XOAUTH2_BEARER \- OAuth 2.0 access token +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XOAUTH2_BEARER, char *token); +.fi +.SH DESCRIPTION +Pass a char pointer as parameter, which should point to the null\-terminated +OAuth 2.0 Bearer Access Token for use with HTTP, IMAP, LDAP, POP3 and SMTP +servers that support the OAuth 2.0 Authorization Framework. + +Note: For IMAP, LDAP, POP3 and SMTP, the username used to generate the Bearer +Token should be supplied via the \fICURLOPT_USERNAME(3)\fP option. + +The application does not have to keep the string around after setting this +option. + +Using this option multiple times makes the last set string override the +previous ones. Set it to NULL to disable its use again. +.SH DEFAULT +NULL +.SH PROTOCOLS +This functionality affects http, imap, ldap, pop3 and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "pop3://example.com/"); + curl_easy_setopt(curl, CURLOPT_XOAUTH2_BEARER, "1ab9cb22ba269a7"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +Support for OpenLDAP added in 7.82.0. +.SH AVAILABILITY +Added in curl 7.33.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH SEE ALSO +.BR CURLOPT_MAIL_AUTH (3), +.BR CURLOPT_USERNAME (3) diff --git a/3rdparty/curl/share/man/man3/CURLSHOPT_LOCKFUNC.3 b/3rdparty/curl/share/man/man3/CURLSHOPT_LOCKFUNC.3 new file mode 100644 index 0000000..60e160c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLSHOPT_LOCKFUNC.3 @@ -0,0 +1,58 @@ +.\" generated by cd2nroff 0.1 from CURLSHOPT_LOCKFUNC.md +.TH CURLSHOPT_LOCKFUNC 3 "2024-10-11" libcurl +.SH NAME +CURLSHOPT_LOCKFUNC \- mutex lock callback +.SH SYNOPSIS +.nf +#include + +void lockcb(CURL *handle, curl_lock_data data, curl_lock_access access, + void *clientp); + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_LOCKFUNC, lockcb); +.fi +.SH DESCRIPTION +Set a mutex lock callback for the share object, to allow it to get used by +multiple threads concurrently. There is a corresponding +\fICURLSHOPT_UNLOCKFUNC(3)\fP callback called when the mutex is again released. + +The \fIlockcb\fP argument must be a pointer to a function matching the +prototype shown above. The arguments to the callback are: + +\fIhandle\fP is the currently active easy handle in use when the share object +is intended to get used. + +The \fIdata\fP argument tells what kind of data libcurl wants to lock. Make +sure that the callback uses a different lock for each kind of data. + +\fIaccess\fP defines what access type libcurl wants, shared or single. + +\fIclientp\fP is the private pointer you set with \fICURLSHOPT_USERDATA(3)\fP. +This pointer is not used by libcurl itself. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +extern void mutex_lock(CURL *handle, curl_lock_data data, + curl_lock_access access, void *clientp); + +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_LOCKFUNC, mutex_lock); + if(sh) + printf("Error: %s\\n", curl_share_strerror(sh)); +} +.fi +.SH AVAILABILITY +Added in curl 7.10.3 +.SH RETURN VALUE +CURLSHE_OK (zero) means that the option was set properly, non\-zero means an +error occurred. See \fIlibcurl\-errors(3)\fP for the full list with +descriptions. +.SH SEE ALSO +.BR CURLSHOPT_UNLOCKFUNC (3), +.BR curl_share_cleanup (3), +.BR curl_share_init (3), +.BR curl_share_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLSHOPT_SHARE.3 b/3rdparty/curl/share/man/man3/CURLSHOPT_SHARE.3 new file mode 100644 index 0000000..2cf726a --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLSHOPT_SHARE.3 @@ -0,0 +1,90 @@ +.\" generated by cd2nroff 0.1 from CURLSHOPT_SHARE.md +.TH CURLSHOPT_SHARE 3 "2024-10-11" libcurl +.SH NAME +CURLSHOPT_SHARE \- add data to share +.SH SYNOPSIS +.nf +#include + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_SHARE, long type); +.fi +.SH DESCRIPTION +The \fItype\fP parameter specifies what specific data that should be shared +and kept in the share object that was created with \fIcurl_share_init(3)\fP. +The given \fItype\fP must be one of the values described below. You can set +\fICURLSHOPT_SHARE(3)\fP multiple times with different data arguments to have +the share object share multiple types of data. Unset a type again by setting +\fICURLSHOPT_UNSHARE(3)\fP. +.IP CURL_LOCK_DATA_COOKIE +Cookie data is shared across the easy handles using this shared object. Note +that this does not activate an easy handle\(aqs cookie handling. You can do that +separately by using \fICURLOPT_COOKIEFILE(3)\fP for example. + +It is not supported to share cookies between multiple concurrent threads. +.IP CURL_LOCK_DATA_DNS +Cached DNS hosts are shared across the easy handles using this shared +object. Note that when you use the multi interface, all easy handles added to +the same multi handle share DNS cache by default without using this option. +.IP CURL_LOCK_DATA_SSL_SESSION +SSL session IDs are shared across the easy handles using this shared +object. This reduces the time spent in the SSL handshake when reconnecting to +the same server. Note SSL session IDs are reused within the same easy handle +by default. Note this symbol was added in 7.10.3 but was not implemented until +7.23.0. + +It is not supported to share SSL sessions between multiple concurrent threads. +.IP CURL_LOCK_DATA_CONNECT +Put the connection cache in the share object and make all easy handles using +this share object share the connection cache. + +It is not supported to share connections between multiple concurrent threads. + +Connections that are used for HTTP/2 or HTTP/3 multiplexing only get +additional transfers added to them if the existing connection is held by the +same multi or easy handle. libcurl does not support doing multiplexed streams +in different threads using a shared connection. + +Support for \fBCURL_LOCK_DATA_CONNECT\fP was added in 7.57.0, but the symbol +existed before this. + +Note that when you use the multi interface, all easy handles added to the same +multi handle shares connection cache by default without using this option. +.IP CURL_LOCK_DATA_PSL +The Public Suffix List stored in the share object is made available to all +easy handle bound to the later. Since the Public Suffix List is periodically +refreshed, this avoids updates in too many different contexts. + +Added in 7.61.0. + +Note that when you use the multi interface, all easy handles added to the same +multi handle shares PSL cache by default without using this option. +.IP CURL_LOCK_DATA_HSTS +The in\-memory HSTS cache. + +It is not supported to share the HSTS between multiple concurrent threads. + +Added in 7.88.0 +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE); + if(sh) + printf("Error: %s\\n", curl_share_strerror(sh)); +} +.fi +.SH AVAILABILITY +Added in curl 7.10.3 +.SH RETURN VALUE +CURLSHE_OK (zero) means that the option was set properly, non\-zero means an +error occurred. See \fIlibcurl\-errors(3)\fP for the full list with +descriptions. +.SH SEE ALSO +.BR CURLSHOPT_UNSHARE (3), +.BR curl_share_cleanup (3), +.BR curl_share_init (3), +.BR curl_share_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLSHOPT_UNLOCKFUNC.3 b/3rdparty/curl/share/man/man3/CURLSHOPT_UNLOCKFUNC.3 new file mode 100644 index 0000000..19f3845 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLSHOPT_UNLOCKFUNC.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from CURLSHOPT_UNLOCKFUNC.md +.TH CURLSHOPT_UNLOCKFUNC 3 "2024-10-11" libcurl +.SH NAME +CURLSHOPT_UNLOCKFUNC \- mutex unlock callback +.SH SYNOPSIS +.nf +#include + +void unlockcb(CURL *handle, curl_lock_data data, void *clientp); + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNLOCKFUNC, unlockcb); +.fi +.SH DESCRIPTION +Set a mutex unlock callback for the share object. There is a corresponding +\fICURLSHOPT_LOCKFUNC(3)\fP callback called when the mutex is first locked. + +The \fIunlockcb\fP argument must be a pointer to a function matching the +prototype shown above. The arguments to the callback are: + +\fIhandle\fP is the currently active easy handle in use when the share object +is released. + +The \fIdata\fP argument tells what kind of data libcurl wants to unlock. Make +sure that the callback uses a different lock for each kind of data. + +\fIclientp\fP is the private pointer you set with \fICURLSHOPT_USERDATA(3)\fP. +This pointer is not used by libcurl itself. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +extern void mutex_unlock(CURL *, curl_lock_data, void *); + +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_UNLOCKFUNC, mutex_unlock); + if(sh) + printf("Error: %s\\n", curl_share_strerror(sh)); +} +.fi +.SH AVAILABILITY +Added in curl 7.10.3 +.SH RETURN VALUE +CURLSHE_OK (zero) means that the option was set properly, non\-zero means an +error occurred. See \fIlibcurl\-errors(3)\fP for the full list with +descriptions. +.SH SEE ALSO +.BR CURLSHOPT_LOCKFUNC (3), +.BR curl_share_cleanup (3), +.BR curl_share_init (3), +.BR curl_share_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLSHOPT_UNSHARE.3 b/3rdparty/curl/share/man/man3/CURLSHOPT_UNSHARE.3 new file mode 100644 index 0000000..f82d753 --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLSHOPT_UNSHARE.3 @@ -0,0 +1,55 @@ +.\" generated by cd2nroff 0.1 from CURLSHOPT_UNSHARE.md +.TH CURLSHOPT_UNSHARE 3 "2024-10-11" libcurl +.SH NAME +CURLSHOPT_UNSHARE \- remove data to share +.SH SYNOPSIS +.nf +#include + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNSHARE, long type); +.fi +.SH DESCRIPTION +The \fItype\fP parameter specifies what specific data that should no longer be +shared and kept in the share object that was created with +\fIcurl_share_init(3)\fP. In other words, stop sharing that data in this +shared object. The given \fItype\fP must be one of the values described +below. You can set \fICURLSHOPT_UNSHARE(3)\fP multiple times with different +data arguments to remove multiple types from the shared object. Add data to +share again with \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_DATA_COOKIE +Cookie data is no longer shared across the easy handles using this shared +object. +.IP CURL_LOCK_DATA_DNS +Cached DNS hosts are no longer shared across the easy handles using this +shared object. +.IP CURL_LOCK_DATA_SSL_SESSION +SSL session IDs are no longer shared across the easy handles using this shared +object. +.IP CURL_LOCK_DATA_CONNECT +The connection cache is no longer shared. +.IP CURL_LOCK_DATA_PSL +The Public Suffix List is no longer shared. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_UNSHARE, CURL_LOCK_DATA_COOKIE); + if(sh) + printf("Error: %s\\n", curl_share_strerror(sh)); +} +.fi +.SH AVAILABILITY +Added in curl 7.10.3 +.SH RETURN VALUE +CURLSHE_OK (zero) means that the option was set properly, non\-zero means an +error occurred. See \fIlibcurl\-errors(3)\fP for the full list with +descriptions. +.SH SEE ALSO +.BR CURLSHOPT_SHARE (3), +.BR curl_share_cleanup (3), +.BR curl_share_init (3), +.BR curl_share_setopt (3) diff --git a/3rdparty/curl/share/man/man3/CURLSHOPT_USERDATA.3 b/3rdparty/curl/share/man/man3/CURLSHOPT_USERDATA.3 new file mode 100644 index 0000000..a29348c --- /dev/null +++ b/3rdparty/curl/share/man/man3/CURLSHOPT_USERDATA.3 @@ -0,0 +1,43 @@ +.\" generated by cd2nroff 0.1 from CURLSHOPT_USERDATA.md +.TH CURLSHOPT_USERDATA 3 "2024-10-11" libcurl +.SH NAME +CURLSHOPT_USERDATA \- pointer passed to the lock and unlock mutex callbacks +.SH SYNOPSIS +.nf +#include + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_USERDATA, void *clientp); +.fi +.SH DESCRIPTION +The \fIclientp\fP parameter is held verbatim by libcurl and is passed on as +the \fIclientp\fP argument to the callbacks set with +\fICURLSHOPT_LOCKFUNC(3)\fP and \fICURLSHOPT_UNLOCKFUNC(3)\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +struct secrets { + void *custom; +}; + +int main(void) +{ + CURLSHcode sh; + struct secrets private_stuff; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_USERDATA, &private_stuff); + if(sh) + printf("Error: %s\\n", curl_share_strerror(sh)); +} +.fi +.SH AVAILABILITY +Added in curl 7.10.3 +.SH RETURN VALUE +CURLSHE_OK (zero) means that the option was set properly, non\-zero means an +error occurred. See \fIlibcurl\-errors(3)\fP for the full list with +descriptions. +.SH SEE ALSO +.BR CURLSHOPT_LOCKFUNC (3), +.BR curl_share_cleanup (3), +.BR curl_share_init (3), +.BR curl_share_setopt (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_cleanup.3 b/3rdparty/curl/share/man/man3/curl_easy_cleanup.3 new file mode 100644 index 0000000..a8e9f2f --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_cleanup.3 @@ -0,0 +1,61 @@ +.\" generated by cd2nroff 0.1 from curl_easy_cleanup.md +.TH curl_easy_cleanup 3 "2024-10-11" libcurl +.SH NAME +curl_easy_cleanup \- free an easy handle +.SH SYNOPSIS +.nf +#include + +void curl_easy_cleanup(CURL *handle); +.fi +.SH DESCRIPTION +This function is the opposite of \fIcurl_easy_init(3)\fP. It closes down and frees +all resources previously associated with this easy handle. + +This call closes all connections this handle has used and possibly has kept +open until now unless the easy handle was attached to a multi handle while +doing the transfers. Do not call this function if you intend to transfer more +files, reusing handles is a key to good performance with libcurl. + +Occasionally you may get your progress callback or header callback called from +within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using +\fIcurl_easy_setopt(3)\fP). Like if libcurl decides to shut down the connection and +the protocol is of a kind that requires a command/response sequence before +disconnect. Examples of such protocols are FTP, POP3 and IMAP. + +Any use of the easy \fBhandle\fP after this function has been called and have +returned, is illegal. + +To close an easy handle that has been used with the multi interface, make sure +to first call \fIcurl_multi_remove_handle(3)\fP to remove it from the multi handle +before it is closed. + +Passing in a NULL pointer in \fIhandle\fP makes this function return immediately +with no action. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res) + printf("error: %s\\n", curl_easy_strerror(res)); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +None +.SH SEE ALSO +.BR curl_easy_duphandle (3), +.BR curl_easy_init (3), +.BR curl_easy_reset (3), +.BR curl_multi_cleanup (3), +.BR curl_multi_remove_handle (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_duphandle.3 b/3rdparty/curl/share/man/man3/curl_easy_duphandle.3 new file mode 100644 index 0000000..8b90df9 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_duphandle.3 @@ -0,0 +1,57 @@ +.\" generated by cd2nroff 0.1 from curl_easy_duphandle.md +.TH curl_easy_duphandle 3 "2024-10-11" libcurl +.SH NAME +curl_easy_duphandle \- clone an easy handle +.SH SYNOPSIS +.nf +#include + +CURL *curl_easy_duphandle(CURL *handle); +.fi +.SH DESCRIPTION +This function returns a new curl handle, a duplicate, using all the options +previously set in the input curl \fIhandle\fP. Both handles can subsequently be +used independently and they must both be freed with \fIcurl_easy_cleanup(3)\fP. + +Any options that the input handle has been told to point to (as opposed to +copy) with previous calls to \fIcurl_easy_setopt(3)\fP, are pointed to by the new +handle as well. You must therefore make sure to keep the data around until +both handles have been cleaned up. + +The new handle does \fBnot\fP inherit any state information, no connections, no +SSL sessions and no cookies. It also does not inherit any share object states +or options (created as if \fICURLOPT_SHARE(3)\fP was set to NULL). + +If the source handle has HSTS or alt\-svc enabled, the duplicate gets data read +data from the main filename to populate the cache. + +In multi\-threaded programs, this function must be called in a synchronous way, +the input handle may not be in use when cloned. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + CURL *nother; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + nother = curl_easy_duphandle(curl); + res = curl_easy_perform(nother); + curl_easy_cleanup(nother); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9 +.SH RETURN VALUE +If this function returns NULL, something went wrong and no valid handle was +returned. +.SH SEE ALSO +.BR curl_easy_cleanup (3), +.BR curl_easy_init (3), +.BR curl_easy_reset (3), +.BR curl_global_init (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_escape.3 b/3rdparty/curl/share/man/man3/curl_easy_escape.3 new file mode 100644 index 0000000..39b2a67 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_escape.3 @@ -0,0 +1,68 @@ +.\" generated by cd2nroff 0.1 from curl_easy_escape.md +.TH curl_easy_escape 3 "2024-10-11" libcurl +.SH NAME +curl_easy_escape \- URL encode a string +.SH SYNOPSIS +.nf +#include + +char *curl_easy_escape(CURL *curl, const char *string, int length); +.fi +.SH DESCRIPTION +This function converts the given input \fIstring\fP to a URL encoded string and +returns that as a new allocated string. All input characters that are not a\-z, +A\-Z, 0\-9, \(aq\-\(aq, \(aq.\(aq, \(aq_\(aq or \(aq~\(aq are converted to their "URL escaped" version +(\fB%NN\fP where \fBNN\fP is a two\-digit hexadecimal number). + +If \fIlength\fP is set to 0 (zero), \fIcurl_easy_escape(3)\fP uses strlen() on the input +\fIstring\fP to find out the size. This function does not accept input strings +longer than \fBCURL_MAX_INPUT_LENGTH\fP (8 MB). + +You must \fIcurl_free(3)\fP the returned string when you are done with it. +.SH ENCODING +libcurl is typically not aware of, nor does it care about, character +encodings. \fIcurl_easy_escape(3)\fP encodes the data byte\-by\-byte into the +URL encoded version without knowledge or care for what particular character +encoding the application or the receiving server may assume that the data +uses. + +The caller of \fIcurl_easy_escape(3)\fP must make sure that the data passed in +to the function is encoded correctly. +.SH URLs +URLs are by definition \fIURL encoded\fP. To create a proper URL from a set of +components that may not be URL encoded already, you cannot just URL encode the +entire URL string with \fIcurl_easy_escape(3)\fP, because it then also converts +colons, slashes and other symbols that you probably want untouched. + +To create a proper URL from strings that are not already URL encoded, we +recommend using libcurl\(aqs URL API: set the pieces with \fIcurl_url_set(3)\fP and get +the final correct URL with \fIcurl_url_get(3)\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + char *output = curl_easy_escape(curl, "data to convert", 15); + if(output) { + printf("Encoded: %s\\n", output); + curl_free(output); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH HISTORY +Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was +per\-handle character conversion support for some old operating systems such as +TPF, but it was otherwise ignored. +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +A pointer to a null\-terminated string or NULL if it failed. +.SH SEE ALSO +.BR curl_easy_unescape (3), +.BR curl_url_get (3), +.BR curl_url_set (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_getinfo.3 b/3rdparty/curl/share/man/man3/curl_easy_getinfo.3 new file mode 100644 index 0000000..d7c96c6 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_getinfo.3 @@ -0,0 +1,259 @@ +.\" generated by cd2nroff 0.1 from curl_easy_getinfo.md +.TH curl_easy_getinfo 3 "2024-10-11" libcurl +.SH NAME +curl_easy_getinfo \- extract information from a curl handle +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... ); +.fi +.SH DESCRIPTION +Get the \fIinfo\fP kept in the \fIcurl\fP handle. The third argument \fBMUST\fP be +pointing to the specific type of the used option which is documented in each +man page of the \fIinfo\fP option. The data is stored accordingly and can be +relied upon only if this function returns CURLE_OK. Use this function after a +performed transfer if you want to get transfer related data. + +You should not free the memory returned by this function unless it is +explicitly mentioned below. +.SH OPTIONS +The following information can be extracted: +.IP CURLINFO_ACTIVESOCKET +The session\(aqs active socket. See \fICURLINFO_ACTIVESOCKET(3)\fP +.IP CURLINFO_APPCONNECT_TIME +The time it took from the start until the SSL connect/handshake with the +remote host was completed as a double in number of seconds. (Added in 7.19.0) +.IP CURLINFO_APPCONNECT_TIME_T +The time it took from the start until the SSL connect/handshake with the +remote host was completed in number of microseconds. (Added in 7.60.0) See +\fICURLINFO_APPCONNECT_TIME_T(3)\fP +.IP CURLINFO_CAINFO +Get the default value for \fICURLOPT_CAINFO(3)\fP. See \fICURLINFO_CAINFO(3)\fP +.IP CURLINFO_CAPATH +Get the default value for \fICURLOPT_CAPATH(3)\fP. See \fICURLINFO_CAPATH(3)\fP +.IP CURLINFO_CERTINFO +Certificate chain. See \fICURLINFO_CERTINFO(3)\fP +.IP CURLINFO_CONDITION_UNMET +Whether or not a time conditional was met or 304 HTTP response. +See \fICURLINFO_CONDITION_UNMET(3)\fP +.IP CURLINFO_CONNECT_TIME +The time it took from the start until the connect to the remote host (or +proxy) was completed. As a double. See \fICURLINFO_CONNECT_TIME(3)\fP +.IP CURLINFO_CONNECT_TIME_T +The time it took from the start until the connect to the remote host (or +proxy) was completed. In microseconds. See \fICURLINFO_CONNECT_TIME_T(3)\fP. +.IP CURLINFO_CONN_ID +The ID of the last connection used by the transfer. (Added in 8.2.0) +See \fICURLINFO_CONN_ID(3)\fP +.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD +(\fBDeprecated\fP) Content length from the Content\-Length header. +See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD(3)\fP +.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD_T +Content length from the Content\-Length header. +See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP +.IP CURLINFO_CONTENT_LENGTH_UPLOAD +(\fBDeprecated\fP) Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD(3)\fP +.IP CURLINFO_CONTENT_LENGTH_UPLOAD_T +Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP +.IP CURLINFO_CONTENT_TYPE +Content type from the \fIContent\-Type:\fP header. We recommend using +\fIcurl_easy_header(3)\fP instead. See \fICURLINFO_CONTENT_TYPE(3)\fP +.IP CURLINFO_COOKIELIST +List of all known cookies. See \fICURLINFO_COOKIELIST(3)\fP +.IP CURLINFO_EFFECTIVE_METHOD +Last used HTTP method. See \fICURLINFO_EFFECTIVE_METHOD(3)\fP +.IP CURLINFO_EFFECTIVE_URL +Last used URL. See \fICURLINFO_EFFECTIVE_URL(3)\fP +.IP CURLINFO_FILETIME +Remote time of the retrieved document. See \fICURLINFO_FILETIME(3)\fP +.IP CURLINFO_FILETIME_T +Remote time of the retrieved document. See \fICURLINFO_FILETIME_T(3)\fP +.IP CURLINFO_FTP_ENTRY_PATH +The entry path after logging in to an FTP server. See +\fICURLINFO_FTP_ENTRY_PATH(3)\fP +.IP CURLINFO_HEADER_SIZE +Number of bytes of all headers received. See \fICURLINFO_HEADER_SIZE(3)\fP +.IP CURLINFO_HTTPAUTH_AVAIL +Available HTTP authentication methods. See \fICURLINFO_HTTPAUTH_AVAIL(3)\fP +.IP CURLINFO_HTTP_CONNECTCODE +Last proxy CONNECT response code. See \fICURLINFO_HTTP_CONNECTCODE(3)\fP +.IP CURLINFO_HTTP_VERSION +The http version used in the connection. See \fICURLINFO_HTTP_VERSION(3)\fP +.IP CURLINFO_LASTSOCKET +(\fBDeprecated\fP) Last socket used. See \fICURLINFO_LASTSOCKET(3)\fP +.IP CURLINFO_LOCAL_IP +Source IP address of the last connection. See \fICURLINFO_LOCAL_IP(3)\fP +.IP CURLINFO_LOCAL_PORT +Source port number of the last connection. See \fICURLINFO_LOCAL_PORT(3)\fP +.IP CURLINFO_NAMELOOKUP_TIME +Time from start until name resolving completed as a double. See +\fICURLINFO_NAMELOOKUP_TIME(3)\fP +.IP CURLINFO_NAMELOOKUP_TIME_T +Time from start until name resolving completed in number of microseconds. See +\fICURLINFO_NAMELOOKUP_TIME_T(3)\fP +.IP CURLINFO_NUM_CONNECTS +Number of new successful connections used for previous transfer. +See \fICURLINFO_NUM_CONNECTS(3)\fP +.IP CURLINFO_OS_ERRNO +The errno from the last failure to connect. See \fICURLINFO_OS_ERRNO(3)\fP +.IP CURLINFO_POSTTRANSFER_TIME_T +The time it took from the start until the last byte is sent by libcurl. +In microseconds. (Added in 8.10.0) See \fICURLINFO_POSTTRANSFER_TIME_T(3)\fP +.IP CURLINFO_PRETRANSFER_TIME +The time it took from the start until the file transfer is just about to +begin. This includes all pre\-transfer commands and negotiations that are +specific to the particular protocol(s) involved. See +\fICURLINFO_PRETRANSFER_TIME(3)\fP +.IP CURLINFO_PRETRANSFER_TIME_T +The time it took from the start until the file transfer is just about to +begin. This includes all pre\-transfer commands and negotiations that are +specific to the particular protocol(s) involved. In microseconds. See +\fICURLINFO_PRETRANSFER_TIME_T(3)\fP +.IP CURLINFO_PRIMARY_IP +Destination IP address of the last connection. See \fICURLINFO_PRIMARY_IP(3)\fP +.IP CURLINFO_PRIMARY_PORT +Destination port of the last connection. See \fICURLINFO_PRIMARY_PORT(3)\fP +.IP CURLINFO_PRIVATE +User\(aqs private data pointer. See \fICURLINFO_PRIVATE(3)\fP +.IP CURLINFO_PROTOCOL +(\fBDeprecated\fP) The protocol used for the connection. (Added in 7.52.0) See +\fICURLINFO_PROTOCOL(3)\fP +.IP CURLINFO_PROXYAUTH_AVAIL +Available HTTP proxy authentication methods. See \fICURLINFO_PROXYAUTH_AVAIL(3)\fP +.IP CURLINFO_PROXY_ERROR +Detailed proxy error. See \fICURLINFO_PROXY_ERROR(3)\fP +.IP CURLINFO_PROXY_SSL_VERIFYRESULT +Proxy certificate verification result. See \fICURLINFO_PROXY_SSL_VERIFYRESULT(3)\fP +.IP CURLINFO_QUEUE_TIME_T +The time during which the transfer was held in a waiting queue before it could +start for real in number of microseconds. (Added in 8.6.0) See +\fICURLINFO_QUEUE_TIME_T(3)\fP +.IP CURLINFO_REDIRECT_COUNT +Total number of redirects that were followed. See \fICURLINFO_REDIRECT_COUNT(3)\fP +.IP CURLINFO_REDIRECT_TIME +The time it took for all redirection steps include name lookup, connect, +pretransfer and transfer before final transaction was started. So, this is +zero if no redirection took place. As a double. See \fICURLINFO_REDIRECT_TIME(3)\fP +.IP CURLINFO_REDIRECT_TIME_T +The time it took for all redirection steps include name lookup, connect, +pretransfer and transfer before final transaction was started. So, this is +zero if no redirection took place. In number of microseconds. See +\fICURLINFO_REDIRECT_TIME_T(3)\fP +.IP CURLINFO_REDIRECT_URL +URL a redirect would take you to, had you enabled redirects. See +\fICURLINFO_REDIRECT_URL(3)\fP +.IP CURLINFO_REFERER +Referrer header. See \fICURLINFO_REFERER(3)\fP +.IP CURLINFO_REQUEST_SIZE +Number of bytes sent in the issued HTTP requests. See \fICURLINFO_REQUEST_SIZE(3)\fP +.IP CURLINFO_RESPONSE_CODE +Last received response code. See \fICURLINFO_RESPONSE_CODE(3)\fP +.IP CURLINFO_RETRY_AFTER +The value from the Retry\-After header. See \fICURLINFO_RETRY_AFTER(3)\fP +.IP CURLINFO_RTSP_CLIENT_CSEQ +The RTSP client CSeq that is expected next. See \fICURLINFO_RTSP_CLIENT_CSEQ(3)\fP +.IP CURLINFO_RTSP_CSEQ_RECV +RTSP CSeq last received. See \fICURLINFO_RTSP_CSEQ_RECV(3)\fP +.IP CURLINFO_RTSP_SERVER_CSEQ +The RTSP server CSeq that is expected next. See \fICURLINFO_RTSP_SERVER_CSEQ(3)\fP +.IP CURLINFO_RTSP_SESSION_ID +RTSP session ID. See \fICURLINFO_RTSP_SESSION_ID(3)\fP +.IP CURLINFO_SCHEME +The scheme used for the connection. (Added in 7.52.0) See \fICURLINFO_SCHEME(3)\fP +.IP CURLINFO_SIZE_DOWNLOAD +(\fBDeprecated\fP) Number of bytes downloaded. See \fICURLINFO_SIZE_DOWNLOAD(3)\fP +.IP CURLINFO_SIZE_DOWNLOAD_T +Number of bytes downloaded. See \fICURLINFO_SIZE_DOWNLOAD_T(3)\fP +.IP CURLINFO_SIZE_UPLOAD +(\fBDeprecated\fP) Number of bytes uploaded. See \fICURLINFO_SIZE_UPLOAD(3)\fP +.IP CURLINFO_SIZE_UPLOAD_T +Number of bytes uploaded. See \fICURLINFO_SIZE_UPLOAD_T(3)\fP +.IP CURLINFO_SPEED_DOWNLOAD +(\fBDeprecated\fP) Average download speed. See \fICURLINFO_SPEED_DOWNLOAD(3)\fP +.IP CURLINFO_SPEED_DOWNLOAD_T +Average download speed. See \fICURLINFO_SPEED_DOWNLOAD_T(3)\fP +.IP CURLINFO_SPEED_UPLOAD +(\fBDeprecated\fP) Average upload speed. See \fICURLINFO_SPEED_UPLOAD(3)\fP +.IP CURLINFO_SPEED_UPLOAD_T +Average upload speed in number of bytes per second. See +\fICURLINFO_SPEED_UPLOAD_T(3)\fP +.IP CURLINFO_SSL_ENGINES +A list of OpenSSL crypto engines. See \fICURLINFO_SSL_ENGINES(3)\fP +.IP CURLINFO_SSL_VERIFYRESULT +Certificate verification result. See \fICURLINFO_SSL_VERIFYRESULT(3)\fP +.IP CURLINFO_STARTTRANSFER_TIME +The time it took from the start until the first byte is received by libcurl. +As a double. See \fICURLINFO_STARTTRANSFER_TIME(3)\fP +.IP CURLINFO_STARTTRANSFER_TIME_T +The time it took from the start until the first byte is received by libcurl. +In microseconds. See \fICURLINFO_STARTTRANSFER_TIME_T(3)\fP +.IP CURLINFO_TLS_SESSION +(\fBDeprecated\fP) TLS session info that can be used for further processing. See +\fICURLINFO_TLS_SESSION(3)\fP. Use \fICURLINFO_TLS_SSL_PTR(3)\fP instead! +.IP CURLINFO_TLS_SSL_PTR +TLS session info that can be used for further processing. See +\fICURLINFO_TLS_SSL_PTR(3)\fP +.IP CURLINFO_TOTAL_TIME +Total time of previous transfer. See \fICURLINFO_TOTAL_TIME(3)\fP +.IP CURLINFO_TOTAL_TIME_T +Total time of previous transfer. See \fICURLINFO_TOTAL_TIME_T(3)\fP +.IP CURLINFO_USED_PROXY +Whether the proxy was used (Added in 8.7.0). See \fICURLINFO_USED_PROXY(3)\fP +.IP CURLINFO_XFER_ID +The ID of the transfer. (Added in 8.2.0) See \fICURLINFO_XFER_ID(3)\fP +.SH TIMES +An overview of the time values available from \fIcurl_easy_getinfo(3)\fP + +.nf +curl_easy_perform() + | + |--QUEUE + |--|--NAMELOOKUP + |--|--|--CONNECT + |--|--|--|--APPCONNECT + |--|--|--|--|--PRETRANSFER + |--|--|--|--|--|--POSTTRANSFER + |--|--|--|--|--|--|--STARTTRANSFER + |--|--|--|--|--|--|--|--TOTAL + |--|--|--|--|--|--|--|--REDIRECT +.fi + + \fICURLINFO_QUEUE_TIME_T(3)\fP, \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP, + \fICURLINFO_CONNECT_TIME_T(3)\fP, \fICURLINFO_APPCONNECT_TIME_T(3)\fP, + \fICURLINFO_PRETRANSFER_TIME_T(3)\fP, \fICURLINFO_POSTTRANSFER_TIME_T(3)\fP, + \fICURLINFO_STARTTRANSFER_TIME_T(3)\fP, \fICURLINFO_TOTAL_TIME_T(3)\fP, + \fICURLINFO_REDIRECT_TIME_T(3)\fP +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); + res = curl_easy_perform(curl); + + if(CURLE_OK == res) { + char *ct; + /* ask for the content-type */ + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct); + + if((CURLE_OK == res) && ct) + printf("We received Content-Type: %s\\n", ct); + } + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.4.1 +.SH RETURN VALUE +If the operation was successful, CURLE_OK is returned. Otherwise an +appropriate error code is returned. +.SH SEE ALSO +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_header.3 b/3rdparty/curl/share/man/man3/curl_easy_header.3 new file mode 100644 index 0000000..78efbd6 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_header.3 @@ -0,0 +1,132 @@ +.\" generated by cd2nroff 0.1 from curl_easy_header.md +.TH curl_easy_header 3 "2024-10-11" libcurl +.SH NAME +curl_easy_header \- get an HTTP header +.SH SYNOPSIS +.nf +#include + +CURLHcode curl_easy_header(CURL *easy, + const char *name, + size_t index, + unsigned int origin, + int request, + struct curl_header **hout); +.fi +.SH DESCRIPTION +\fIcurl_easy_header(3)\fP returns a pointer to a "curl_header" struct in \fBhout\fP +with data for the HTTP response header \fIname\fP. The case insensitive +null\-terminated header name should be specified without colon. + +\fIindex\fP 0 means asking for the first instance of the header. If the returned +header struct has \fBamount\fP set larger than 1, it means there are more +instances of the same header name available to get. Asking for a too big index +makes \fBCURLHE_BADINDEX\fP get returned. + +The \fIorigin\fP argument is for specifying which headers to receive, as a single +HTTP transfer might provide headers from several different places and they may +then have different importance to the user and headers using the same name +might be used. The \fIorigin\fP is a bitmask for what header sources you want. See +the descriptions below. + +The \fIrequest\fP argument tells libcurl from which request you want headers +from. A single transfer might consist of a series of HTTP requests and this +argument lets you specify which particular individual request you want the +headers from. 0 being the first request and then the number increases for +further redirects or when multi\-state authentication is used. Passing in \-1 is +a shortcut to "the last" request in the series, independently of the actual +amount of requests used. + +libcurl stores and provides the actually used "correct" headers. If for +example two headers with the same name arrive and the latter overrides the +former, then only the latter is provided. If the first header survives the +second, then only the first one is provided. An application using this API +does not have to bother about multiple headers used wrongly. + +The memory for the returned struct is associated with the easy handle and +subsequent calls to \fIcurl_easy_header(3)\fP clobber the struct used in the +previous calls for the same easy handle. The application needs to copy the data if +it wants to keep it around. The memory used for the struct gets freed with +calling \fIcurl_easy_cleanup(3)\fP of the easy handle. + +The first line in an HTTP response is called the status line. It is not +considered a header by this function. Headers are the "name: value" lines +following the status. + +This function can be used before (all) headers have been received and is fine +to call from within libcurl callbacks. It returns the state of the headers at +the time it is called. +.SH The header struct +.nf +struct curl_header { + char *name; + char *value; + size_t amount; + size_t index; + unsigned int origin; + void *anchor; +}; +.fi + +The data \fBname\fP field points to, is the same as the requested name, but +might have a different case. + +The data \fBvalue\fP field points to, comes exactly as delivered over the +network but with leading and trailing whitespace and newlines stripped +off. The \fIvalue\fP data is null\-terminated. For legacy HTTP/1 "folded headers", +this API provides the full single value in an unfolded manner with a single +whitespace between the lines. + +\fBamount\fP is how many headers using this name that exist, within the origin +and request scope asked for. + +\fBindex\fP is the zero based entry number of this particular header, which in +case this header was used more than once in the requested scope can be larger +than 0 but is always less than \fBamount\fP. + +The \fBorigin\fP field in the "curl_header" struct has one of the origin bits +set, indicating where from the header originates. At the time of this writing, +there are 5 bits with defined use. The undocumented 27 remaining bits are +reserved for future use and must not be assumed to have any particular value. + +\fBanchor\fP is a private handle used by libcurl internals. Do not modify. +.SH ORIGINS +.IP CURLH_HEADER +The header arrived as a header from the server. +.IP CURLH_TRAILER +The header arrived as a trailer. A header that arrives after the body. +.IP CURLH_CONNECT +The header arrived in a CONNECT response. A CONNECT request is being done to +setup a transfer "through" an HTTP(S) proxy. +.IP CURLH_1XX +The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate" +response that might happen before the "real" response. +.IP CURLH_PSEUDO +The header is an HTTP/2 or HTTP/3 pseudo header +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + struct curl_header *type; + CURL *curl = curl_easy_init(); + if(curl) { + CURLHcode h; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_perform(curl); + h = curl_easy_header(curl, "Content-Type", 0, CURLH_HEADER, -1, &type); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.83.0 +.SH RETURN VALUE +This function returns a CURLHcode indicating success or error. +.SH SEE ALSO +.BR CURLINFO_CONTENT_TYPE (3), +.BR CURLOPT_HEADERFUNCTION (3), +.BR curl_easy_nextheader (3), +.BR curl_easy_perform (3), +.BR libcurl-errors (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_init.3 b/3rdparty/curl/share/man/man3/curl_easy_init.3 new file mode 100644 index 0000000..b713aa0 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_init.3 @@ -0,0 +1,58 @@ +.\" generated by cd2nroff 0.1 from curl_easy_init.md +.TH curl_easy_init 3 "2024-10-11" libcurl +.SH NAME +curl_easy_init \- create an easy handle +.SH SYNOPSIS +.nf +#include + +CURL *curl_easy_init(); +.fi +.SH DESCRIPTION +This function allocates and returns a CURL easy handle. Such a handle is used +as input to other functions in the easy interface. This call must have a +corresponding call to \fIcurl_easy_cleanup(3)\fP when the operation is complete. + +The easy handle is used to hold and control a single network transfer. It is +encouraged to reuse easy handles for repeated transfers. + +An alternative way to get a new easy handle is to duplicate an already +existing one with \fIcurl_easy_duphandle(3)\fP, which has the upside that it gets +all the options that were set in the source handle set in the new copy as +well. + +If you did not already call \fIcurl_global_init(3)\fP before calling this function, +\fIcurl_easy_init(3)\fP does it automatically. This can be lethal in multi\-threaded +cases for platforms where \fIcurl_global_init(3)\fP is not thread\-safe, and it may +then result in resource problems because there is no corresponding cleanup. + +You are strongly advised to not allow this automatic behavior, by calling +\fIcurl_global_init(3)\fP yourself properly. See the description in \fIlibcurl(3)\fP of +global environment requirements for details of how to use this function. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +If this function returns NULL, something went wrong and you cannot use the +other curl functions. +.SH SEE ALSO +.BR curl_easy_cleanup (3), +.BR curl_easy_duphandle (3), +.BR curl_easy_perform (3), +.BR curl_easy_reset (3), +.BR curl_global_init (3), +.BR curl_multi_init (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_nextheader.3 b/3rdparty/curl/share/man/man3/curl_easy_nextheader.3 new file mode 100644 index 0000000..4ee136a --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_nextheader.3 @@ -0,0 +1,85 @@ +.\" generated by cd2nroff 0.1 from curl_easy_nextheader.md +.TH curl_easy_nextheader 3 "2024-10-11" libcurl +.SH NAME +curl_easy_nextheader \- get the next HTTP header +.SH SYNOPSIS +.nf +#include + +struct curl_header *curl_easy_nextheader(CURL *easy, + unsigned int origin, + int request, + struct curl_header *prev); +.fi +.SH DESCRIPTION +This function lets an application iterate over all previously received HTTP +headers. + +The \fIorigin\fP argument is for specifying which headers to receive, as a single +HTTP transfer might provide headers from several different places and they may +then have different importance to the user and headers using the same name +might be used. The \fIorigin\fP is a bitmask for what header sources you want. See +the \fIcurl_easy_header(3)\fP man page for the origin descriptions. + +The \fIrequest\fP argument tells libcurl from which request you want headers +from. A single transfer might consist of a series of HTTP requests and this +argument lets you specify which particular individual request you want the +headers from. 0 being the first request and then the number increases for +further redirects or when multi\-state authentication is used. Passing in \-1 is +a shortcut to "the last" request in the series, independently of the actual +amount of requests used. + +It is suggested that you pass in the same \fBorigin\fP and \fBrequest\fP when +iterating over a range of headers as changing the value mid\-loop might give +you unexpected results. + +If \fIprev\fP is NULL, this function returns a pointer to the first header stored +within the given scope (origin + request). + +If \fIprev\fP is a pointer to a previously returned header struct, +\fIcurl_easy_nextheader(3)\fP returns a pointer the next header stored within the +given scope. This way, an application can iterate over all available headers. + +The memory for the struct this points to, is owned and managed by libcurl and +is associated with the easy handle. Applications must copy the data if they +want it to survive subsequent API calls or the life\-time of the easy handle. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + struct curl_header *prev = NULL; + struct curl_header *h; + + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_perform(curl); + + /* extract the normal headers from the first request */ + while((h = curl_easy_nextheader(curl, CURLH_HEADER, 0, prev))) { + printf("%s: %s\\n", h->name, h->value); + prev = h; + } + + /* extract the normal headers + 1xx + trailers from the last request */ + unsigned int origin = CURLH_HEADER| CURLH_1XX | CURLH_TRAILER; + while((h = curl_easy_nextheader(curl, origin, -1, prev))) { + printf("%s: %s\\n", h->name, h->value); + prev = h; + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.83.0 +.SH RETURN VALUE +This function returns the next header, or NULL when there are no more +(matching) headers or an error occurred. + +If this function returns NULL when \fIprev\fP was set to NULL, then there are no +headers available within the scope to return. +.SH SEE ALSO +.BR curl_easy_header (3), +.BR curl_easy_perform (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_option_by_id.3 b/3rdparty/curl/share/man/man3/curl_easy_option_by_id.3 new file mode 100644 index 0000000..e4a6eea --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_option_by_id.3 @@ -0,0 +1,39 @@ +.\" generated by cd2nroff 0.1 from curl_easy_option_by_id.md +.TH curl_easy_option_by_id 3 "2024-10-11" libcurl +.SH NAME +curl_easy_option_by_id \- find an easy setopt option by id +.SH SYNOPSIS +.nf +#include + +const struct curl_easyoption *curl_easy_option_by_id(CURLoption id); +.fi +.SH DESCRIPTION +Given a \fICURLoption\fP \fBid\fP, this function returns a pointer to the +\fIcurl_easyoption\fP struct, holding information about the +\fIcurl_easy_setopt(3)\fP option using that id. The option id is the CURLOPT_ +prefix ones provided in the standard curl/curl.h header file. This function +returns the non\-alias version of the cases where there is an alias function as +well. + +If libcurl has no option with the given id, this function returns NULL. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + const struct curl_easyoption *opt = curl_easy_option_by_id(CURLOPT_URL); + if(opt) { + printf("This option wants type %x\\n", opt->type); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.73.0 +.SH RETURN VALUE +A pointer to the \fIcurl_easyoption\fP struct for the option or NULL. +.SH SEE ALSO +.BR curl_easy_option_by_name (3), +.BR curl_easy_option_next (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_option_by_name.3 b/3rdparty/curl/share/man/man3/curl_easy_option_by_name.3 new file mode 100644 index 0000000..7626d6f --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_option_by_name.3 @@ -0,0 +1,38 @@ +.\" generated by cd2nroff 0.1 from curl_easy_option_by_name.md +.TH curl_easy_option_by_name 3 "2024-10-11" libcurl +.SH NAME +curl_easy_option_by_name \- find an easy setopt option by name +.SH SYNOPSIS +.nf +#include + +const struct curl_easyoption *curl_easy_option_by_name(const char *name); +.fi +.SH DESCRIPTION +Given a \fBname\fP, this function returns a pointer to the +\fIcurl_easyoption\fP struct, holding information about the +\fIcurl_easy_setopt(3)\fP option using that name. The name should be specified +without the "CURLOPT_" prefix and the name comparison is made case +insensitive. + +If libcurl has no option with the given name, this function returns NULL. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + const struct curl_easyoption *opt = curl_easy_option_by_name("URL"); + if(opt) { + printf("This option wants CURLoption %x\\n", (int)opt->id); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.73.0 +.SH RETURN VALUE +A pointer to the \fIcurl_easyoption\fP struct for the option or NULL. +.SH SEE ALSO +.BR curl_easy_option_by_id (3), +.BR curl_easy_option_next (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_option_next.3 b/3rdparty/curl/share/man/man3/curl_easy_option_next.3 new file mode 100644 index 0000000..c319896 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_option_next.3 @@ -0,0 +1,72 @@ +.\" generated by cd2nroff 0.1 from curl_easy_option_next.md +.TH curl_easy_option_next 3 "2024-10-11" libcurl +.SH NAME +curl_easy_option_next \- iterate over easy setopt options +.SH SYNOPSIS +.nf +#include + +const struct curl_easyoption * +curl_easy_option_next(const struct curl_easyoption *prev); +.fi +.SH DESCRIPTION +This function returns a pointer to the first or the next \fIcurl_easyoption\fP +struct, providing an ability to iterate over all known options for +\fIcurl_easy_setopt(3)\fP in this instance of libcurl. + +Pass a \fBNULL\fP argument as \fBprev\fP to get the first option returned, or +pass in the current option to get the next one returned. If there is no more +option to return, \fIcurl_easy_option_next(3)\fP returns NULL. + +The options returned by this functions are the ones known to this libcurl and +information about what argument type they want. + +If the \fBCURLOT_FLAG_ALIAS\fP bit is set in the flags field, it means the +name is provided for backwards compatibility as an alias. +.SH struct +.nf +typedef enum { + CURLOT_LONG, /* long (a range of values) */ + CURLOT_VALUES, /* (a defined set or bitmask) */ + CURLOT_OFF_T, /* curl_off_t (a range of values) */ + CURLOT_OBJECT, /* pointer (void *) */ + CURLOT_STRING, /* (char * to null-terminated buffer) */ + CURLOT_SLIST, /* (struct curl_slist *) */ + CURLOT_CBPTR, /* (void * passed as-is to a callback) */ + CURLOT_BLOB, /* blob (struct curl_blob *) */ + CURLOT_FUNCTION /* function pointer */ +} curl_easytype; + +/* The CURLOPTTYPE_* id ranges can still be used to figure out what type/size + to use for curl_easy_setopt() for the given id */ +struct curl_easyoption { + const char *name; + CURLoption id; + curl_easytype type; + unsigned int flags; +}; +.fi +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + /* iterate over all available options */ + const struct curl_easyoption *opt; + opt = curl_easy_option_next(NULL); + while(opt) { + printf("Name: %s\\n", opt->name); + opt = curl_easy_option_next(opt); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.73.0 +.SH RETURN VALUE +A pointer to the \fIcurl_easyoption\fP struct for the next option or NULL if +no more options. +.SH SEE ALSO +.BR curl_easy_option_by_id (3), +.BR curl_easy_option_by_name (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_pause.3 b/3rdparty/curl/share/man/man3/curl_easy_pause.3 new file mode 100644 index 0000000..a9d5e0d --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_pause.3 @@ -0,0 +1,111 @@ +.\" generated by cd2nroff 0.1 from curl_easy_pause.md +.TH curl_easy_pause 3 "2024-10-11" libcurl +.SH NAME +curl_easy_pause \- pause and unpause a connection +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_pause(CURL *handle, int bitmask ); +.fi +.SH DESCRIPTION +Using this function, you can explicitly mark a running connection to get +paused, and you can unpause a connection that was previously paused. Unlike +most other libcurl functions, \fIcurl_easy_pause(3)\fP can be used from within +callbacks. + +A connection can be paused by using this function or by letting the read or +the write callbacks return the proper magic return code +(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback +that returns pause signals to the library that it could not take care of any +data at all, and that data is then delivered again to the callback when the +transfer is unpaused. + +While it may feel tempting, take care and notice that you cannot call this +function from another thread. To unpause, you may for example call it from the +progress callback (\fICURLOPT_PROGRESSFUNCTION(3)\fP). + +When this function is called to unpause receiving, the write callback might +get called before this function returns to deliver cached content. When +libcurl delivers such cached data to the write callback, it is delivered as +fast as possible, which may overstep the boundary set in +\fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP etc. + +The \fBhandle\fP argument identifies the transfer you want to pause or +unpause. + +A paused transfer is excluded from low speed cancels via the +\fICURLOPT_LOW_SPEED_LIMIT(3)\fP option and unpausing a transfer resets the +time period required for the low speed limit to be met. + +The \fBbitmask\fP argument is a set of bits that sets the new state of the +connection. The following bits can be used: +.IP CURLPAUSE_RECV +Pause receiving data. There is no data received on this connection until this +function is called again without this bit set. Thus, the write callback +(\fICURLOPT_WRITEFUNCTION(3)\fP) is not called. +.IP CURLPAUSE_SEND +Pause sending data. There is no data sent on this connection until this +function is called again without this bit set. Thus, the read callback +(\fICURLOPT_READFUNCTION(3)\fP) is not called. +.IP CURLPAUSE_ALL +Convenience define that pauses both directions. +.IP CURLPAUSE_CONT +Convenience define that unpauses both directions. +.SH LIMITATIONS +The pausing of transfers does not work with protocols that work without +network connectivity, like FILE://. Trying to pause such a transfer, in any +direction, might cause problems or error. +.SH MULTIPLEXED +When a connection is used multiplexed, like for HTTP/2, and one of the +transfers over the connection is paused and the others continue flowing, +libcurl might end up buffering contents for the paused transfer. It has to do +this because it needs to drain the socket for the other transfers and the +already announced window size for the paused transfer allows the server to +continue sending data up to that window size amount. By default, libcurl +announces a 32 megabyte window size, which thus can make libcurl end up +buffering 32 megabyte of data for a paused stream. + +When such a paused stream is unpaused again, any buffered data is delivered +first. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* pause a transfer in both directions */ + curl_easy_pause(curl, CURLPAUSE_RECV | CURLPAUSE_SEND); + + } +} +.fi +.SH MEMORY USE +When pausing a download transfer by returning the magic return code from a +write callback, the read data is already in libcurl\(aqs internal buffers so it +has to keep it in an allocated buffer until the receiving is again unpaused +using this function. + +If the downloaded data is compressed and is asked to get uncompressed +automatically on download, libcurl continues to uncompress the entire +downloaded chunk and it caches the data uncompressed. This has the side\- +effect that if you download something that is compressed a lot, it can result +in a large data amount needing to be allocated to save the data during the +pause. Consider not using paused receiving if you allow libcurl to uncompress +data automatically. + +If the download is done with HTTP/2 or HTTP/3, there is up to a stream window +size worth of data that curl cannot stop but instead needs to cache while the +transfer is paused. This means that if a window size of 64 MB is used, libcurl +might end up having to cache 64 MB of data. +.SH AVAILABILITY +Added in curl 7.18.0 +.SH RETURN VALUE +CURLE_OK (zero) means that the option was set properly, and a non\-zero return +code means something wrong occurred after the new state was set. See the +\fIlibcurl\-errors(3)\fP man page for the full list with descriptions. +.SH SEE ALSO +.BR curl_easy_cleanup (3), +.BR curl_easy_reset (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_perform.3 b/3rdparty/curl/share/man/man3/curl_easy_perform.3 new file mode 100644 index 0000000..1bbe335 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_perform.3 @@ -0,0 +1,68 @@ +.\" generated by cd2nroff 0.1 from curl_easy_perform.md +.TH curl_easy_perform 3 "2024-10-11" libcurl +.SH NAME +curl_easy_perform \- perform a blocking network transfer +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_perform(CURL *easy_handle); +.fi +.SH DESCRIPTION +\fIcurl_easy_perform(3)\fP performs a network transfer in a blocking manner and +returns when done, or earlier if it fails. For non\-blocking behavior, see +\fIcurl_multi_perform(3)\fP. + +Invoke this function after \fIcurl_easy_init(3)\fP and all the \fIcurl_easy_setopt(3)\fP +calls are made, and it performs the transfer as described in the options. It +must be called with the same \fBeasy_handle\fP as input as the \fIcurl_easy_init(3)\fP +call returned. + +You can do any amount of calls to \fIcurl_easy_perform(3)\fP while using the same +\fBeasy_handle\fP. If you intend to transfer more than one file, you are even +encouraged to do so. libcurl attempts to reuse existing connections for the +following transfers, thus making the operations faster, less CPU intense and +using less network resources. You probably want to use \fIcurl_easy_setopt(3)\fP +between the invokes to set options for the following \fIcurl_easy_perform(3)\fP +call. + +You must never call this function simultaneously from two places using the +same \fBeasy_handle\fP. Let the function return first before invoking it another +time. If you want parallel transfers, you must use several curl easy_handles. + +A network transfer moves data to a peer or from a peer. An application tells +libcurl how to receive data by setting the \fICURLOPT_WRITEFUNCTION(3)\fP and +\fICURLOPT_WRITEDATA(3)\fP options. To tell libcurl what data to send, there are a +few more alternatives but two common ones are \fICURLOPT_READFUNCTION(3)\fP and +\fICURLOPT_POSTFIELDS(3)\fP. + +While the \fBeasy_handle\fP is added to a multi handle, it cannot be used by +\fIcurl_easy_perform(3)\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +CURLE_OK (0) means everything was OK, non\-zero means an error occurred as +\fI\fP defines \- see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP +was set with \fIcurl_easy_setopt(3)\fP there is an error message stored in the error +buffer when non\-zero is returned. +.SH SEE ALSO +.BR curl_easy_init (3), +.BR curl_easy_setopt (3), +.BR curl_multi_add_handle (3), +.BR curl_multi_perform (3), +.BR libcurl-errors (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_recv.3 b/3rdparty/curl/share/man/man3/curl_easy_recv.3 new file mode 100644 index 0000000..2dc1d0e --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_recv.3 @@ -0,0 +1,88 @@ +.\" generated by cd2nroff 0.1 from curl_easy_recv.md +.TH curl_easy_recv 3 "2024-10-11" libcurl +.SH NAME +curl_easy_recv \- receives raw data on an "easy" connection +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen, size_t *n); +.fi +.SH DESCRIPTION +This function receives raw data from the established connection. You may use +it together with \fIcurl_easy_send(3)\fP to implement custom protocols using +libcurl. This functionality can be particularly useful if you use proxies +and/or SSL encryption: libcurl takes care of proxy negotiation and connection +setup. + +\fBbuffer\fP is a pointer to your buffer memory that gets populated by the +received data. \fBbuflen\fP is the maximum amount of data you can get in that +buffer. The variable \fBn\fP points to receives the number of received bytes. + +To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before +calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that +\fIcurl_easy_recv(3)\fP does not work on connections that were created without +this option. + +The call returns \fBCURLE_AGAIN\fP if there is no data to read \- the socket is +used in non\-blocking mode internally. When \fBCURLE_AGAIN\fP is returned, use +your operating system facilities like \fIselect(2)\fP to wait for data. The +socket may be obtained using \fIcurl_easy_getinfo(3)\fP with +\fICURLINFO_ACTIVESOCKET(3)\fP. + +Wait on the socket only if \fIcurl_easy_recv(3)\fP returns \fBCURLE_AGAIN\fP. +The reason for this is libcurl or the SSL library may internally cache some +data, therefore you should call \fIcurl_easy_recv(3)\fP until all data is +read which would include any cached data. + +Furthermore if you wait on the socket and it tells you there is data to read, +\fIcurl_easy_recv(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was +read was for internal SSL processing, and no other data is available. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* Do not do the transfer - only connect to host */ + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); + res = curl_easy_perform(curl); + + if(res == CURLE_OK) { + char buf[256]; + size_t nread; + long sockfd; + + /* Extract the socket from the curl handle - we need it for waiting. */ + res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); + + /* read data */ + res = curl_easy_recv(curl, buf, sizeof(buf), &nread); + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.18.2 +.SH RETURN VALUE +On success, returns \fBCURLE_OK\fP, stores the received data into +\fBbuffer\fP, and the number of bytes it actually read into \fB*n\fP. + +On failure, returns the appropriate error code. + +The function may return \fBCURLE_AGAIN\fP. In this case, use your operating +system facilities to wait until data can be read, and retry. + +Reading exactly 0 bytes indicates a closed connection. + +If there is no socket available to use from the previous transfer, this function +returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP. +.SH SEE ALSO +.BR curl_easy_getinfo (3), +.BR curl_easy_perform (3), +.BR curl_easy_send (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_reset.3 b/3rdparty/curl/share/man/man3/curl_easy_reset.3 new file mode 100644 index 0000000..95e5ab5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_reset.3 @@ -0,0 +1,41 @@ +.\" generated by cd2nroff 0.1 from curl_easy_reset.md +.TH curl_easy_reset 3 "2024-10-11" libcurl +.SH NAME +curl_easy_reset \- reset all options of a libcurl session handle +.SH SYNOPSIS +.nf +#include + +void curl_easy_reset(CURL *handle); +.fi +.SH DESCRIPTION +Re\-initializes all options previously set on a specified CURL handle to the +default values. This puts back the handle to the same state as it was in when +it was just created with \fIcurl_easy_init(3)\fP. + +It does not change the following information kept in the handle: live +connections, the Session ID cache, the DNS cache, the cookies, the shares or +the alt\-svc cache. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + + /* ... the handle is used and options are set ... */ + curl_easy_reset(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.12.1 +.SH RETURN VALUE +Nothing +.SH SEE ALSO +.BR curl_easy_cleanup (3), +.BR curl_easy_duphandle (3), +.BR curl_easy_init (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_send.3 b/3rdparty/curl/share/man/man3/curl_easy_send.3 new file mode 100644 index 0000000..f26d3fe --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_send.3 @@ -0,0 +1,80 @@ +.\" generated by cd2nroff 0.1 from curl_easy_send.md +.TH curl_easy_send 3 "2024-10-11" libcurl +.SH NAME +curl_easy_send \- sends raw data over an "easy" connection +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_send(CURL *curl, const void *buffer, + size_t buflen, size_t *n); +.fi +.SH DESCRIPTION +This function sends arbitrary data over the established connection. You may +use it together with \fIcurl_easy_recv(3)\fP to implement custom protocols +using libcurl. This functionality can be particularly useful if you use +proxies and/or SSL encryption: libcurl takes care of proxy negotiation and +connection setup. + +\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want +sent. The variable \fBn\fP points to receives the number of sent bytes. + +To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before +calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that +\fIcurl_easy_send(3)\fP does not work on connections that were created without +this option. + +The call returns \fBCURLE_AGAIN\fP if it is not possible to send data right now +- the socket is used in non\-blocking mode internally. When \fBCURLE_AGAIN\fP +is returned, use your operating system facilities like \fIselect(2)\fP to wait +until the socket is writable. The socket may be obtained using +\fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP. + +Furthermore if you wait on the socket and it tells you it is writable, +\fIcurl_easy_send(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was sent +was for internal SSL processing, and no other data could be sent. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* Do not do the transfer - only connect to host */ + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); + res = curl_easy_perform(curl); + + if(res == CURLE_OK) { + long sockfd; + size_t sent; + /* Extract the socket from the curl handle - we need it for waiting. */ + res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); + + /* send data */ + res = curl_easy_send(curl, "hello", 5, &sent); + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.18.2 +.SH RETURN VALUE +On success, returns \fBCURLE_OK\fP and stores the number of bytes actually +sent into \fB*n\fP. Note that this may be less than the amount you wanted to +send. + +On failure, returns the appropriate error code. + +This function may return \fBCURLE_AGAIN\fP. In this case, use your operating +system facilities to wait until the socket is writable, and retry. + +If there is no socket available to use from the previous transfer, this function +returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP. +.SH SEE ALSO +.BR curl_easy_getinfo (3), +.BR curl_easy_perform (3), +.BR curl_easy_recv (3), +.BR curl_easy_setopt (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_setopt.3 b/3rdparty/curl/share/man/man3/curl_easy_setopt.3 new file mode 100644 index 0000000..89b5264 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_setopt.3 @@ -0,0 +1,734 @@ +.\" generated by cd2nroff 0.1 from curl_easy_setopt.md +.TH curl_easy_setopt 3 "2024-10-11" libcurl +.SH NAME +curl_easy_setopt \- set options for a curl easy handle +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter); +.fi +.SH DESCRIPTION +\fIcurl_easy_setopt(3)\fP is used to tell libcurl how to behave. By setting the +appropriate options, the application can change libcurl\(aqs behavior. All +options are set with an \fIoption\fP followed by a \fIparameter\fP. That parameter can +be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject pointer\fP or a +\fBcurl_off_t\fP, depending on what the specific option expects. Read this +manual carefully as bad input values may cause libcurl to behave badly! You +can only set one option in each function call. A typical application uses many +\fIcurl_easy_setopt(3)\fP calls in the setup phase. + +Options set with this function call are valid for all forthcoming transfers +performed using this \fIhandle\fP. The options are not in any way reset between +transfers, so if you want subsequent transfers with different options, you +must change them between the transfers. You can optionally reset all options +back to internal default with \fIcurl_easy_reset(3)\fP. + +Strings passed to libcurl as \(aqchar *\(aq arguments, are copied by the library; +the string storage associated to the pointer argument may be discarded or +reused after \fIcurl_easy_setopt(3)\fP returns. The only exception to this rule is +really \fICURLOPT_POSTFIELDS(3)\fP, but the alternative that copies the string +\fICURLOPT_COPYPOSTFIELDS(3)\fP has some usage characteristics you need to read up +on. This function does not accept input strings longer than +\fBCURL_MAX_INPUT_LENGTH\fP (8 MB). + +The order in which the options are set does not matter. + +Before version 7.17.0, strings were not copied. Instead the user was forced +keep them available until libcurl no longer needed them. + +The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or +\fIcurl_easy_duphandle(3)\fP call. +.SH OPTIONS +.IP CURLOPT_ABSTRACT_UNIX_SOCKET +Path to an abstract Unix domain socket. See \fICURLOPT_ABSTRACT_UNIX_SOCKET(3)\fP +.IP CURLOPT_ACCEPTTIMEOUT_MS +Timeout for waiting for the server\(aqs connect back to be accepted. See +\fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP +.IP CURLOPT_ACCEPT_ENCODING +Accept\-Encoding and automatic decompressing data. See +\fICURLOPT_ACCEPT_ENCODING(3)\fP +.IP CURLOPT_ADDRESS_SCOPE +IPv6 scope for local addresses. See \fICURLOPT_ADDRESS_SCOPE(3)\fP +.IP CURLOPT_ALTSVC +Specify the Alt\-Svc: cache filename. See \fICURLOPT_ALTSVC(3)\fP +.IP CURLOPT_ALTSVC_CTRL +Enable and configure Alt\-Svc: treatment. See \fICURLOPT_ALTSVC_CTRL(3)\fP +.IP CURLOPT_APPEND +Append to remote file. See \fICURLOPT_APPEND(3)\fP +.IP CURLOPT_AUTOREFERER +Automatically set Referer: header. See \fICURLOPT_AUTOREFERER(3)\fP +.IP CURLOPT_AWS_SIGV4 +AWS HTTP V4 Signature. See \fICURLOPT_AWS_SIGV4(3)\fP +.IP CURLOPT_BUFFERSIZE +Ask for alternate buffer size. See \fICURLOPT_BUFFERSIZE(3)\fP +.IP CURLOPT_CAINFO +CA cert bundle. See \fICURLOPT_CAINFO(3)\fP +.IP CURLOPT_CAINFO_BLOB +CA cert bundle memory buffer. See \fICURLOPT_CAINFO_BLOB(3)\fP +.IP CURLOPT_CAPATH +Path to CA cert bundle. See \fICURLOPT_CAPATH(3)\fP +.IP CURLOPT_CA_CACHE_TIMEOUT +Timeout for CA cache. See \fICURLOPT_CA_CACHE_TIMEOUT(3)\fP +.IP CURLOPT_CERTINFO +Extract certificate info. See \fICURLOPT_CERTINFO(3)\fP +.IP CURLOPT_CHUNK_BGN_FUNCTION +Callback for wildcard download start of chunk. See +\fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP +.IP CURLOPT_CHUNK_DATA +Data pointer to pass to the chunk callbacks. See \fICURLOPT_CHUNK_DATA(3)\fP +.IP CURLOPT_CHUNK_END_FUNCTION +Callback for wildcard download end of chunk. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP +.IP CURLOPT_CLOSESOCKETDATA +Data pointer to pass to the close socket callback. See +\fICURLOPT_CLOSESOCKETDATA(3)\fP +.IP CURLOPT_CLOSESOCKETFUNCTION +Callback for closing socket. See \fICURLOPT_CLOSESOCKETFUNCTION(3)\fP +.IP CURLOPT_CONNECTTIMEOUT +Timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT(3)\fP +.IP CURLOPT_CONNECTTIMEOUT_MS +Millisecond timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP +.IP CURLOPT_CONNECT_ONLY +Only connect, nothing else. See \fICURLOPT_CONNECT_ONLY(3)\fP +.IP CURLOPT_CONNECT_TO +Connect to a specific host and port. See \fICURLOPT_CONNECT_TO(3)\fP +.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION +\fBOBSOLETE\fP Callback for code base conversion. +See \fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP +.IP CURLOPT_CONV_FROM_UTF8_FUNCTION +\fBOBSOLETE\fP Callback for code base conversion. +See \fICURLOPT_CONV_FROM_UTF8_FUNCTION(3)\fP +.IP CURLOPT_CONV_TO_NETWORK_FUNCTION +\fBOBSOLETE\fP Callback for code base conversion. +See \fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP +.IP CURLOPT_COOKIE +Cookie(s) to send. See \fICURLOPT_COOKIE(3)\fP +.IP CURLOPT_COOKIEFILE +File to read cookies from. See \fICURLOPT_COOKIEFILE(3)\fP +.IP CURLOPT_COOKIEJAR +File to write cookies to. See \fICURLOPT_COOKIEJAR(3)\fP +.IP CURLOPT_COOKIELIST +Add or control cookies. See \fICURLOPT_COOKIELIST(3)\fP +.IP CURLOPT_COOKIESESSION +Start a new cookie session. See \fICURLOPT_COOKIESESSION(3)\fP +.IP CURLOPT_COPYPOSTFIELDS +Send a POST with this data \- and copy it. See \fICURLOPT_COPYPOSTFIELDS(3)\fP +.IP CURLOPT_CRLF +Convert newlines. See \fICURLOPT_CRLF(3)\fP +.IP CURLOPT_CRLFILE +Certificate Revocation List. See \fICURLOPT_CRLFILE(3)\fP +.IP CURLOPT_CURLU +Set URL to work on with a URL handle. See \fICURLOPT_CURLU(3)\fP +.IP CURLOPT_CUSTOMREQUEST +Custom request/method. See \fICURLOPT_CUSTOMREQUEST(3)\fP +.IP CURLOPT_DEBUGDATA +Data pointer to pass to the debug callback. See \fICURLOPT_DEBUGDATA(3)\fP +.IP CURLOPT_DEBUGFUNCTION +Callback for debug information. See \fICURLOPT_DEBUGFUNCTION(3)\fP +.IP CURLOPT_DEFAULT_PROTOCOL +Default protocol. See \fICURLOPT_DEFAULT_PROTOCOL(3)\fP +.IP CURLOPT_DIRLISTONLY +List only. See \fICURLOPT_DIRLISTONLY(3)\fP +.IP CURLOPT_DISALLOW_USERNAME_IN_URL +Do not allow username in URL. See \fICURLOPT_DISALLOW_USERNAME_IN_URL(3)\fP +.IP CURLOPT_DNS_CACHE_TIMEOUT +Timeout for DNS cache. See \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP +.IP CURLOPT_DNS_INTERFACE +Bind name resolves to this interface. See \fICURLOPT_DNS_INTERFACE(3)\fP +.IP CURLOPT_DNS_LOCAL_IP4 +Bind name resolves to this IP4 address. See \fICURLOPT_DNS_LOCAL_IP4(3)\fP +.IP CURLOPT_DNS_LOCAL_IP6 +Bind name resolves to this IP6 address. See \fICURLOPT_DNS_LOCAL_IP6(3)\fP +.IP CURLOPT_DNS_SERVERS +Preferred DNS servers. See \fICURLOPT_DNS_SERVERS(3)\fP +.IP CURLOPT_DNS_SHUFFLE_ADDRESSES +Shuffle addresses before use. See \fICURLOPT_DNS_SHUFFLE_ADDRESSES(3)\fP +.IP CURLOPT_DNS_USE_GLOBAL_CACHE +\fBOBSOLETE\fP Enable global DNS cache. See \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP +.IP CURLOPT_DOH_SSL_VERIFYHOST +Verify the hostname in the DoH (DNS\-over\-HTTPS) SSL certificate. See +\fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP +.IP CURLOPT_DOH_SSL_VERIFYPEER +Verify the DoH (DNS\-over\-HTTPS) SSL certificate. See +\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP +.IP CURLOPT_DOH_SSL_VERIFYSTATUS +Verify the DoH (DNS\-over\-HTTPS) SSL certificate\(aqs status. See +\fICURLOPT_DOH_SSL_VERIFYSTATUS(3)\fP +.IP CURLOPT_DOH_URL +Use this DoH server for name resolves. See \fICURLOPT_DOH_URL(3)\fP +.IP CURLOPT_ECH +Set the configuration for ECH. See \fICURLOPT_ECH(3)\fP +.IP CURLOPT_EGDSOCKET +\fBOBSOLETE\fP Identify EGD socket for entropy. See \fICURLOPT_EGDSOCKET(3)\fP +.IP CURLOPT_ERRORBUFFER +Error message buffer. See \fICURLOPT_ERRORBUFFER(3)\fP +.IP CURLOPT_EXPECT_100_TIMEOUT_MS +100\-continue timeout. See \fICURLOPT_EXPECT_100_TIMEOUT_MS(3)\fP +.IP CURLOPT_FAILONERROR +Fail on HTTP 4xx errors. \fICURLOPT_FAILONERROR(3)\fP +.IP CURLOPT_FILETIME +Request file modification date and time. See \fICURLOPT_FILETIME(3)\fP +.IP CURLOPT_FNMATCH_DATA +Data pointer to pass to the wildcard matching callback. See +\fICURLOPT_FNMATCH_DATA(3)\fP +.IP CURLOPT_FNMATCH_FUNCTION +Callback for wildcard matching. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP +.IP CURLOPT_FOLLOWLOCATION +Follow HTTP redirects. See \fICURLOPT_FOLLOWLOCATION(3)\fP +.IP CURLOPT_FORBID_REUSE +Prevent subsequent connections from reusing this. See \fICURLOPT_FORBID_REUSE(3)\fP +.IP CURLOPT_FRESH_CONNECT +Use a new connection. \fICURLOPT_FRESH_CONNECT(3)\fP +.IP CURLOPT_FTPPORT +Use active FTP. See \fICURLOPT_FTPPORT(3)\fP +.IP CURLOPT_FTPSSLAUTH +Control how to do TLS. See \fICURLOPT_FTPSSLAUTH(3)\fP +.IP CURLOPT_FTP_ACCOUNT +Send ACCT command. See \fICURLOPT_FTP_ACCOUNT(3)\fP +.IP CURLOPT_FTP_ALTERNATIVE_TO_USER +Alternative to USER. See \fICURLOPT_FTP_ALTERNATIVE_TO_USER(3)\fP +.IP CURLOPT_FTP_CREATE_MISSING_DIRS +Create missing directories on the remote server. See +\fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP +.IP CURLOPT_FTP_FILEMETHOD +Specify how to reach files. See \fICURLOPT_FTP_FILEMETHOD(3)\fP +.IP CURLOPT_FTP_SKIP_PASV_IP +Ignore the IP address in the PASV response. See \fICURLOPT_FTP_SKIP_PASV_IP(3)\fP +.IP CURLOPT_FTP_SSL_CCC +Back to non\-TLS again after authentication. See \fICURLOPT_FTP_SSL_CCC(3)\fP +.IP CURLOPT_FTP_USE_EPRT +Use EPRT. See \fICURLOPT_FTP_USE_EPRT(3)\fP +.IP CURLOPT_FTP_USE_EPSV +Use EPSV. See \fICURLOPT_FTP_USE_EPSV(3)\fP +.IP CURLOPT_FTP_USE_PRET +Use PRET. See \fICURLOPT_FTP_USE_PRET(3)\fP +.IP CURLOPT_GSSAPI_DELEGATION +Disable GSS\-API delegation. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP +.IP CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS +Timeout for happy eyeballs. See \fICURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)\fP +.IP CURLOPT_HAPROXYPROTOCOL +Send an HAProxy PROXY protocol v1 header. See \fICURLOPT_HAPROXYPROTOCOL(3)\fP +.IP CURLOPT_HAPROXY_CLIENT_IP +Spoof the client IP in an HAProxy PROXY protocol v1 header. See +\fICURLOPT_HAPROXY_CLIENT_IP(3)\fP +.IP CURLOPT_HEADER +Include the header in the body output. See \fICURLOPT_HEADER(3)\fP +.IP CURLOPT_HEADERDATA +Data pointer to pass to the header callback. See \fICURLOPT_HEADERDATA(3)\fP +.IP CURLOPT_HEADERFUNCTION +Callback for writing received headers. See \fICURLOPT_HEADERFUNCTION(3)\fP +.IP CURLOPT_HEADEROPT +Control custom headers. See \fICURLOPT_HEADEROPT(3)\fP +.IP CURLOPT_HSTS +Set HSTS cache file. See \fICURLOPT_HSTS(3)\fP +.IP CURLOPT_HSTSREADDATA +Pass pointer to the HSTS read callback. See \fICURLOPT_HSTSREADDATA(3)\fP +.IP CURLOPT_HSTSREADFUNCTION +Set HSTS read callback. See \fICURLOPT_HSTSREADFUNCTION(3)\fP +.IP CURLOPT_HSTSWRITEDATA +Pass pointer to the HSTS write callback. See \fICURLOPT_HSTSWRITEDATA(3)\fP +.IP CURLOPT_HSTSWRITEFUNCTION +Set HSTS write callback. See \fICURLOPT_HSTSWRITEFUNCTION(3)\fP +.IP CURLOPT_HSTS_CTRL +Enable HSTS. See \fICURLOPT_HSTS_CTRL(3)\fP +.IP CURLOPT_HTTP09_ALLOWED +Allow HTTP/0.9 responses. \fICURLOPT_HTTP09_ALLOWED(3)\fP +.IP CURLOPT_HTTP200ALIASES +Alternative versions of 200 OK. See \fICURLOPT_HTTP200ALIASES(3)\fP +.IP CURLOPT_HTTPAUTH +HTTP server authentication methods. See \fICURLOPT_HTTPAUTH(3)\fP +.IP CURLOPT_HTTPGET +Do an HTTP GET request. See \fICURLOPT_HTTPGET(3)\fP +.IP CURLOPT_HTTPHEADER +Custom HTTP headers. See \fICURLOPT_HTTPHEADER(3)\fP +.IP CURLOPT_HTTPPOST +\fBDeprecated option\fP Multipart formpost HTTP POST. +See \fICURLOPT_HTTPPOST(3)\fP +.IP CURLOPT_HTTPPROXYTUNNEL +Tunnel through the HTTP proxy. \fICURLOPT_HTTPPROXYTUNNEL(3)\fP +.IP CURLOPT_HTTP_CONTENT_DECODING +Disable Content decoding. See \fICURLOPT_HTTP_CONTENT_DECODING(3)\fP +.IP CURLOPT_HTTP_TRANSFER_DECODING +Disable Transfer decoding. See \fICURLOPT_HTTP_TRANSFER_DECODING(3)\fP +.IP CURLOPT_HTTP_VERSION +HTTP version to use. \fICURLOPT_HTTP_VERSION(3)\fP +.IP CURLOPT_IGNORE_CONTENT_LENGTH +Ignore Content\-Length. See \fICURLOPT_IGNORE_CONTENT_LENGTH(3)\fP +.IP CURLOPT_INFILESIZE +Size of file to send. \fICURLOPT_INFILESIZE(3)\fP +.IP CURLOPT_INFILESIZE_LARGE +Size of file to send. \fICURLOPT_INFILESIZE_LARGE(3)\fP +.IP CURLOPT_INTERFACE +Bind connection locally to this. See \fICURLOPT_INTERFACE(3)\fP +.IP CURLOPT_INTERLEAVEDATA +Data pointer to pass to the RTSP interleave callback. See +\fICURLOPT_INTERLEAVEDATA(3)\fP +.IP CURLOPT_INTERLEAVEFUNCTION +Callback for RTSP interleaved data. See \fICURLOPT_INTERLEAVEFUNCTION(3)\fP +.IP CURLOPT_IOCTLDATA +\fBDeprecated option\fP Data pointer to pass to the I/O callback. +See \fICURLOPT_IOCTLDATA(3)\fP +.IP CURLOPT_IOCTLFUNCTION +\fBDeprecated option\fP Callback for I/O operations. +See \fICURLOPT_IOCTLFUNCTION(3)\fP +.IP CURLOPT_IPRESOLVE +IP version to use. See \fICURLOPT_IPRESOLVE(3)\fP +.IP CURLOPT_ISSUERCERT +Issuer certificate. See \fICURLOPT_ISSUERCERT(3)\fP +.IP CURLOPT_ISSUERCERT_BLOB +Issuer certificate memory buffer. See \fICURLOPT_ISSUERCERT_BLOB(3)\fP +.IP CURLOPT_KEEP_SENDING_ON_ERROR +Keep sending on HTTP >= 300 errors. \fICURLOPT_KEEP_SENDING_ON_ERROR(3)\fP +.IP CURLOPT_KEYPASSWD +Client key password. See \fICURLOPT_KEYPASSWD(3)\fP +.IP CURLOPT_KRBLEVEL +Kerberos security level. See \fICURLOPT_KRBLEVEL(3)\fP +.IP CURLOPT_LOCALPORT +Bind connection locally to this port. See \fICURLOPT_LOCALPORT(3)\fP +.IP CURLOPT_LOCALPORTRANGE +Bind connection locally to port range. See \fICURLOPT_LOCALPORTRANGE(3)\fP +.IP CURLOPT_LOGIN_OPTIONS +Login options. See \fICURLOPT_LOGIN_OPTIONS(3)\fP +.IP CURLOPT_LOW_SPEED_LIMIT +Low speed limit to abort transfer. See \fICURLOPT_LOW_SPEED_LIMIT(3)\fP +.IP CURLOPT_LOW_SPEED_TIME +Time to be below the speed to trigger low speed abort. See +\fICURLOPT_LOW_SPEED_TIME(3)\fP +.IP CURLOPT_MAIL_AUTH +Authentication address. See \fICURLOPT_MAIL_AUTH(3)\fP +.IP CURLOPT_MAIL_FROM +Address of the sender. See \fICURLOPT_MAIL_FROM(3)\fP +.IP CURLOPT_MAIL_RCPT +Address of the recipients. See \fICURLOPT_MAIL_RCPT(3)\fP +.IP CURLOPT_MAIL_RCPT_ALLOWFAILS +Allow RCPT TO command to fail for some recipients. See +\fICURLOPT_MAIL_RCPT_ALLOWFAILS(3)\fP +.IP CURLOPT_MAXAGE_CONN +Limit the age (idle time) of connections for reuse. See \fICURLOPT_MAXAGE_CONN(3)\fP +.IP CURLOPT_MAXCONNECTS +Maximum number of connections in the connection pool. See +\fICURLOPT_MAXCONNECTS(3)\fP +.IP CURLOPT_MAXFILESIZE +Maximum file size to get. See \fICURLOPT_MAXFILESIZE(3)\fP +.IP CURLOPT_MAXFILESIZE_LARGE +Maximum file size to get. See \fICURLOPT_MAXFILESIZE_LARGE(3)\fP +.IP CURLOPT_MAXLIFETIME_CONN +Limit the age (since creation) of connections for reuse. See +\fICURLOPT_MAXLIFETIME_CONN(3)\fP +.IP CURLOPT_MAXREDIRS +Maximum number of redirects to follow. See \fICURLOPT_MAXREDIRS(3)\fP +.IP CURLOPT_MAX_RECV_SPEED_LARGE +Cap the download speed to this. See \fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP +.IP CURLOPT_MAX_SEND_SPEED_LARGE +Cap the upload speed to this. See \fICURLOPT_MAX_SEND_SPEED_LARGE(3)\fP +.IP CURLOPT_MIMEPOST +Post/send MIME data. See \fICURLOPT_MIMEPOST(3)\fP +.IP CURLOPT_MIME_OPTIONS +Set MIME option flags. See \fICURLOPT_MIME_OPTIONS(3)\fP +.IP CURLOPT_NETRC +Enable .netrc parsing. See \fICURLOPT_NETRC(3)\fP +.IP CURLOPT_NETRC_FILE +\&.netrc filename. See \fICURLOPT_NETRC_FILE(3)\fP +.IP CURLOPT_NEW_DIRECTORY_PERMS +Mode for creating new remote directories. See \fICURLOPT_NEW_DIRECTORY_PERMS(3)\fP +.IP CURLOPT_NEW_FILE_PERMS +Mode for creating new remote files. See \fICURLOPT_NEW_FILE_PERMS(3)\fP +.IP CURLOPT_NOBODY +Do not get the body contents. See \fICURLOPT_NOBODY(3)\fP +.IP CURLOPT_NOPROGRESS +Shut off the progress meter. See \fICURLOPT_NOPROGRESS(3)\fP +.IP CURLOPT_NOPROXY +Filter out hosts from proxy use. \fICURLOPT_NOPROXY(3)\fP +.IP CURLOPT_NOSIGNAL +Do not install signal handlers. See \fICURLOPT_NOSIGNAL(3)\fP +.IP CURLOPT_OPENSOCKETDATA +Data pointer to pass to the open socket callback. See \fICURLOPT_OPENSOCKETDATA(3)\fP +.IP CURLOPT_OPENSOCKETFUNCTION +Callback for socket creation. See \fICURLOPT_OPENSOCKETFUNCTION(3)\fP +.IP CURLOPT_PASSWORD +Password. See \fICURLOPT_PASSWORD(3)\fP +.IP CURLOPT_PATH_AS_IS +Disable squashing /../ and /./ sequences in the path. See \fICURLOPT_PATH_AS_IS(3)\fP +.IP CURLOPT_PINNEDPUBLICKEY +Set pinned SSL public key . See \fICURLOPT_PINNEDPUBLICKEY(3)\fP +.IP CURLOPT_PIPEWAIT +Wait on connection to pipeline on it. See \fICURLOPT_PIPEWAIT(3)\fP +.IP CURLOPT_PORT +Port number to connect to. See \fICURLOPT_PORT(3)\fP +.IP CURLOPT_POST +Make an HTTP POST. See \fICURLOPT_POST(3)\fP +.IP CURLOPT_POSTFIELDSIZE +The POST data is this big. See \fICURLOPT_POSTFIELDSIZE(3)\fP +.IP CURLOPT_POSTFIELDSIZE_LARGE +The POST data is this big. See \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP +.IP CURLOPT_POSTQUOTE +Commands to run after transfer. See \fICURLOPT_POSTQUOTE(3)\fP +.IP CURLOPT_POSTREDIR +How to act on redirects after POST. See \fICURLOPT_POSTREDIR(3)\fP +.IP CURLOPT_PREQUOTE +Commands to run just before transfer. See \fICURLOPT_PREQUOTE(3)\fP +.IP CURLOPT_PREREQDATA +Data pointer to pass to the CURLOPT_PREREQFUNCTION callback. See +\fICURLOPT_PREREQDATA(3)\fP +.IP CURLOPT_PREREQFUNCTION +Callback to be called after a connection is established but before a request +is made on that connection. See \fICURLOPT_PREREQFUNCTION(3)\fP +.IP CURLOPT_PRE_PROXY +Socks proxy to use. See \fICURLOPT_PRE_PROXY(3)\fP +.IP CURLOPT_PRIVATE +Private pointer to store. See \fICURLOPT_PRIVATE(3)\fP +.IP CURLOPT_PROGRESSDATA +Data pointer to pass to the progress meter callback. See +\fICURLOPT_PROGRESSDATA(3)\fP +.IP CURLOPT_PROGRESSFUNCTION +\fBOBSOLETE\fP callback for progress meter. See \fICURLOPT_PROGRESSFUNCTION(3)\fP +.IP CURLOPT_PROTOCOLS +\fBDeprecated option\fP Allowed protocols. See \fICURLOPT_PROTOCOLS(3)\fP +.IP CURLOPT_PROTOCOLS_STR +Allowed protocols. See \fICURLOPT_PROTOCOLS_STR(3)\fP +.IP CURLOPT_PROXY +Proxy to use. See \fICURLOPT_PROXY(3)\fP +.IP CURLOPT_PROXYAUTH +HTTP proxy authentication methods. See \fICURLOPT_PROXYAUTH(3)\fP +.IP CURLOPT_PROXYHEADER +Custom HTTP headers sent to proxy. See \fICURLOPT_PROXYHEADER(3)\fP +.IP CURLOPT_PROXYPASSWORD +Proxy password. See \fICURLOPT_PROXYPASSWORD(3)\fP +.IP CURLOPT_PROXYPORT +Proxy port to use. See \fICURLOPT_PROXYPORT(3)\fP +.IP CURLOPT_PROXYTYPE +Proxy type. See \fICURLOPT_PROXYTYPE(3)\fP +.IP CURLOPT_PROXYUSERNAME +Proxy username. See \fICURLOPT_PROXYUSERNAME(3)\fP +.IP CURLOPT_PROXYUSERPWD +Proxy username and password. See \fICURLOPT_PROXYUSERPWD(3)\fP +.IP CURLOPT_PROXY_CAINFO +Proxy CA cert bundle. See \fICURLOPT_PROXY_CAINFO(3)\fP +.IP CURLOPT_PROXY_CAINFO_BLOB +Proxy CA cert bundle memory buffer. See \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP +.IP CURLOPT_PROXY_CAPATH +Path to proxy CA cert bundle. See \fICURLOPT_PROXY_CAPATH(3)\fP +.IP CURLOPT_PROXY_CRLFILE +Proxy Certificate Revocation List. See \fICURLOPT_PROXY_CRLFILE(3)\fP +.IP CURLOPT_PROXY_ISSUERCERT +Proxy issuer certificate. See \fICURLOPT_PROXY_ISSUERCERT(3)\fP +.IP CURLOPT_PROXY_ISSUERCERT_BLOB +Proxy issuer certificate memory buffer. See \fICURLOPT_PROXY_ISSUERCERT_BLOB(3)\fP +.IP CURLOPT_PROXY_KEYPASSWD +Proxy client key password. See \fICURLOPT_PROXY_KEYPASSWD(3)\fP +.IP CURLOPT_PROXY_PINNEDPUBLICKEY +Set the proxy\(aqs pinned SSL public key. See +\fICURLOPT_PROXY_PINNEDPUBLICKEY(3)\fP +.IP CURLOPT_PROXY_SERVICE_NAME +Proxy authentication service name. \fICURLOPT_PROXY_SERVICE_NAME(3)\fP +.IP CURLOPT_PROXY_SSLCERT +Proxy client cert. See \fICURLOPT_PROXY_SSLCERT(3)\fP +.IP CURLOPT_PROXY_SSLCERTTYPE +Proxy client cert type. See \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP +.IP CURLOPT_PROXY_SSLCERT_BLOB +Proxy client cert memory buffer. See \fICURLOPT_PROXY_SSLCERT_BLOB(3)\fP +.IP CURLOPT_PROXY_SSLKEY +Proxy client key. See \fICURLOPT_PROXY_SSLKEY(3)\fP +.IP CURLOPT_PROXY_SSLKEYTYPE +Proxy client key type. See \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP +.IP CURLOPT_PROXY_SSLKEY_BLOB +Proxy client key. See \fICURLOPT_PROXY_SSLKEY_BLOB(3)\fP +.IP CURLOPT_PROXY_SSLVERSION +Proxy SSL version to use. See \fICURLOPT_PROXY_SSLVERSION(3)\fP +.IP CURLOPT_PROXY_SSL_CIPHER_LIST +Proxy ciphers to use. See \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP +.IP CURLOPT_PROXY_SSL_OPTIONS +Control proxy SSL behavior. See \fICURLOPT_PROXY_SSL_OPTIONS(3)\fP +.IP CURLOPT_PROXY_SSL_VERIFYHOST +Verify the hostname in the proxy SSL certificate. See +\fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP +.IP CURLOPT_PROXY_SSL_VERIFYPEER +Verify the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP +.IP CURLOPT_PROXY_TLS13_CIPHERS +Proxy TLS 1.3 cipher suites to use. See \fICURLOPT_PROXY_TLS13_CIPHERS(3)\fP +.IP CURLOPT_PROXY_TLSAUTH_PASSWORD +Proxy TLS authentication password. See \fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP +.IP CURLOPT_PROXY_TLSAUTH_TYPE +Proxy TLS authentication methods. See \fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP +.IP CURLOPT_PROXY_TLSAUTH_USERNAME +Proxy TLS authentication username. See \fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP +.IP CURLOPT_PROXY_TRANSFER_MODE +Add transfer mode to URL over proxy. See \fICURLOPT_PROXY_TRANSFER_MODE(3)\fP +.IP CURLOPT_PUT +\fBDeprecated option\fP Issue an HTTP PUT request. See \fICURLOPT_PUT(3)\fP +.IP CURLOPT_QUICK_EXIT +To be set by toplevel tools like "curl" to skip lengthy cleanups when they are +about to call exit() anyway. See \fICURLOPT_QUICK_EXIT(3)\fP +.IP CURLOPT_QUOTE +Commands to run before transfer. See \fICURLOPT_QUOTE(3)\fP +.IP CURLOPT_RANDOM_FILE +\fBOBSOLETE\fP Provide source for entropy random data. +See \fICURLOPT_RANDOM_FILE(3)\fP +.IP CURLOPT_RANGE +Range requests. See \fICURLOPT_RANGE(3)\fP +.IP CURLOPT_READDATA +Data pointer to pass to the read callback. See \fICURLOPT_READDATA(3)\fP +.IP CURLOPT_READFUNCTION +Callback for reading data. See \fICURLOPT_READFUNCTION(3)\fP +.IP CURLOPT_REDIR_PROTOCOLS +\fBDeprecated option\fP Protocols to allow redirects to. See +\fICURLOPT_REDIR_PROTOCOLS(3)\fP +.IP CURLOPT_REDIR_PROTOCOLS_STR +Protocols to allow redirects to. See \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP +.IP CURLOPT_REFERER +Referer: header. See \fICURLOPT_REFERER(3)\fP +.IP CURLOPT_REQUEST_TARGET +Set the request target. \fICURLOPT_REQUEST_TARGET(3)\fP +.IP CURLOPT_RESOLVE +Provide fixed/fake name resolves. See \fICURLOPT_RESOLVE(3)\fP +.IP CURLOPT_RESOLVER_START_DATA +Data pointer to pass to resolver start callback. See +\fICURLOPT_RESOLVER_START_DATA(3)\fP +.IP CURLOPT_RESOLVER_START_FUNCTION +Callback to be called before a new resolve request is started. See +\fICURLOPT_RESOLVER_START_FUNCTION(3)\fP +.IP CURLOPT_RESUME_FROM +Resume a transfer. See \fICURLOPT_RESUME_FROM(3)\fP +.IP CURLOPT_RESUME_FROM_LARGE +Resume a transfer. See \fICURLOPT_RESUME_FROM_LARGE(3)\fP +.IP CURLOPT_RTSP_CLIENT_CSEQ +Client CSEQ number. See \fICURLOPT_RTSP_CLIENT_CSEQ(3)\fP +.IP CURLOPT_RTSP_REQUEST +RTSP request. See \fICURLOPT_RTSP_REQUEST(3)\fP +.IP CURLOPT_RTSP_SERVER_CSEQ +CSEQ number for RTSP Server\->Client request. See \fICURLOPT_RTSP_SERVER_CSEQ(3)\fP +.IP CURLOPT_RTSP_SESSION_ID +RTSP session\-id. See \fICURLOPT_RTSP_SESSION_ID(3)\fP +.IP CURLOPT_RTSP_STREAM_URI +RTSP stream URI. See \fICURLOPT_RTSP_STREAM_URI(3)\fP +.IP CURLOPT_RTSP_TRANSPORT +RTSP Transport: header. See \fICURLOPT_RTSP_TRANSPORT(3)\fP +.IP CURLOPT_SASL_AUTHZID +SASL authorization identity (identity to act as). See \fICURLOPT_SASL_AUTHZID(3)\fP +.IP CURLOPT_SASL_IR +Enable SASL initial response. See \fICURLOPT_SASL_IR(3)\fP +.IP CURLOPT_SEEKDATA +Data pointer to pass to the seek callback. See \fICURLOPT_SEEKDATA(3)\fP +.IP CURLOPT_SEEKFUNCTION +Callback for seek operations. See \fICURLOPT_SEEKFUNCTION(3)\fP +.IP CURLOPT_SERVER_RESPONSE_TIMEOUT +Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP +.IP CURLOPT_SERVER_RESPONSE_TIMEOUT_MS +Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP +.IP CURLOPT_SERVICE_NAME +Authentication service name. \fICURLOPT_SERVICE_NAME(3)\fP +.IP CURLOPT_SHARE +Share object to use. See \fICURLOPT_SHARE(3)\fP +.IP CURLOPT_SOCKOPTDATA +Data pointer to pass to the sockopt callback. See \fICURLOPT_SOCKOPTDATA(3)\fP +.IP CURLOPT_SOCKOPTFUNCTION +Callback for sockopt operations. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP +.IP CURLOPT_SOCKS5_AUTH +Socks5 authentication methods. See \fICURLOPT_SOCKS5_AUTH(3)\fP +.IP CURLOPT_SOCKS5_GSSAPI_NEC +Socks5 GSSAPI NEC mode. See \fICURLOPT_SOCKS5_GSSAPI_NEC(3)\fP +.IP CURLOPT_SOCKS5_GSSAPI_SERVICE +\fBDeprecated option\fP Socks5 GSSAPI service name. +See \fICURLOPT_SOCKS5_GSSAPI_SERVICE(3)\fP +.IP CURLOPT_SSH_AUTH_TYPES +SSH authentication types. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP +.IP CURLOPT_SSH_COMPRESSION +Enable SSH compression. See \fICURLOPT_SSH_COMPRESSION(3)\fP +.IP CURLOPT_SSH_HOSTKEYDATA +Custom pointer to pass to ssh host key callback. See \fICURLOPT_SSH_HOSTKEYDATA(3)\fP +.IP CURLOPT_SSH_HOSTKEYFUNCTION +Callback for checking host key handling. See \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP +.IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 +MD5 of host\(aqs public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3)\fP +.IP CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 +SHA256 of host\(aqs public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP +.IP CURLOPT_SSH_KEYDATA +Custom pointer to pass to ssh key callback. See \fICURLOPT_SSH_KEYDATA(3)\fP +.IP CURLOPT_SSH_KEYFUNCTION +Callback for known hosts handling. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP +.IP CURLOPT_SSH_KNOWNHOSTS +Filename with known hosts. See \fICURLOPT_SSH_KNOWNHOSTS(3)\fP +.IP CURLOPT_SSH_PRIVATE_KEYFILE +Filename of the private key. See \fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP +.IP CURLOPT_SSH_PUBLIC_KEYFILE +Filename of the public key. See \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP +.IP CURLOPT_SSLCERT +Client cert. See \fICURLOPT_SSLCERT(3)\fP +.IP CURLOPT_SSLCERTTYPE +Client cert type. See \fICURLOPT_SSLCERTTYPE(3)\fP +.IP CURLOPT_SSLCERT_BLOB +Client cert memory buffer. See \fICURLOPT_SSLCERT_BLOB(3)\fP +.IP CURLOPT_SSLENGINE +Use identifier with SSL engine. See \fICURLOPT_SSLENGINE(3)\fP +.IP CURLOPT_SSLENGINE_DEFAULT +Default SSL engine. See \fICURLOPT_SSLENGINE_DEFAULT(3)\fP +.IP CURLOPT_SSLKEY +Client key. See \fICURLOPT_SSLKEY(3)\fP +.IP CURLOPT_SSLKEYTYPE +Client key type. See \fICURLOPT_SSLKEYTYPE(3)\fP +.IP CURLOPT_SSLKEY_BLOB +Client key memory buffer. See \fICURLOPT_SSLKEY_BLOB(3)\fP +.IP CURLOPT_SSLVERSION +SSL version to use. See \fICURLOPT_SSLVERSION(3)\fP +.IP CURLOPT_SSL_CIPHER_LIST +Ciphers to use. See \fICURLOPT_SSL_CIPHER_LIST(3)\fP +.IP CURLOPT_SSL_CTX_DATA +Data pointer to pass to the SSL context callback. See \fICURLOPT_SSL_CTX_DATA(3)\fP +.IP CURLOPT_SSL_CTX_FUNCTION +Callback for SSL context logic. See \fICURLOPT_SSL_CTX_FUNCTION(3)\fP +.IP CURLOPT_SSL_EC_CURVES +Set key exchange curves. See \fICURLOPT_SSL_EC_CURVES(3)\fP +.IP CURLOPT_SSL_ENABLE_ALPN +Enable use of ALPN. See \fICURLOPT_SSL_ENABLE_ALPN(3)\fP +.IP CURLOPT_SSL_ENABLE_NPN +\fBOBSOLETE\fP Enable use of NPN. See \fICURLOPT_SSL_ENABLE_NPN(3)\fP +.IP CURLOPT_SSL_FALSESTART +Enable TLS False Start. See \fICURLOPT_SSL_FALSESTART(3)\fP +.IP CURLOPT_SSL_OPTIONS +Control SSL behavior. See \fICURLOPT_SSL_OPTIONS(3)\fP +.IP CURLOPT_SSL_SESSIONID_CACHE +Disable SSL session\-id cache. See \fICURLOPT_SSL_SESSIONID_CACHE(3)\fP +.IP CURLOPT_SSL_VERIFYHOST +Verify the hostname in the SSL certificate. See \fICURLOPT_SSL_VERIFYHOST(3)\fP +.IP CURLOPT_SSL_VERIFYPEER +Verify the SSL certificate. See \fICURLOPT_SSL_VERIFYPEER(3)\fP +.IP CURLOPT_SSL_VERIFYSTATUS +Verify the SSL certificate\(aqs status. See \fICURLOPT_SSL_VERIFYSTATUS(3)\fP +.IP CURLOPT_STDERR +Redirect stderr to another stream. See \fICURLOPT_STDERR(3)\fP +.IP CURLOPT_STREAM_DEPENDS +This HTTP/2 stream depends on another. See \fICURLOPT_STREAM_DEPENDS(3)\fP +.IP CURLOPT_STREAM_DEPENDS_E +This HTTP/2 stream depends on another exclusively. See +\fICURLOPT_STREAM_DEPENDS_E(3)\fP +.IP CURLOPT_STREAM_WEIGHT +Set this HTTP/2 stream\(aqs weight. See \fICURLOPT_STREAM_WEIGHT(3)\fP +.IP CURLOPT_SUPPRESS_CONNECT_HEADERS +Suppress proxy CONNECT response headers from user callbacks. See +\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP +.IP CURLOPT_TCP_FASTOPEN +Enable TCP Fast Open. See \fICURLOPT_TCP_FASTOPEN(3)\fP +.IP CURLOPT_TCP_KEEPALIVE +Enable TCP keep\-alive. See \fICURLOPT_TCP_KEEPALIVE(3)\fP +.IP CURLOPT_TCP_KEEPCNT +Maximum number of keep\-alive probes. See \fICURLOPT_TCP_KEEPCNT(3)\fP +.IP CURLOPT_TCP_KEEPIDLE +Idle time before sending keep\-alive. See \fICURLOPT_TCP_KEEPIDLE(3)\fP +.IP CURLOPT_TCP_KEEPINTVL +Interval between keep\-alive probes. See \fICURLOPT_TCP_KEEPINTVL(3)\fP +.IP CURLOPT_TCP_NODELAY +Disable the Nagle algorithm. See \fICURLOPT_TCP_NODELAY(3)\fP +.IP CURLOPT_TELNETOPTIONS +TELNET options. See \fICURLOPT_TELNETOPTIONS(3)\fP +.IP CURLOPT_TFTP_BLKSIZE +TFTP block size. See \fICURLOPT_TFTP_BLKSIZE(3)\fP +.IP CURLOPT_TFTP_NO_OPTIONS +Do not send TFTP options requests. See \fICURLOPT_TFTP_NO_OPTIONS(3)\fP +.IP CURLOPT_TIMECONDITION +Make a time conditional request. See \fICURLOPT_TIMECONDITION(3)\fP +.IP CURLOPT_TIMEOUT +Timeout for the entire request. See \fICURLOPT_TIMEOUT(3)\fP +.IP CURLOPT_TIMEOUT_MS +Millisecond timeout for the entire request. See \fICURLOPT_TIMEOUT_MS(3)\fP +.IP CURLOPT_TIMEVALUE +Time value for the time conditional request. See \fICURLOPT_TIMEVALUE(3)\fP +.IP CURLOPT_TIMEVALUE_LARGE +Time value for the time conditional request. See \fICURLOPT_TIMEVALUE_LARGE(3)\fP +.IP CURLOPT_TLS13_CIPHERS +TLS 1.3 cipher suites to use. See \fICURLOPT_TLS13_CIPHERS(3)\fP +.IP CURLOPT_TLSAUTH_PASSWORD +TLS authentication password. See \fICURLOPT_TLSAUTH_PASSWORD(3)\fP +.IP CURLOPT_TLSAUTH_TYPE +TLS authentication methods. See \fICURLOPT_TLSAUTH_TYPE(3)\fP +.IP CURLOPT_TLSAUTH_USERNAME +TLS authentication username. See \fICURLOPT_TLSAUTH_USERNAME(3)\fP +.IP CURLOPT_TRAILERDATA +Custom pointer passed to the trailing headers callback. See +\fICURLOPT_TRAILERDATA(3)\fP +.IP CURLOPT_TRAILERFUNCTION +Set callback for sending trailing headers. See +\fICURLOPT_TRAILERFUNCTION(3)\fP +.IP CURLOPT_TRANSFERTEXT +Use text transfer. See \fICURLOPT_TRANSFERTEXT(3)\fP +.IP CURLOPT_TRANSFER_ENCODING +Request Transfer\-Encoding. See \fICURLOPT_TRANSFER_ENCODING(3)\fP +.IP CURLOPT_UNIX_SOCKET_PATH +Path to a Unix domain socket. See \fICURLOPT_UNIX_SOCKET_PATH(3)\fP +.IP CURLOPT_UNRESTRICTED_AUTH +Do not restrict authentication to original host. \fICURLOPT_UNRESTRICTED_AUTH(3)\fP +.IP CURLOPT_UPKEEP_INTERVAL_MS +Sets the interval at which connection upkeep are performed. See +\fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP +.IP CURLOPT_UPLOAD +Upload data. See \fICURLOPT_UPLOAD(3)\fP +.IP CURLOPT_UPLOAD_BUFFERSIZE +Set upload buffer size. See \fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP +.IP CURLOPT_URL +URL to work on. See \fICURLOPT_URL(3)\fP +.IP CURLOPT_USERAGENT +User\-Agent: header. See \fICURLOPT_USERAGENT(3)\fP +.IP CURLOPT_USERNAME +Username. See \fICURLOPT_USERNAME(3)\fP +.IP CURLOPT_USERPWD +Username and password. See \fICURLOPT_USERPWD(3)\fP +.IP CURLOPT_USE_SSL +Use TLS/SSL. See \fICURLOPT_USE_SSL(3)\fP +.IP CURLOPT_VERBOSE +Display verbose information. See \fICURLOPT_VERBOSE(3)\fP +.IP CURLOPT_WILDCARDMATCH +Transfer multiple files according to a filename pattern. See +\fICURLOPT_WILDCARDMATCH(3)\fP +.IP CURLOPT_WRITEDATA +Data pointer to pass to the write callback. See \fICURLOPT_WRITEDATA(3)\fP +.IP CURLOPT_WRITEFUNCTION +Callback for writing data. See \fICURLOPT_WRITEFUNCTION(3)\fP +.IP CURLOPT_WS_OPTIONS +Set WebSocket options. See \fICURLOPT_WS_OPTIONS(3)\fP +.IP CURLOPT_XFERINFODATA +Data pointer to pass to the progress meter callback. See +\fICURLOPT_XFERINFODATA(3)\fP +.IP CURLOPT_XFERINFOFUNCTION +Callback for progress meter. See \fICURLOPT_XFERINFOFUNCTION(3)\fP +.IP CURLOPT_XOAUTH2_BEARER +OAuth2 bearer token. See \fICURLOPT_XOAUTH2_BEARER(3)\fP +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +\fICURLE_OK\fP (zero) means that the option was set properly, non\-zero means an +error occurred as \fI\fP defines. See the \fIlibcurl\-errors(3)\fP man +page for the full list with descriptions. + +Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise +\fIcurl_easy_setopt(3)\fP returns \fBCURLE_BAD_FUNCTION_ARGUMENT\fP (added in 7.65.0). + +\fBCURLE_BAD_FUNCTION_ARGUMENT\fP is returned when the argument to an option is +invalid, like perhaps out of range. + +If you try to set an option that libcurl does not know about, perhaps because +the library is too old to support it or the option was removed in a recent +version, this function returns \fICURLE_UNKNOWN_OPTION\fP. If support for the +option was disabled at compile\-time, it returns \fICURLE_NOT_BUILT_IN\fP. +.SH SEE ALSO +.BR curl_easy_cleanup (3), +.BR curl_easy_getinfo (3), +.BR curl_easy_init (3), +.BR curl_easy_option_by_id (3), +.BR curl_easy_option_by_name (3), +.BR curl_easy_option_next (3), +.BR curl_easy_reset (3), +.BR curl_multi_setopt (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_strerror.3 b/3rdparty/curl/share/man/man3/curl_easy_strerror.3 new file mode 100644 index 0000000..62a4e86 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_strerror.3 @@ -0,0 +1,44 @@ +.\" generated by cd2nroff 0.1 from curl_easy_strerror.md +.TH curl_easy_strerror 3 "2024-10-11" libcurl +.SH NAME +curl_easy_strerror \- return string describing error code +.SH SYNOPSIS +.nf +#include + +const char *curl_easy_strerror(CURLcode errornum); +.fi +.SH DESCRIPTION +The \fIcurl_easy_strerror(3)\fP function returns a string describing the +CURLcode error code passed in the argument \fIerrornum\fP. + +Typically applications also appreciate \fICURLOPT_ERRORBUFFER(3)\fP for more +specific error descriptions generated at runtime. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + /* set options */ + /* Perform the entire transfer */ + res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\\n", + curl_easy_strerror(res)); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.12.0 +.SH RETURN VALUE +A pointer to a null\-terminated string. +.SH SEE ALSO +.BR curl_multi_strerror (3), +.BR curl_share_strerror (3), +.BR curl_url_strerror (3), +.BR libcurl-errors (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_unescape.3 b/3rdparty/curl/share/man/man3/curl_easy_unescape.3 new file mode 100644 index 0000000..d039c4d --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_unescape.3 @@ -0,0 +1,58 @@ +.\" generated by cd2nroff 0.1 from curl_easy_unescape.md +.TH curl_easy_unescape 3 "2024-10-11" libcurl +.SH NAME +curl_easy_unescape \- URL decode a string +.SH SYNOPSIS +.nf +#include + +char *curl_easy_unescape(CURL *curl, const char *input, + int inlength, int *outlength); +.fi +.SH DESCRIPTION +This function converts the URL encoded string \fBinput\fP to a "plain string" +and returns that in an allocated memory area. All input characters that are URL +encoded (%XX where XX is a two\-digit hexadecimal number) are converted to their +binary versions. + +If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP +uses strlen() on \fBinput\fP to find out the size. + +If \fBoutlength\fP is non\-NULL, the function writes the length of the returned +string in the integer it points to. This allows proper handling even for +strings containing %00. Since this is a pointer to an \fIint\fP type, it can +only return a value up to \fIINT_MAX\fP so no longer string can be returned in +this parameter. + +Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was +per\-handle character conversion support for some old operating systems such as +TPF, but it was otherwise ignored. + +You must \fIcurl_free(3)\fP the returned string when you are done with it. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + int decodelen; + char *decoded = curl_easy_unescape(curl, "%63%75%72%6c", 12, &decodelen); + if(decoded) { + /* do not assume printf() works on the decoded data! */ + printf("Decoded: "); + /* ... */ + curl_free(decoded); + } + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +A pointer to a null\-terminated string or NULL if it failed. +.SH SEE ALSO +.BR curl_easy_escape (3), +.BR curl_url_get (3) diff --git a/3rdparty/curl/share/man/man3/curl_easy_upkeep.3 b/3rdparty/curl/share/man/man3/curl_easy_upkeep.3 new file mode 100644 index 0000000..8982817 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_easy_upkeep.3 @@ -0,0 +1,66 @@ +.\" generated by cd2nroff 0.1 from curl_easy_upkeep.md +.TH curl_easy_upkeep 3 "2024-10-11" libcurl +.SH NAME +curl_easy_upkeep \- keep existing connections alive +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_upkeep(CURL *handle); +.fi +.SH DESCRIPTION +Some protocols have "connection upkeep" mechanisms. These mechanisms usually +send some traffic on existing connections in order to keep them alive; this +can prevent connections from being closed due to overzealous firewalls, for +example. + +Currently the only protocol with a connection upkeep mechanism is HTTP/2: when +the connection upkeep interval is exceeded and \fIcurl_easy_upkeep(3)\fP +is called, an HTTP/2 PING frame is sent on the connection. + +This function must be explicitly called in order to perform the upkeep work. +The connection upkeep interval is set with +\fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP. + +If you call this function on an easy handle that uses a shared connection cache +then upkeep is performed on the connections in that cache, even if those +connections were never used by the easy handle. (Added in 8.10.0) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* Make a connection to an HTTP/2 server. */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the interval to 30000ms / 30s */ + curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L); + + curl_easy_perform(curl); + + /* Perform more work here. */ + + /* While the connection is being held open, curl_easy_upkeep() can be + called. If curl_easy_upkeep() is called and the time since the last + upkeep exceeds the interval, then an HTTP/2 PING is sent. */ + curl_easy_upkeep(curl); + + /* Perform more work here. */ + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.62.0 +.SH RETURN VALUE +On success, returns \fBCURLE_OK\fP. + +On failure, returns the appropriate error code. +.SH SEE ALSO +.BR CURLOPT_TCP_KEEPALIVE (3), +.BR CURLOPT_TCP_KEEPIDLE (3) diff --git a/3rdparty/curl/share/man/man3/curl_escape.3 b/3rdparty/curl/share/man/man3/curl_escape.3 new file mode 100644 index 0000000..f76d46b --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_escape.3 @@ -0,0 +1,45 @@ +.\" generated by cd2nroff 0.1 from curl_escape.md +.TH curl_escape 3 "2024-10-11" libcurl +.SH NAME +curl_escape \- URL encode a string +.SH SYNOPSIS +.nf +#include + +char *curl_escape(const char *string, int length); +.fi +.SH DESCRIPTION +Obsolete function. Use \fIcurl_easy_escape(3)\fP instead! + +This function converts the given input \fBstring\fP to a URL encoded string +and return that as a new allocated string. All input characters that are not +a\-z, A\-Z or 0\-9 are converted to their "URL escaped" version (\fB%NN\fP where +\fBNN\fP is a two\-digit hexadecimal number). + +If the \fBlength\fP argument is set to 0, \fIcurl_escape(3)\fP uses strlen() +on \fBstring\fP to find out the size. + +You must \fIcurl_free(3)\fP the returned string when you are done with it. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + char *output = curl_escape("data to convert", 15); + if(output) { + printf("Encoded: %s\\n", output); + curl_free(output); + } +} +.fi +.SH HISTORY +Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function might be +removed in a future release. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +A pointer to a null\-terminated string or NULL if it failed. +.SH SEE ALSO +.BR curl_free (3), +.BR curl_unescape (3) diff --git a/3rdparty/curl/share/man/man3/curl_formadd.3 b/3rdparty/curl/share/man/man3/curl_formadd.3 new file mode 100644 index 0000000..b243e66 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_formadd.3 @@ -0,0 +1,266 @@ +.\" generated by cd2nroff 0.1 from curl_formadd.md +.TH curl_formadd 3 "2024-10-11" libcurl +.SH NAME +curl_formadd \- add a section to a multipart form POST +.SH SYNOPSIS +.nf +#include + +CURLFORMcode curl_formadd(struct curl_httppost **firstitem, + struct curl_httppost **lastitem, ...); +.fi +.SH DESCRIPTION +\fBThis function is deprecated.\fP Use \fIcurl_mime_init(3)\fP instead. + +curl_formadd() is used to append sections when building a multipart form +post. Append one section at a time until you have added all the sections you +want included and then you pass the \fIfirstitem\fP pointer as parameter to +\fICURLOPT_HTTPPOST(3)\fP. \fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and +on repeated invokes it should be left as set to allow repeated invokes to find +the end of the list faster. + +After the \fIlastitem\fP pointer follow the real arguments. + +The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to +NULL in the first call to this function. All list\-data is allocated by the +function itself. You must call \fIcurl_formfree(3)\fP on the \fIfirstitem\fP +after the form post has been done to free the resources. + +Using POST with HTTP 1.1 implies the use of a "Expect: 100\-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. + +First, there are some basics you need to understand about multipart form +posts. Each part consists of at least a NAME and a CONTENTS part. If the part +is made for file upload, there are also a stored CONTENT\-TYPE and a FILENAME. +Below, we discuss what options you use to set these properties in the parts +you want to add to your post. + +The options listed first are for making normal parts. The options from +\fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload +parts. +.SH OPTIONS +.IP CURLFORM_COPYNAME +followed by a string which provides the \fIname\fP of this part. libcurl +copies the string so your application does not need to keep it around after +this function call. If the name is not null\-terminated, you must set its +length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to +contain zero\-valued bytes. The copied data is freed by \fIcurl_formfree(3)\fP. +.IP CURLFORM_PTRNAME +followed by a string which provides the \fIname\fP of this part. libcurl uses the +pointer and refer to the data in your application, so you must make sure it +remains until curl no longer needs it. If the name is not null\-terminated, you +must set its length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to +contain zero\-valued bytes. +.IP CURLFORM_COPYCONTENTS +followed by a pointer to the contents of this part, the actual data to send +away. libcurl copies the provided data, so your application does not need to +keep it around after this function call. If the data is not null terminated, +or if you would like it to contain zero bytes, you must set the length of the +name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied data is freed by +\fIcurl_formfree(3)\fP. +.IP CURLFORM_PTRCONTENTS +followed by a pointer to the contents of this part, the actual data to send +away. libcurl uses the pointer and refer to the data in your application, so +you must make sure it remains until curl no longer needs it. If the data is +not null\-terminated, or if you would like it to contain zero bytes, you must +set its length with \fBCURLFORM_CONTENTSLENGTH\fP. +.IP CURLFORM_CONTENTLEN +followed by a curl_off_t value giving the length of the contents. Note that +for \fICURLFORM_STREAM\fP contents, this option is mandatory. + +If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents +to figure out the size. If you really want to send a zero byte content then +you must make sure strlen() on the data pointer returns zero. + +(Option added in 7.46.0) +.IP CURLFORM_CONTENTSLENGTH +(This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead!) + +followed by a long giving the length of the contents. Note that for +\fICURLFORM_STREAM\fP contents, this option is mandatory. + +If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents +to figure out the size. If you really want to send a zero byte content then +you must make sure strlen() on the data pointer returns zero. +.IP CURLFORM_FILECONTENT +followed by a filename, causes that file to be read and its contents used +as data in this part. This part does \fInot\fP automatically become a file +upload part simply because its data was read from a file. + +The specified file needs to kept around until the associated transfer is done. +.IP CURLFORM_FILE +followed by a filename, makes this part a file upload part. It sets the +\fIfilename\fP field to the basename of the provided filename, it reads the +contents of the file and passes them as data and sets the content\-type if the +given file match one of the internally known file extensions. For +\fBCURLFORM_FILE\fP the user may send one or more files in one part by +providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename +(and each \fICURLFORM_FILE\fP is allowed to have a +\fICURLFORM_CONTENTTYPE\fP). + +The given upload file has to exist in its full in the file system already when +the upload starts, as libcurl needs to read the correct file size beforehand. + +The specified file needs to kept around until the associated transfer is done. +.IP CURLFORM_CONTENTTYPE +is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a +string which provides the content\-type for this part, possibly instead of an +internally chosen one. +.IP CURLFORM_FILENAME +is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a +string, it tells libcurl to use the given string as the \fIfilename\fP in the file +upload part instead of the actual filename. +.IP CURLFORM_BUFFER +is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It +tells libcurl that the file contents are already present in a buffer. The +parameter is a string which provides the \fIfilename\fP field in the content +header. +.IP CURLFORM_BUFFERPTR +is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer +to the buffer to be uploaded. This buffer must not be freed until after +\fIcurl_easy_cleanup(3)\fP is called. You must also use +\fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer. +.IP CURLFORM_BUFFERLENGTH +is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a +long which gives the length of the buffer. +.IP CURLFORM_STREAM +Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get +data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on +to the read callback\(aqs fourth argument. If you want the part to look like a +file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that +when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be +set with the total expected length of the part unless the formpost is sent +chunked encoded. (Option added in libcurl 7.18.2) +.IP CURLFORM_ARRAY +Another possibility to send options to curl_formadd() is the +\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as +its value. Each curl_forms structure element has a \fICURLformoption\fP and a +char pointer. The final element in the array must be a CURLFORM_END. All +available options can be used in an array, except the CURLFORM_ARRAY option +itself. The last argument in such an array must always be \fBCURLFORM_END\fP. +.IP CURLFORM_CONTENTHEADER +specifies extra headers for the form POST section. This takes a curl_slist +prepared in the usual way using \fBcurl_slist_append\fP and appends the list +of headers to those libcurl automatically generates. The list must exist while +the POST occurs, if you free it before the post completes you may experience +problems. + +When you have passed the \fIstruct curl_httppost\fP pointer to +\fIcurl_easy_setopt(3)\fP (using the \fICURLOPT_HTTPPOST(3)\fP option), you +must not free the list until after you have called \fIcurl_easy_cleanup(3)\fP +for the curl handle. + +See example below. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +#include /* for strlen */ + +static const char record[]="data in a buffer"; + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct curl_httppost *post = NULL; + struct curl_httppost *last = NULL; + char namebuffer[] = "name buffer"; + long namelength = strlen(namebuffer); + char buffer[] = "test buffer"; + char htmlbuffer[] = "test buffer"; + long htmlbufferlength = strlen(htmlbuffer); + struct curl_forms forms[3]; + char file1[] = "my-face.jpg"; + char file2[] = "your-face.jpg"; + /* add null character into htmlbuffer, to demonstrate that + transfers of buffers containing null characters actually work + */ + htmlbuffer[8] = '\\0'; + + /* Add simple name/content section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "name", + CURLFORM_COPYCONTENTS, "content", CURLFORM_END); + + /* Add simple name/content/contenttype section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode", + CURLFORM_COPYCONTENTS, "", + CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END); + + /* Add name/ptrcontent section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent", + CURLFORM_PTRCONTENTS, buffer, CURLFORM_END); + + /* Add ptrname/ptrcontent section */ + curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer, + CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH, + namelength, CURLFORM_END); + + /* Add name/ptrcontent/contenttype section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole", + CURLFORM_PTRCONTENTS, htmlbuffer, + CURLFORM_CONTENTSLENGTH, htmlbufferlength, + CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END); + + /* Add simple file section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture", + CURLFORM_FILE, "my-face.jpg", CURLFORM_END); + + /* Add file/contenttype section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture", + CURLFORM_FILE, "my-face.jpg", + CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END); + + /* Add two file section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", + CURLFORM_FILE, "my-face.jpg", + CURLFORM_FILE, "your-face.jpg", CURLFORM_END); + + /* Add two file section using CURLFORM_ARRAY */ + forms[0].option = CURLFORM_FILE; + forms[0].value = file1; + forms[1].option = CURLFORM_FILE; + forms[1].value = file2; + forms[2].option = CURLFORM_END; + + /* Add a buffer to upload */ + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "name", + CURLFORM_BUFFER, "data", + CURLFORM_BUFFERPTR, record, + CURLFORM_BUFFERLENGTH, sizeof(record), + CURLFORM_END); + + /* no option needed for the end marker */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", + CURLFORM_ARRAY, forms, CURLFORM_END); + /* Add the content of a file as a normal post text value */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent", + CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END); + /* Set the form info */ + curl_easy_setopt(curl, CURLOPT_HTTPPOST, post); + + curl_easy_perform(curl); + + curl_easy_cleanup(curl); + + curl_formfree(post); + } +} +.fi +.SH DEPRECATED +Deprecated in 7.56.0. Before this release, field names were allowed to contain +zero\-valued bytes. The pseudo\-filename "\-" to read stdin is discouraged +although still supported, but data is not read before being actually sent: the +effective data size can then not be automatically determined, resulting in a +chunked encoding transfer. Backslashes and double quotes in field and +filenames are now escaped before transmission. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +0 means everything was OK, non\-zero means an error occurred corresponding to a +CURL_FORMADD_* constant defined in \fI\fP. +.SH SEE ALSO +.BR curl_easy_setopt (3), +.BR curl_formfree (3), +.BR curl_mime_init (3) diff --git a/3rdparty/curl/share/man/man3/curl_formfree.3 b/3rdparty/curl/share/man/man3/curl_formfree.3 new file mode 100644 index 0000000..e54644c --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_formfree.3 @@ -0,0 +1,63 @@ +.\" generated by cd2nroff 0.1 from curl_formfree.md +.TH curl_formfree 3 "2024-10-11" libcurl +.SH NAME +curl_formfree \- free a previously build multipart form post chain +.SH SYNOPSIS +.nf +#include + +void curl_formfree(struct curl_httppost *form); +.fi +.SH DESCRIPTION +This function is deprecated. Do not use. See \fIcurl_mime_init(3)\fP instead! + +curl_formfree() is used to clean up data previously built/appended with +\fIcurl_formadd(3)\fP. This must be called when the data has been used, which +typically means after \fIcurl_easy_perform(3)\fP has been called. + +The pointer to free is the same pointer you passed to the +\fICURLOPT_HTTPPOST(3)\fP option, which is the \fIfirstitem\fP pointer from +the \fIcurl_formadd(3)\fP invoke(s). + +\fBform\fP is the pointer as returned from a previous call to +\fIcurl_formadd(3)\fP and may be NULL. + +Passing in a NULL pointer in \fIform\fP makes this function return immediately +with no action. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct curl_httppost *formpost; + struct curl_httppost *lastptr; + + /* Fill in a file upload field */ + curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "file", + CURLFORM_FILE, "nice-image.jpg", + CURLFORM_END); + + curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost); + + curl_easy_perform(curl); + + /* then cleanup the formpost chain */ + curl_formfree(formpost); + } +} +.fi +.SH DEPRECATED +Deprecated in 7.56.0. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +None +.SH SEE ALSO +.BR curl_formadd (3), +.BR curl_mime_free (3), +.BR curl_mime_init (3) diff --git a/3rdparty/curl/share/man/man3/curl_formget.3 b/3rdparty/curl/share/man/man3/curl_formget.3 new file mode 100644 index 0000000..64dd458 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_formget.3 @@ -0,0 +1,57 @@ +.\" generated by cd2nroff 0.1 from curl_formget.md +.TH curl_formget 3 "2024-10-11" libcurl +.SH NAME +curl_formget \- serialize a multipart form POST chain +.SH SYNOPSIS +.nf +#include + +int curl_formget(struct curl_httppost * form, void *userp, + curl_formget_callback append); +.fi +.SH DESCRIPTION +The form API (including this function) is deprecated since libcurl 7.56.0. + +curl_formget() serializes data previously built with \fIcurl_formadd(3)\fP. It +accepts a void pointer as second argument named \fIuserp\fP which is passed as the +first argument to the curl_formget_callback function. + +.nf + typedef size_t (*curl_formget_callback)(void *userp, const char *buf, + size_t len);" +.fi + +The curl_formget_callback is invoked for each part of the HTTP POST chain. The +character buffer passed to the callback must not be freed. The callback should +return the buffer length passed to it on success. + +If the \fBCURLFORM_STREAM\fP option is used in the formpost, it prevents +\fIcurl_formget(3)\fP from working until you have performed the actual HTTP request. +This, because first then does libcurl known which actual read callback to use! +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +size_t print_httppost_callback(void *arg, const char *buf, size_t len) +{ + fwrite(buf, len, 1, stdout); + (*(size_t *) arg) += len; + return len; +} + +size_t print_httppost(struct curl_httppost *post) +{ + size_t total_size = 0; + if(curl_formget(post, &total_size, print_httppost_callback)) { + return (size_t) -1; + } + return total_size; +} +.fi +.SH AVAILABILITY +Added in curl 7.15.5 +.SH RETURN VALUE +0 means everything was OK, non\-zero means an error occurred +.SH SEE ALSO +.BR curl_formadd (3), +.BR curl_mime_init (3) diff --git a/3rdparty/curl/share/man/man3/curl_free.3 b/3rdparty/curl/share/man/man3/curl_free.3 new file mode 100644 index 0000000..b45205c --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_free.3 @@ -0,0 +1,37 @@ +.\" generated by cd2nroff 0.1 from curl_free.md +.TH curl_free 3 "2024-10-11" libcurl +.SH NAME +curl_free \- reclaim memory that has been obtained through a libcurl call +.SH SYNOPSIS +.nf +#include + +void curl_free(void *ptr); +.fi +.SH DESCRIPTION +curl_free reclaims memory that has been obtained through a libcurl call. Use +\fIcurl_free(3)\fP instead of free() to avoid anomalies that can result from +differences in memory management between your application and libcurl. + +Passing in a NULL pointer in \fIptr\fP makes this function return immediately +with no action. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + char *width = curl_getenv("COLUMNS"); + if(width) { + /* it was set! */ + curl_free(width); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +None +.SH SEE ALSO +.BR curl_easy_escape (3), +.BR curl_easy_unescape (3) diff --git a/3rdparty/curl/share/man/man3/curl_getdate.3 b/3rdparty/curl/share/man/man3/curl_getdate.3 new file mode 100644 index 0000000..b8c6b79 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_getdate.3 @@ -0,0 +1,102 @@ +.\" generated by cd2nroff 0.1 from curl_getdate.md +.TH curl_getdate 3 "2024-10-11" libcurl +.SH NAME +curl_getdate \- convert date string to number of seconds +.SH SYNOPSIS +.nf +#include + +time_t curl_getdate(const char *datestring, const time_t *now); +.fi +.SH DESCRIPTION +\fIcurl_getdate(3)\fP returns the number of seconds since the Epoch, January +1st 1970 00:00:00 in the UTC time zone, for the date and time that the +\fIdatestring\fP parameter specifies. The \fInow\fP parameter is not used, +pass a NULL there. + +This function works with valid dates and does not always detect and reject +wrong dates, such as February 30. +.SH PARSING DATES AND TIMES +A "date" is a string containing several items separated by whitespace. The +order of the items is immaterial. A date string may contain many flavors of +items: +.IP "calendar date items" +Can be specified several ways. Month names can only be three\-letter English +abbreviations, numbers can be zero\-prefixed and the year may use 2 or 4 +digits. Examples: 06 Nov 1994, 06\-Nov\-94 and Nov\-94 6. + +If the year appears to be below 100 (two\-digit), any year after 70 is assumed +to be 1900 + the given year. All others are 2000 + the given year. +.IP "time of the day items" +This string specifies the time on a given day. You must specify it with 6 +digits with two colons: HH:MM:SS. If there is no time given in a provided date +string, 00:00:00 is assumed. Example: 18:19:21. +.IP "time zone items" +Specifies international time zone. There are a few acronyms supported, but in +general you should instead use the specific relative time compared to +UTC. Supported formats include: \-1200, MST, +0100. +.IP "day of the week items" +Specifies a day of the week. Days of the week may be spelled out in full +(using English): \(aqSunday\(aq, \(aqMonday\(aq, etc or they may be abbreviated to their +first three letters. This is usually not info that adds anything. +.IP "pure numbers" +If a decimal number of the form YYYYMMDD appears, then YYYY is read as the +year, MM as the month number and DD as the day of the month, for the specified +calendar date. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + time_t t; + t = curl_getdate("Sun, 06 Nov 1994 08:49:37 GMT", NULL); + t = curl_getdate("Sunday, 06-Nov-94 08:49:37 GMT", NULL); + t = curl_getdate("Sun Nov 6 08:49:37 1994", NULL); + t = curl_getdate("06 Nov 1994 08:49:37 GMT", NULL); + t = curl_getdate("06-Nov-94 08:49:37 GMT", NULL); + t = curl_getdate("Nov 6 08:49:37 1994", NULL); + t = curl_getdate("06 Nov 1994 08:49:37", NULL); + t = curl_getdate("06-Nov-94 08:49:37", NULL); + t = curl_getdate("1994 Nov 6 08:49:37", NULL); + t = curl_getdate("GMT 08:49:37 06-Nov-94 Sunday", NULL); + t = curl_getdate("94 6 Nov 08:49:37", NULL); + t = curl_getdate("1994 Nov 6", NULL); + t = curl_getdate("06-Nov-94", NULL); + t = curl_getdate("Sun Nov 6 94", NULL); + t = curl_getdate("1994.Nov.6", NULL); + t = curl_getdate("Sun/Nov/6/94/GMT", NULL); + t = curl_getdate("Sun, 06 Nov 1994 08:49:37 CET", NULL); + t = curl_getdate("06 Nov 1994 08:49:37 EST", NULL); + t = curl_getdate("Sun, 12 Sep 2004 15:05:58 -0700", NULL); + t = curl_getdate("Sat, 11 Sep 2004 21:32:11 +0200", NULL); + t = curl_getdate("20040912 15:05:58 -0700", NULL); + t = curl_getdate("20040911 +0200", NULL); +} +.fi +.SH STANDARDS +This parser handles date formats specified in RFC 822 (including the update in +RFC 1123) using time zone name or time zone delta and RFC 850 (obsoleted by +RFC 1036) and ANSI C\(aqs \fIasctime()\fP format. + +These formats are the only ones RFC 7231 says HTTP applications may use. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +This function returns \-1 when it fails to parse the date string. Otherwise it +returns the number of seconds as described. + +On systems with a signed 32\-bit time_t: if the year is larger than 2037 or +less than 1903, this function returns \-1. + +On systems with an unsigned 32\-bit time_t: if the year is larger than 2106 or +less than 1970, this function returns \-1. + +On systems with 64\-bit time_t: if the year is less than 1583, this function +returns \-1. (The Gregorian calendar was first introduced 1582 so no "real" +dates in this way of doing dates existed before then.) +.SH SEE ALSO +.BR CURLOPT_TIMECONDITION (3), +.BR CURLOPT_TIMEVALUE (3), +.BR curl_easy_escape (3), +.BR curl_easy_unescape (3) diff --git a/3rdparty/curl/share/man/man3/curl_getenv.3 b/3rdparty/curl/share/man/man3/curl_getenv.3 new file mode 100644 index 0000000..93b1a7a --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_getenv.3 @@ -0,0 +1,40 @@ +.\" generated by cd2nroff 0.1 from curl_getenv.md +.TH curl_getenv 3 "2024-10-11" libcurl +.SH NAME +curl_getenv \- return value for environment name +.SH SYNOPSIS +.nf +#include + +char *curl_getenv(const char *name); +.fi +.SH DESCRIPTION +curl_getenv() is a portable wrapper for the getenv() function, meant to +emulate its behavior and provide an identical interface for all operating +systems libcurl builds on (including Windows). + +You must \fIcurl_free(3)\fP the returned string when you are done with it. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + char *width = curl_getenv("COLUMNS"); + if(width) { + /* it was set! */ + curl_free(width); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +A pointer to a null\-terminated string or NULL if it failed to find the +specified name. +.SH NOTE +Under Unix operating systems, there is no point in returning an allocated +memory, although other systems does not work properly if this is not done. The +Unix implementation thus suffers slightly from the drawbacks of other systems. +.SH SEE ALSO +.BR getenv (3C) diff --git a/3rdparty/curl/share/man/man3/curl_global_cleanup.3 b/3rdparty/curl/share/man/man3/curl_global_cleanup.3 new file mode 100644 index 0000000..23cb6b1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_global_cleanup.3 @@ -0,0 +1,62 @@ +.\" generated by cd2nroff 0.1 from curl_global_cleanup.md +.TH curl_global_cleanup 3 "2024-10-11" libcurl +.SH NAME +curl_global_cleanup \- global libcurl cleanup +.SH SYNOPSIS +.nf +#include + +void curl_global_cleanup(void); +.fi +.SH DESCRIPTION +This function releases resources acquired by \fIcurl_global_init(3)\fP. + +You should call \fIcurl_global_cleanup(3)\fP once for each call you make to +\fIcurl_global_init(3)\fP, after you are done using libcurl. + +This function is thread\-safe since libcurl 7.84.0 if +\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set +(most platforms). + +If this is not thread\-safe, you must not call this function when any other +thread in the program (i.e. a thread sharing the same memory) is running. +This does not just mean no other thread that is using libcurl. Because +\fIcurl_global_cleanup(3)\fP calls functions of other libraries that are +similarly thread unsafe, it could conflict with any other thread that uses +these other libraries. + +See the description in \fIlibcurl(3)\fP of global environment requirements for +details of how to use this function. +.SH CAUTION +\fIcurl_global_cleanup(3)\fP does not block waiting for any libcurl\-created +threads to terminate (such as threads used for name resolving). If a module +containing libcurl is dynamically unloaded while libcurl\-created threads are +still running then your program may crash or other corruption may occur. We +recommend you do not run libcurl from any module that may be unloaded +dynamically. This behavior may be addressed in the future. + +libcurl may not be able to fully clean up after multi\-threaded OpenSSL +depending on how OpenSSL was built and loaded as a library. It is possible in +some rare circumstances a memory leak could occur unless you implement your own +OpenSSL thread cleanup. Refer to \fIlibcurl\-thread(3)\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + curl_global_init(CURL_GLOBAL_DEFAULT); + + /* use libcurl, then before exiting... */ + + curl_global_cleanup(); +} +.fi +.SH AVAILABILITY +Added in curl 7.8 +.SH RETURN VALUE +None +.SH SEE ALSO +.BR curl_global_init (3), +.BR libcurl (3), +.BR libcurl-thread (3) diff --git a/3rdparty/curl/share/man/man3/curl_global_init.3 b/3rdparty/curl/share/man/man3/curl_global_init.3 new file mode 100644 index 0000000..a27ff4f --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_global_init.3 @@ -0,0 +1,102 @@ +.\" generated by cd2nroff 0.1 from curl_global_init.md +.TH curl_global_init 3 "2024-10-11" libcurl +.SH NAME +curl_global_init \- global libcurl initialization +.SH SYNOPSIS +.nf +#include + +CURLcode curl_global_init(long flags); +.fi +.SH DESCRIPTION +This function sets up the program environment that libcurl needs. Think of it +as an extension of the library loader. + +This function must be called at least once within a program (a program is all +the code that shares a memory space) before the program calls any other +function in libcurl. The environment it sets up is constant for the life of +the program and is the same for every program, so multiple calls have the same +effect as one call. + +The flags option is a bit pattern that tells libcurl exactly what features to +init, as described below. Set the desired bits by ORing the values together. +In normal operation, you must specify CURL_GLOBAL_ALL. Do not use any other +value unless you are familiar with it and mean to control internal operations +of libcurl. + +This function is thread\-safe on most platforms. Then \fIcurl_version_info(3)\fP has +the \fIthreadsafe\fP feature set (added in 7.84.0). + +If this is not thread\-safe (the bit mentioned above is not set), you must not +call this function when any other thread in the program (i.e. a thread sharing +the same memory) is running. This does not just mean no other thread that is +using libcurl. Because \fIcurl_global_init(3)\fP calls functions of other libraries +that are similarly thread unsafe, it could conflict with any other thread that +uses these other libraries. + +If you are initializing libcurl from a Windows DLL you should not initialize +it from \fIDllMain\fP or a static initializer because Windows holds the loader +lock during that time and it could cause a deadlock. + +See the description in \fIlibcurl(3)\fP of global environment requirements for +details of how to use this function. +.SH FLAGS +.IP CURL_GLOBAL_ALL +Initialize everything possible. This sets all known bits except +\fBCURL_GLOBAL_ACK_EINTR\fP. +.IP CURL_GLOBAL_SSL +(This flag\(aqs presence or absence serves no meaning since 7.57.0. The +description below is for older libcurl versions.) + +Initialize SSL. + +The implication here is that if this bit is not set, the initialization of the +SSL layer needs to be done by the application or at least outside of +libcurl. The exact procedure how to do SSL initialization depends on the TLS +backend libcurl uses. + +Doing TLS based transfers without having the TLS layer initialized may lead to +unexpected behaviors. +.IP CURL_GLOBAL_WIN32 +Initialize the Win32 socket libraries. + +The implication here is that if this bit is not set, the initialization of +Winsock has to be done by the application or you risk getting undefined +behaviors. This option exists for when the initialization is handled outside +of libcurl so there is no need for libcurl to do it again. +.IP CURL_GLOBAL_NOTHING +Initialize nothing extra. This sets no bit. +.IP CURL_GLOBAL_DEFAULT +A sensible default. It initializes both SSL and Win32. Right now, this equals +the functionality of the \fBCURL_GLOBAL_ALL\fP mask. +.IP CURL_GLOBAL_ACK_EINTR +This bit has no point since 7.69.0 but its behavior is instead the default. + +Before 7.69.0: when this flag is set, curl acknowledges EINTR condition when +connecting or when waiting for data. Otherwise, curl waits until full timeout +elapses. (Added in 7.30.0) +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + curl_global_init(CURL_GLOBAL_DEFAULT); + + /* use libcurl, then before exiting... */ + + curl_global_cleanup(); +} +.fi +.SH AVAILABILITY +Added in curl 7.8 +.SH RETURN VALUE +If this function returns non\-zero, something went wrong and you cannot use the +other curl functions. +.SH SEE ALSO +.BR curl_easy_init (3), +.BR curl_global_cleanup (3), +.BR curl_global_init_mem (3), +.BR curl_global_sslset (3), +.BR curl_global_trace (3), +.BR libcurl (3) diff --git a/3rdparty/curl/share/man/man3/curl_global_init_mem.3 b/3rdparty/curl/share/man/man3/curl_global_init_mem.3 new file mode 100644 index 0000000..b9620a1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_global_init_mem.3 @@ -0,0 +1,68 @@ +.\" generated by cd2nroff 0.1 from curl_global_init_mem.md +.TH curl_global_init_mem 3 "2024-10-11" libcurl +.SH NAME +curl_global_init_mem \- global libcurl initialization with memory callbacks +.SH SYNOPSIS +.nf +#include + +CURLcode curl_global_init_mem(long flags, + curl_malloc_callback m, + curl_free_callback f, + curl_realloc_callback r, + curl_strdup_callback s, + curl_calloc_callback c); +.fi +.SH DESCRIPTION +This function works exactly as \fIcurl_global_init(3)\fP with one addition: it +allows the application to set callbacks to replace the otherwise used internal +memory functions. + +If you are using libcurl from multiple threads or libcurl was built with the +threaded resolver option then the callback functions must be thread safe. The +threaded resolver is a common build option to enable (and in some cases the +default) so we strongly urge you to make your callback functions thread safe. + +All callback arguments must be set to valid function pointers. The +prototypes for the given callbacks must match these: +.IP "void *malloc_callback(size_t size);" +To replace malloc() +.IP "void free_callback(void *ptr);" +To replace free() +.IP "void *realloc_callback(void *ptr, size_t size);" +To replace realloc() +.IP "char *strdup_callback(const char *str);" +To replace strdup() +.IP "void *calloc_callback(size_t nmemb, size_t size);" +To replace calloc() + +This function is otherwise the same as \fIcurl_global_init(3)\fP, please refer +to that man page for documentation. +.SH CAUTION +Manipulating these gives considerable powers to the application to severely +screw things up for libcurl. Take care! +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +extern void *malloc_cb(size_t); +extern void free_cb(void *); +extern void *realloc_cb(void *, size_t); +extern char *strdup_cb(const char *); +extern void *calloc_cb(size_t, size_t); + +int main(void) +{ + curl_global_init_mem(CURL_GLOBAL_DEFAULT, malloc_cb, + free_cb, realloc_cb, + strdup_cb, calloc_cb); +} +.fi +.SH AVAILABILITY +Added in curl 7.12.0 +.SH RETURN VALUE +CURLE_OK (0) means everything was OK, non\-zero means an error occurred as +\fI\fP defines \- see \fIlibcurl\-errors(3)\fP. +.SH SEE ALSO +.BR curl_global_cleanup (3), +.BR curl_global_init (3) diff --git a/3rdparty/curl/share/man/man3/curl_global_sslset.3 b/3rdparty/curl/share/man/man3/curl_global_sslset.3 new file mode 100644 index 0000000..8a5cc62 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_global_sslset.3 @@ -0,0 +1,118 @@ +.\" generated by cd2nroff 0.1 from curl_global_sslset.md +.TH curl_global_sslset 3 "2024-10-11" libcurl +.SH NAME +curl_global_sslset \- select SSL backend to use +.SH SYNOPSIS +.nf +#include + +CURLsslset curl_global_sslset(curl_sslbackend id, + const char *name, + const curl_ssl_backend ***avail); +.fi +.SH DESCRIPTION +This function configures at runtime which SSL backend to use with +libcurl. This function can only be used to select an SSL backend once, and it +must be called \fBbefore\fP \fIcurl_global_init(3)\fP. + +The backend can be identified by the \fIid\fP +(e.g. \fBCURLSSLBACKEND_OPENSSL\fP). The backend can also be specified via the +\fIname\fP parameter for a case insensitive match (passing +\fBCURLSSLBACKEND_NONE\fP as \fIid\fP). If both \fIid\fP and \fIname\fP are +specified, the \fIname\fP is ignored. + +If neither \fIid\fP nor \fIname\fP are specified, the function fails with +\fBCURLSSLSET_UNKNOWN_BACKEND\fP and set the \fIavail\fP pointer to the +NULL\-terminated list of available backends. The available backends are those +that this particular build of libcurl supports. + +Since libcurl 7.60.0, the \fIavail\fP pointer is always set to the list of +alternatives if non\-NULL. + +Upon success, the function returns \fBCURLSSLSET_OK\fP. + +If the specified SSL backend is not available, the function returns +\fBCURLSSLSET_UNKNOWN_BACKEND\fP and sets the \fIavail\fP pointer to a +NULL\-terminated list of available SSL backends. In this case, you may call the +function again to try to select a different backend. + +The SSL backend can be set only once. If it has already been set, a subsequent +attempt to change it results in a \fBCURLSSLSET_TOO_LATE\fP getting returned. + +This function is thread\-safe since libcurl 7.84.0 if +\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set +(most platforms). + +If this is not thread\-safe, you must not call this function when any other +thread in the program (i.e. a thread sharing the same memory) is running. +This does not just mean no other thread that is using libcurl. +.SH OpenSSL +The name "OpenSSL" is used for all versions of OpenSSL and its associated +forks/flavors in this function. OpenSSL, BoringSSL, LibreSSL, quictls and +AmiSSL are all supported by libcurl, but in the eyes of +\fIcurl_global_sslset(3)\fP they are all just "OpenSSL". They all mostly +provide the same API. + +\fIcurl_version_info(3)\fP can return more specific info about the exact +OpenSSL flavor and version number is use. +.SH struct +.nf +typedef struct { + curl_sslbackend id; + const char *name; +} curl_ssl_backend; + +typedef enum { + CURLSSLBACKEND_NONE = 0, + CURLSSLBACKEND_OPENSSL = 1, /* or one of its forks */ + CURLSSLBACKEND_GNUTLS = 2, + CURLSSLBACKEND_NSS = 3, + CURLSSLBACKEND_GSKIT = 5, /* deprecated */ + CURLSSLBACKEND_POLARSSL = 6, /* deprecated */ + CURLSSLBACKEND_WOLFSSL = 7, + CURLSSLBACKEND_SCHANNEL = 8, + CURLSSLBACKEND_SECURETRANSPORT = 9, + CURLSSLBACKEND_AXTLS = 10, /* deprecated */ + CURLSSLBACKEND_MBEDTLS = 11, + CURLSSLBACKEND_MESALINK = 12, /* deprecated */ + CURLSSLBACKEND_BEARSSL = 13, + CURLSSLBACKEND_RUSTLS = 14 +} curl_sslbackend; +.fi +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + int i; + /* choose a specific backend */ + curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL); + + /* list the available ones */ + const curl_ssl_backend **list; + curl_global_sslset(CURLSSLBACKEND_NONE, NULL, &list); + + for(i = 0; list[i]; i++) + printf("SSL backend #%d: '%s' (ID: %d)\\n", + i, list[i]->name, list[i]->id); +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +If this function returns \fICURLSSLSET_OK\fP, the backend was successfully +selected. + +If the chosen backend is unknown (or support for the chosen backend has not +been compiled into libcurl), the function returns +\fICURLSSLSET_UNKNOWN_BACKEND\fP. + +If the backend had been configured previously, or if \fIcurl_global_init(3)\fP +has already been called, the function returns \fICURLSSLSET_TOO_LATE\fP. + +If this libcurl was built completely without SSL support, with no backends at +all, this function returns \fICURLSSLSET_NO_BACKENDS\fP. +.SH SEE ALSO +.BR curl_global_init (3), +.BR libcurl (3) diff --git a/3rdparty/curl/share/man/man3/curl_global_trace.3 b/3rdparty/curl/share/man/man3/curl_global_trace.3 new file mode 100644 index 0000000..9c1ac2e --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_global_trace.3 @@ -0,0 +1,121 @@ +.\" generated by cd2nroff 0.1 from curl_global_trace.md +.TH curl_global_trace 3 "2024-10-11" libcurl +.SH NAME +curl_global_trace \- log configuration +.SH SYNOPSIS +.nf +#include + +CURLcode curl_global_trace(const char *config); +.fi +.SH DESCRIPTION +This function configures the logging behavior to make some parts of curl more +verbose or silent than others. + +This function may be called during the initialization phase of a program. It +does not have to be. It can be called several times even, possibly overwriting +settings of previous calls. + +Calling this function after transfers have been started is undefined. On some +platforms/architectures it might take effect, on others not. + +This function is thread\-safe since libcurl 8.3.0 if \fIcurl_version_info(3)\fP has +the CURL_VERSION_THREADSAFE feature bit set (most platforms). + +If this is not thread\-safe, you must not call this function when any other +thread in the program (i.e. a thread sharing the same memory) is running. This +does not just mean no other thread that is using libcurl. Because +\fIcurl_global_init(3)\fP may call functions of other libraries that are similarly +thread unsafe, it could conflict with any other thread that uses these other +libraries. + +If you are initializing libcurl from a Windows DLL you should not initialize +it from \fIDllMain\fP or a static initializer because Windows holds the loader +lock during that time and it could cause a deadlock. + +The \fIconfig\fP string is a list of comma\-separated component names. Names are +case\-insensitive and unknown names are ignored. The special name "all" applies +to all components. Names may be prefixed with \(aq+\(aq or \(aq\-\(aq to enable or disable +detailed logging for a component. + +The list of component names is not part of curl\(aqs public API. Names may be +added or disappear in future versions of libcurl. Since unknown names are +silently ignored, outdated log configurations does not cause errors when +upgrading libcurl. Given that, some names can be expected to be fairly stable +and are listed below for easy reference. + +Note that log configuration applies only to transfers where debug logging is +enabled. See \fICURLOPT_VERBOSE(3)\fP or \fICURLOPT_DEBUGFUNCTION(3)\fP on how to control +that. +.SH TRACE COMPONENTS +.IP tcp +Tracing of TCP socket handling: connect, sends, receives. +.IP ssl +Tracing of SSL/TLS operations, whichever SSL backend is used in your build. +.IP ftp +Tracing of FTP operations when this protocol is enabled in your build. +.IP http/2 +Details about HTTP/2 handling: frames, events, I/O, etc. +.IP http/3 +Details about HTTP/3 handling: connect, frames, events, I/O etc. +.IP http-proxy +Involved when transfers are tunneled through an HTTP proxy. "h1\-proxy" or +\&"h2\-proxy" are also involved, depending on the HTTP version negotiated with +the proxy. + +In order to find out all components involved in a transfer, run it with "all" +configured. You can then see all names involved in your libcurl version in the +trace. +.IP doh +Tracing of DNS\-over\-HTTP operations to resolve hostnames. +.IP read +Traces reading of upload data from the application in order to send it to the server. +.IP smtp +Tracing of SMTP operations when this protocol is enabled in your build. +.IP write +Traces writing of download data, received from the server, to the application. +.IP ws +Tracing of WebSocket operations when this protocol is enabled in your build. +.SH TRACE GROUPS +Besides the specific component names there are the following group names +defined: +.IP all +.IP network +All components involved in bare network I/O, including the SSL layer. + +All components that your libcurl is built with. +.IP protocol +All components involved in transfer protocols, such as \(aqftp\(aq and \(aqhttp/2\(aq. +.IP proxy +All components involved in use of proxies. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + /* log details of HTTP/2 and SSL handling */ + curl_global_trace("http/2,ssl"); + + /* log all details, except SSL handling */ + curl_global_trace("all,-ssl"); +} +.fi + +Below is a trace sample where "http/2" was configured. The trace output +of an enabled component appears at the beginning in brackets. +.nf +* [HTTP/2] [h2sid=1] cf_send(len=96) submit https://example.com/ +\&... +* [HTTP/2] [h2sid=1] FRAME[HEADERS] +* [HTTP/2] [h2sid=1] 249 header bytes +\&... +.fi +.SH AVAILABILITY +Added in curl 8.3 +.SH RETURN VALUE +If this function returns non\-zero, something went wrong and the configuration +may not have any effects or may only been applied partially. +.SH SEE ALSO +.BR curl_global_init (3), +.BR libcurl (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_addpart.3 b/3rdparty/curl/share/man/man3/curl_mime_addpart.3 new file mode 100644 index 0000000..fd827c3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_addpart.3 @@ -0,0 +1,55 @@ +.\" generated by cd2nroff 0.1 from curl_mime_addpart.md +.TH curl_mime_addpart 3 "2024-10-11" libcurl +.SH NAME +curl_mime_addpart \- append a new empty part to a mime structure +.SH SYNOPSIS +.nf +#include + +curl_mimepart *curl_mime_addpart(curl_mime *mime); +.fi +.SH DESCRIPTION +\fIcurl_mime_addpart(3)\fP creates and appends a new empty part to the given +mime structure and returns a handle to it. The returned part handle can +subsequently be populated using functions from the mime API. + +\fImime\fP is the handle of the mime structure in which the new part must be +appended. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* continue and set name + data to the part */ + curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED); + curl_mime_name(part, "data"); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +A mime part structure handle, or NULL upon failure. +.SH SEE ALSO +.BR curl_mime_data (3), +.BR curl_mime_data_cb (3), +.BR curl_mime_encoder (3), +.BR curl_mime_filedata (3), +.BR curl_mime_filename (3), +.BR curl_mime_headers (3), +.BR curl_mime_init (3), +.BR curl_mime_name (3), +.BR curl_mime_subparts (3), +.BR curl_mime_type (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_data.3 b/3rdparty/curl/share/man/man3/curl_mime_data.3 new file mode 100644 index 0000000..70d33c3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_data.3 @@ -0,0 +1,61 @@ +.\" generated by cd2nroff 0.1 from curl_mime_data.md +.TH curl_mime_data 3 "2024-10-11" libcurl +.SH NAME +curl_mime_data \- set a mime part\(aqs body data from memory +.SH SYNOPSIS +.nf +#include + +CURLcode curl_mime_data(curl_mimepart *part, const char *data, + size_t datasize); +.fi +.SH DESCRIPTION +\fIcurl_mime_data(3)\fP sets a mime part\(aqs body content from memory data. + +\fIpart\fP is the mime part to assign contents to, created with +\fIcurl_mime_addpart(3)\fP. + +\fIdata\fP points to the data that gets copied by this function. The storage +may safely be reused after the call. + +\fIdatasize\fP is the number of bytes \fIdata\fP points to. It can be set to +\fICURL_ZERO_TERMINATED\fP to indicate \fIdata\fP is a null\-terminated +character string. + +Setting a part\(aqs contents multiple times is valid: only the value set by the +last call is retained. It is possible to unassign part\(aqs contents by setting +\fIdata\fP to NULL. + +Setting large data is memory consuming: one might consider using +\fIcurl_mime_data_cb(3)\fP in such a case. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* add data to the part */ + curl_mime_data(part, "raw contents to send", CURL_ZERO_TERMINATED); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. +.SH SEE ALSO +.BR curl_mime_addpart (3), +.BR curl_mime_data_cb (3), +.BR curl_mime_name (3), +.BR curl_mime_type (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_data_cb.3 b/3rdparty/curl/share/man/man3/curl_mime_data_cb.3 new file mode 100644 index 0000000..f4f077a --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_data_cb.3 @@ -0,0 +1,153 @@ +.\" generated by cd2nroff 0.1 from curl_mime_data_cb.md +.TH curl_mime_data_cb 3 "2024-10-11" libcurl +.SH NAME +curl_mime_data_cb \- set a callback\-based data source for a mime part\(aqs body +.SH SYNOPSIS +.nf +#include + +size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg); + +int seekfunc(void *arg, curl_off_t offset, int origin); + +void freefunc(void *arg); + +CURLcode curl_mime_data_cb(curl_mimepart *part, curl_off_t datasize, + curl_read_callback readfunc, + curl_seek_callback seekfunc, + curl_free_callback freefunc, void *arg); +.fi +.SH DESCRIPTION +\fIcurl_mime_data_cb(3)\fP sets the data source of a mime part\(aqs body content +from a data read callback function. + +\fIpart\fP is the part\(aqs to assign contents to. + +\fIreadfunc\fP is a pointer to a data read callback function, with a signature +as shown by the above prototype. It may not be set to NULL. + +\fIseekfunc\fP is a pointer to a seek callback function, with a signature as +shown by the above prototype. This function is used when resending data (i.e.: +after a redirect); this pointer may be set to NULL, in which case a resend +might not be not possible. + +\fIfreefunc\fP is a pointer to a user resource freeing callback function, with +a signature as shown by the above prototype. If no resource is to be freed, it +may safely be set to NULL. This function is called upon mime structure +freeing. + +\fIarg\fP is a user defined argument to callback functions. + +The read callback function gets called by libcurl as soon as it needs to +read data in order to send it to the peer \- like if you ask it to upload or +post data to the server. The data area pointed at by the pointer \fIbuffer\fP +should be filled up with at most \fIsize\fP multiplied with \fInitems\fP number +of bytes by your function. + +Your read function must then return the actual number of bytes that it stored +in that memory area. Returning 0 signals end\-of\-file to the library and cause +it to stop the current transfer. + +If you stop the current transfer by returning 0 "pre\-maturely" (i.e. before +the server expected it, like when you have said you intend to upload N bytes +and yet you upload less than N bytes), you may experience that the server +\&"hangs" waiting for the rest of the data that does not come. + +The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current +operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error +code from the transfer. + +The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this +connection to pause. See \fIcurl_easy_pause(3)\fP for further details. + +The seek function gets called by libcurl to rewind input stream data or to +seek to a certain position. The function shall work like fseek(3) or lseek(3) +and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP, +although libcurl currently only passes SEEK_SET. + +The callback function must return \fICURL_SEEKFUNC_OK\fP on success, +\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or +\fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl +is free to work around the problem if possible. The latter can sometimes be +done by instead reading from the input or similar. + +Care must be taken if the part is bound to a curl easy handle that is later +duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in +the pointed item to be shared between the original and the copied handle. In +particular, special attention should be given to the \fIfreefunc\fP procedure +code since it then gets called twice with the same argument. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +Sending a huge data string causes the same amount of memory to be allocated: +to avoid overhead resources consumption, one might want to use a callback +source to avoid data duplication. In this case, original data must be retained +until after the transfer terminates. +.nf +#include /* for memcpy */ +char hugedata[512000]; + +struct ctl { + char *buffer; + curl_off_t size; + curl_off_t position; +}; + +size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg) +{ + struct ctl *p = (struct ctl *) arg; + curl_off_t sz = p->size - p->position; + + nitems *= size; + if(sz > nitems) + sz = nitems; + if(sz) + memcpy(buffer, p->buffer + p->position, sz); + p->position += sz; + return sz; +} + +int seek_callback(void *arg, curl_off_t offset, int origin) +{ + struct ctl *p = (struct ctl *) arg; + + switch(origin) { + case SEEK_END: + offset += p->size; + break; + case SEEK_CUR: + offset += p->position; + break; + } + + if(offset < 0) + return CURL_SEEKFUNC_FAIL; + p->position = offset; + return CURL_SEEKFUNC_OK; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_mime *mime = curl_mime_init(curl); + curl_mimepart *part = curl_mime_addpart(mime); + struct ctl hugectl; + + hugectl.buffer = hugedata; + hugectl.size = sizeof(hugedata); + hugectl.position = 0; + curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL, + &hugectl); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. +.SH SEE ALSO +.BR curl_easy_duphandle (3), +.BR curl_mime_addpart (3), +.BR curl_mime_data (3), +.BR curl_mime_name (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_encoder.3 b/3rdparty/curl/share/man/man3/curl_mime_encoder.3 new file mode 100644 index 0000000..fecdcb7 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_encoder.3 @@ -0,0 +1,85 @@ +.\" generated by cd2nroff 0.1 from curl_mime_encoder.md +.TH curl_mime_encoder 3 "2024-10-11" libcurl +.SH NAME +curl_mime_encoder \- set a mime part\(aqs encoder and content transfer encoding +.SH SYNOPSIS +.nf +#include + +CURLcode curl_mime_encoder(curl_mimepart *part, const char *encoding); +.fi +.SH DESCRIPTION +curl_mime_encoder() requests a mime part\(aqs content to be encoded before being +transmitted. + +\fIpart\fP is the part\(aqs handle to assign an encoder. +\fIencoding\fP is a pointer to a null\-terminated encoding scheme. It may be +set to NULL to disable an encoder previously attached to the part. The encoding +scheme storage may safely be reused after this function returns. + +Setting a part\(aqs encoder multiple times is valid: only the value set by the +last call is retained. + +Upon multipart rendering, the part\(aqs content is encoded according to the +pertaining scheme and a corresponding \fI"Content\-Transfer\-Encoding"\fP header +is added to the part. + +Supported encoding schemes are: + +\&"\fIbinary\fP": the data is left unchanged, the header is added. + +\&"\fI8bit\fP": header added, no data change. + +\&"\fI7bit\fP": the data is unchanged, but is each byte is checked +to be a 7\-bit value; if not, a read error occurs. + +\&"\fIbase64\fP": Data is converted to base64 encoding, then split in +CRLF\-terminated lines of at most 76 characters. + +\&"\fIquoted\-printable\fP": data is encoded in quoted printable lines of +at most 76 characters. Since the resulting size of the final data cannot be +determined prior to reading the original data, it is left as unknown, causing +chunked transfer in HTTP. For the same reason, this encoder may not be used +with IMAP. This encoder targets text data that is mostly ASCII and should +not be used with other types of data. + +If the original data is already encoded in such a scheme, a custom +\fIContent\-Transfer\-Encoding\fP header should be added with +\fIcurl_mime_headers(3)\fP instead of setting a part encoder. + +Encoding should not be applied to multiparts, thus the use of this function on +a part with content set with \fIcurl_mime_subparts(3)\fP is strongly +discouraged. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* send a file */ + curl_mime_filedata(part, "image.png"); + + /* encode file data in base64 for transfer */ + curl_mime_encoder(part, "base64"); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. +.SH SEE ALSO +.BR curl_mime_addpart (3), +.BR curl_mime_headers (3), +.BR curl_mime_subparts (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_filedata.3 b/3rdparty/curl/share/man/man3/curl_mime_filedata.3 new file mode 100644 index 0000000..2929679 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_filedata.3 @@ -0,0 +1,73 @@ +.\" generated by cd2nroff 0.1 from curl_mime_filedata.md +.TH curl_mime_filedata 3 "2024-10-11" libcurl +.SH NAME +curl_mime_filedata \- set a mime part\(aqs body data from a file contents +.SH SYNOPSIS +.nf +#include + +CURLcode curl_mime_filedata(curl_mimepart *part, + const char *filename); +.fi +.SH DESCRIPTION +\fIcurl_mime_filedata(3)\fP sets a mime part\(aqs body content from the named +file\(aqs contents. This is an alternative to \fIcurl_mime_data(3)\fP for setting +data to a mime part. + +\fIpart\fP is the part\(aqs to assign contents to. + +\fIfilename\fP points to the null\-terminated file\(aqs path name. The pointer can +be NULL to detach the previous part contents settings. Filename storage can +be safely be reused after this call. + +As a side effect, the part\(aqs remote filename is set to the base name of the +given \fIfilename\fP if it is a valid named file. This can be undone or +overridden by a subsequent call to \fIcurl_mime_filename(3)\fP. + +The contents of the file is read during the file transfer in a streaming +manner to allow huge files to get transferred without using much memory. It +therefore requires that the file is kept intact during the entire request. + +If the file size cannot be determined before actually reading it (such as for +a character device or named pipe), the whole mime structure containing the +part is transferred using chunks by HTTP but is rejected by IMAP. + +Setting a part\(aqs contents multiple times is valid: only the value set by the +last call is retained. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* send data from this file */ + curl_mime_filedata(part, "image.png"); + + /* set name */ + curl_mime_name(part, "data"); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. CURLE_READ_ERROR is only an +indication that the file is not yet readable: it can be safely ignored at +this time, but the file must be made readable before the pertaining +easy handle is performed. +.SH SEE ALSO +.BR curl_mime_addpart (3), +.BR curl_mime_data (3), +.BR curl_mime_filename (3), +.BR curl_mime_name (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_filename.3 b/3rdparty/curl/share/man/man3/curl_mime_filename.3 new file mode 100644 index 0000000..353e712 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_filename.3 @@ -0,0 +1,64 @@ +.\" generated by cd2nroff 0.1 from curl_mime_filename.md +.TH curl_mime_filename 3 "2024-10-11" libcurl +.SH NAME +curl_mime_filename \- set a mime part\(aqs remote filename +.SH SYNOPSIS +.nf +#include + +CURLcode curl_mime_filename(curl_mimepart *part, + const char *filename); +.fi +.SH DESCRIPTION +\fIcurl_mime_filename(3)\fP sets a mime part\(aqs remote filename. When remote +filename is set, content data is processed as a file, whatever is the part\(aqs +content source. A part\(aqs remote filename is transmitted to the server in the +associated Content\-Disposition generated header. + +\fIpart\fP is the part\(aqs handle to assign the remote filename to. + +\fIfilename\fP points to the null\-terminated filename string; it may be set +to NULL to remove a previously attached remote filename. + +The remote filename string is copied into the part, thus the associated +storage may safely be released or reused after call. Setting a part\(aqs file +name multiple times is valid: only the value set by the last call is retained. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf + +static char imagebuf[]="imagedata"; + +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* send image data from memory */ + curl_mime_data(part, imagebuf, sizeof(imagebuf)); + + /* set a file name to make it look like a file upload */ + curl_mime_filename(part, "image.png"); + + /* set name */ + curl_mime_name(part, "data"); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. +.SH SEE ALSO +.BR curl_mime_addpart (3), +.BR curl_mime_data (3), +.BR curl_mime_filedata (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_free.3 b/3rdparty/curl/share/man/man3/curl_mime_free.3 new file mode 100644 index 0000000..4623d14 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_free.3 @@ -0,0 +1,50 @@ +.\" generated by cd2nroff 0.1 from curl_mime_free.md +.TH curl_mime_free 3 "2024-10-11" libcurl +.SH NAME +curl_mime_free \- free a previously built mime structure +.SH SYNOPSIS +.nf +#include + +void curl_mime_free(curl_mime *mime); +.fi +.SH DESCRIPTION +\fIcurl_mime_free(3)\fP is used to clean up data previously built/appended +with \fIcurl_mime_addpart(3)\fP and other mime\-handling functions. This must +be called when the data has been used, which typically means after +\fIcurl_easy_perform(3)\fP has been called. + +The handle to free is the one you passed to the \fICURLOPT_MIMEPOST(3)\fP +option: attached sub part mime structures must not be explicitly freed as they +are by the top structure freeing. + +\fBmime\fP is the handle as returned from a previous call to +\fIcurl_mime_init(3)\fP and may be NULL. + +Passing in a NULL pointer in \fImime\fP makes this function return immediately +with no action. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* Build the mime message. */ + curl_mime *mime = curl_mime_init(curl); + + /* send off the transfer */ + + /* Free multipart message. */ + curl_mime_free(mime); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +None +.SH SEE ALSO +.BR curl_free (3), +.BR curl_mime_init (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_headers.3 b/3rdparty/curl/share/man/man3/curl_mime_headers.3 new file mode 100644 index 0000000..54eec90 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_headers.3 @@ -0,0 +1,63 @@ +.\" generated by cd2nroff 0.1 from curl_mime_headers.md +.TH curl_mime_headers 3 "2024-10-11" libcurl +.SH NAME +curl_mime_headers \- set a mime part\(aqs custom headers +.SH SYNOPSIS +.nf +#include + +CURLcode curl_mime_headers(curl_mimepart *part, + struct curl_slist *headers, int take_ownership); +.fi +.SH DESCRIPTION +\fIcurl_mime_headers(3)\fP sets a mime part\(aqs custom headers. + +\fIpart\fP is the part\(aqs handle to assign the custom headers list to. + +\fIheaders\fP is the head of a list of custom headers; it may be set to NULL +to remove a previously attached custom header list. + +\fItake_ownership\fP: when non\-zero, causes the list to be freed upon +replacement or mime structure deletion; in this case the list must not be +freed explicitly. + +Setting a part\(aqs custom headers list multiple times is valid: only the value +set by the last call is retained. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + struct curl_slist *headers = NULL; + CURL *easy = curl_easy_init(); + curl_mime *mime; + curl_mimepart *part; + + headers = curl_slist_append(headers, "Custom-Header: mooo"); + + mime = curl_mime_init(easy); + part = curl_mime_addpart(mime); + + /* use these headers in the part, takes ownership */ + curl_mime_headers(part, headers, 1); + + /* pass on this data */ + curl_mime_data(part, "12345679", CURL_ZERO_TERMINATED); + + /* set name */ + curl_mime_name(part, "numbers"); + + /* Post and send it. */ + curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime); + curl_easy_setopt(easy, CURLOPT_URL, "https://example.com"); + curl_easy_perform(easy); +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. +.SH SEE ALSO +.BR curl_mime_addpart (3), +.BR curl_mime_name (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_init.3 b/3rdparty/curl/share/man/man3/curl_mime_init.3 new file mode 100644 index 0000000..34e956f --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_init.3 @@ -0,0 +1,57 @@ +.\" generated by cd2nroff 0.1 from curl_mime_init.md +.TH curl_mime_init 3 "2024-10-11" libcurl +.SH NAME +curl_mime_init \- create a mime handle +.SH SYNOPSIS +.nf +#include + +curl_mime *curl_mime_init(CURL *easy_handle); +.fi +.SH DESCRIPTION +\fIcurl_mime_init(3)\fP creates a handle to a new empty mime structure. +This mime structure can be subsequently filled using the mime API, then +attached to some easy handle using option \fICURLOPT_MIMEPOST(3)\fP within +a \fIcurl_easy_setopt(3)\fP call or added as a multipart in another mime +handle\(aqs part using \fIcurl_mime_subparts(3)\fP. + +\fIeasy_handle\fP is used for part separator randomization and error +reporting. Since 7.87.0, it does not need to be the final target handle. + +Using a mime handle is the recommended way to post an HTTP form, format and +send a multi\-part email with SMTP or upload such an email to an IMAP server. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + CURL *easy = curl_easy_init(); + curl_mime *mime; + curl_mimepart *part; + + /* Build an HTTP form with a single field named "data", */ + mime = curl_mime_init(easy); + part = curl_mime_addpart(mime); + curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED); + curl_mime_name(part, "data"); + + /* Post and send it. */ + curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime); + curl_easy_setopt(easy, CURLOPT_URL, "https://example.com"); + curl_easy_perform(easy); + + /* Clean-up. */ + curl_easy_cleanup(easy); + curl_mime_free(mime); +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +A mime struct handle, or NULL upon failure. +.SH SEE ALSO +.BR CURLOPT_MIMEPOST (3), +.BR curl_mime_addpart (3), +.BR curl_mime_free (3), +.BR curl_mime_subparts (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_name.3 b/3rdparty/curl/share/man/man3/curl_mime_name.3 new file mode 100644 index 0000000..55f0d6c --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_name.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from curl_mime_name.md +.TH curl_mime_name 3 "2024-10-11" libcurl +.SH NAME +curl_mime_name \- set a mime part\(aqs name +.SH SYNOPSIS +.nf +#include + +CURLcode curl_mime_name(curl_mimepart *part, const char *name); +.fi +.SH DESCRIPTION +\fIcurl_mime_name(3)\fP sets a mime part\(aqs name. This is the way HTTP form +fields are named. + +\fIpart\fP is the part\(aqs handle to assign a name to. + +\fIname\fP points to the null\-terminated name string. + +The name string is copied into the part, thus the associated storage may +safely be released or reused after call. Setting a part\(aqs name multiple times +is valid: only the value set by the last call is retained. It is possible to +reset the name of a part by setting \fIname\fP to NULL. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* give the part a name */ + curl_mime_name(part, "shoe_size"); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. +.SH SEE ALSO +.BR curl_mime_addpart (3), +.BR curl_mime_data (3), +.BR curl_mime_type (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_subparts.3 b/3rdparty/curl/share/man/man3/curl_mime_subparts.3 new file mode 100644 index 0000000..fafe643 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_subparts.3 @@ -0,0 +1,68 @@ +.\" generated by cd2nroff 0.1 from curl_mime_subparts.md +.TH curl_mime_subparts 3 "2024-10-11" libcurl +.SH NAME +curl_mime_subparts \- set sub\-parts of a multipart mime part +.SH SYNOPSIS +.nf +#include + +CURLcode curl_mime_subparts(curl_mimepart *part, curl_mime *subparts); +.fi +.SH DESCRIPTION +\fIcurl_mime_subparts(3)\fP sets a multipart mime part\(aqs content from a mime +structure. + +\fIpart\fP is a handle to the multipart part. + +\fIsubparts\fP is a mime structure handle holding the sub\-parts. After +\fIcurl_mime_subparts(3)\fP succeeds, the mime structure handle belongs to the +multipart part and must not be freed explicitly. It may however be updated by +subsequent calls to mime API functions. + +Setting a part\(aqs contents multiple times is valid: only the value set by the +last call is retained. It is possible to unassign previous part\(aqs contents by +setting \fIsubparts\fP to NULL. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf + +static char *inline_html = "example"; +static char *inline_text = "once upon the time"; + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct curl_slist *slist; + + /* The inline part is an alternative proposing the html and the text + versions of the email. */ + curl_mime *alt = curl_mime_init(curl); + curl_mimepart *part; + + /* HTML message. */ + part = curl_mime_addpart(alt); + curl_mime_data(part, inline_html, CURL_ZERO_TERMINATED); + curl_mime_type(part, "text/html"); + + /* Text message. */ + part = curl_mime_addpart(alt); + curl_mime_data(part, inline_text, CURL_ZERO_TERMINATED); + + /* Create the inline part. */ + part = curl_mime_addpart(alt); + curl_mime_subparts(part, alt); + curl_mime_type(part, "multipart/alternative"); + slist = curl_slist_append(NULL, "Content-Disposition: inline"); + curl_mime_headers(part, slist, 1); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. +.SH SEE ALSO +.BR curl_mime_addpart (3), +.BR curl_mime_init (3) diff --git a/3rdparty/curl/share/man/man3/curl_mime_type.3 b/3rdparty/curl/share/man/man3/curl_mime_type.3 new file mode 100644 index 0000000..b456119 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mime_type.3 @@ -0,0 +1,71 @@ +.\" generated by cd2nroff 0.1 from curl_mime_type.md +.TH curl_mime_type 3 "2024-10-11" libcurl +.SH NAME +curl_mime_type \- set a mime part\(aqs content type +.SH SYNOPSIS +.nf +#include + +CURLcode curl_mime_type(curl_mimepart *part, const char *mimetype); +.fi +.SH DESCRIPTION +\fIcurl_mime_type(3)\fP sets a mime part\(aqs content type. + +\fIpart\fP is the part\(aqs handle to assign the content type to. + +\fImimetype\fP points to the null\-terminated file mime type string; it may be +set to NULL to remove a previously attached mime type. + +The mime type string is copied into the part, thus the associated storage may +safely be released or reused after call. Setting a part\(aqs type multiple times +is valid: only the value set by the last call is retained. + +In the absence of a mime type and if needed by the protocol specifications, +a default mime type is determined by the context: + +- If set as a custom header, use this value. + +- application/form\-data for an HTTP form post. + +- If a remote filename is set, the mime type is taken from the filename +extension, or application/octet\-stream by default. + +- For a multipart part, multipart/mixed. + +- text/plain in other cases. +.SH PROTOCOLS +This functionality affects http, imap and smtp +.SH EXAMPLE +.nf +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* get data from this file */ + curl_mime_filedata(part, "image.png"); + + /* content-type for this part */ + curl_mime_type(part, "image/png"); + + /* set name */ + curl_mime_name(part, "image"); +} +} +.fi +.SH AVAILABILITY +Added in curl 7.56.0 +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. +.SH SEE ALSO +.BR curl_mime_addpart (3), +.BR curl_mime_data (3), +.BR curl_mime_name (3) diff --git a/3rdparty/curl/share/man/man3/curl_mprintf.3 b/3rdparty/curl/share/man/man3/curl_mprintf.3 new file mode 100644 index 0000000..926800b --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_mprintf.3 @@ -0,0 +1,217 @@ +.\" generated by cd2nroff 0.1 from curl_mprintf.md +.TH curl_printf 3 "2024-10-11" libcurl +.SH NAME +curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf, +curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf, +curl_mvsprintf \- formatted output conversion +.SH SYNOPSIS +.nf +#include + +int curl_mprintf(const char *format, ...); +int curl_mfprintf(FILE *fd, const char *format, ...); +int curl_msprintf(char *buffer, const char *format, ...); +int curl_msnprintf(char *buffer, size_t maxlength, const char *format, ...); +int curl_mvprintf(const char *format, va_list args); +int curl_mvfprintf(FILE *fd, const char *format, va_list args); +int curl_mvsprintf(char *buffer, const char *format, va_list args); +int curl_mvsnprintf(char *buffer, size_t maxlength, const char *format, + va_list args); +char *curl_maprintf(const char *format , ...); +char *curl_mvaprintf(const char *format, va_list args); +.fi +.SH DESCRIPTION +These functions produce output according to the format string and given +arguments. They are mostly clones of the well\-known C\-style functions but +there are slight differences in behavior. + +We discourage users from using any of these functions in new applications. + +Functions in the curl_mprintf() family produce output according to a format as +described below. The functions \fBcurl_mprintf()\fP and \fBcurl_mvprintf()\fP +write output to stdout, the standard output stream; \fBcurl_mfprintf()\fP and +\fBcurl_mvfprintf()\fP write output to the given output stream; +\fBcurl_msprintf()\fP, \fBcurl_msnprintf()\fP, \fBcurl_mvsprintf()\fP, and +\fBcurl_mvsnprintf()\fP write to the character string \fBbuffer\fP. + +The functions \fBcurl_msnprintf()\fP and \fBcurl_mvsnprintf()\fP write at most +\fImaxlength\fP bytes (including the terminating null byte (\(aq0\(aq)) to +\fIbuffer\fP. + +The functions \fBcurl_mvprintf()\fP, \fBcurl_mvfprintf()\fP, +\fBcurl_mvsprintf()\fP, \fBcurl_mvsnprintf()\fP are equivalent to the +functions \fBcurl_mprintf()\fP, \fBcurl_mfprintf()\fP, \fBcurl_msprintf()\fP, +\fBcurl_msnprintf()\fP, respectively, except that they are called with a +\fIva_list\fP instead of a variable number of arguments. These functions do +not call the \fIva_end\fP macro. Because they invoke the \fIva_arg\fP macro, +the value of \fIap\fP is undefined after the call. + +The functions \fBcurl_maprintf()\fP and \fBcurl_mvaprintf()\fP return the +output string as pointer to a newly allocated memory area. The returned string +must be \fIcurl_free(3)\fPed by the receiver. + +All of these functions write the output under the control of a format string +that specifies how subsequent arguments are converted for output. +.SH FORMAT STRING +The format string is composed of zero or more directives: ordinary characters +(not %), which are copied unchanged to the output stream; and conversion +specifications, each of which results in fetching zero or more subsequent +arguments. Each conversion specification is introduced by the character %, and +ends with a conversion specifier. In between there may be (in this order) zero +or more \fIflags\fP, an optional minimum \fIfield width\fP, an optional +\fIprecision\fP and an optional \fIlength modifier\fP. +.SH The $ modifier +The arguments must correspond properly with the conversion specifier. By +default, the arguments are used in the order given, where each \(aq*\(aq (see Field +width and Precision below) and each conversion specifier asks for the next +argument (and it is an error if insufficiently many arguments are given). One +can also specify explicitly which argument is taken, at each place where an +argument is required, by writing "%m$" instead of \(aq%\(aq and "*m$" instead +of \(aq*\(aq, where the decimal integer m denotes the position in the argument list +of the desired argument, indexed starting from 1. Thus, +.nf + curl_mprintf("%*d", width, num); +.fi +and +.nf + curl_mprintf("%2$*1$d", width, num); +.fi +are equivalent. The second style allows repeated references to the same +argument. + +If the style using \(aq$\(aq is used, it must be used throughout for all conversions +taking an argument and all width and precision arguments, but it may be mixed +with "%%" formats, which do not consume an argument. There may be no gaps in +the numbers of arguments specified using \(aq$\(aq; for example, if arguments 1 and +3 are specified, argument 2 must also be specified somewhere in the format +string. +.SH Flag characters +The character % is followed by zero or more of the following flags: +.IP # +The value should be converted to its "alternate form". +.IP 0 +The value should be zero padded. +.IP - +The converted value is to be left adjusted on the field boundary. (The default +is right justification.) The converted value is padded on the right with +blanks, rather than on the left with blanks or zeros. A \(aq\-\(aq overrides a &\(aq0\(aq +if both are given. +.IP (space) +(a space: \(aq \(aq) A blank should be left before a positive number (or empty +string) produced by a signed conversion. +.IP + +A sign (+ or \-) should always be placed before a number produced by a signed +conversion. By default, a sign is used only for negative numbers. A \(aq+\(aq +overrides a space if both are used. +.SH Field width +An optional decimal digit string (with nonzero first digit) specifying a +minimum field width. If the converted value has fewer characters than the +field width, it gets padded with spaces on the left (or right, if the +left\-adjustment flag has been given). Instead of a decimal digit string one +may write "\fI" or "\fPm$" (for some decimal integer m) to specify that the field +width is given in the next argument, or in the \fIm\-th\fP argument, +respectively, which must be of type int. A negative field width is taken as +a \(aq\-\(aq flag followed by a positive field width. In no case does a nonexistent +or small field width cause truncation of a field; if the result of a +conversion is wider than the field width, the field is expanded to contain the +conversion result. +.SH Precision +An optional precision in the form of a period (\(aq.\(aq) followed by an optional +decimal digit string. Instead of a decimal digit string one may write "*" or +\&"*m$" (for some decimal integer m) to specify that the precision is given in +the next argument, or in the \fIm\-th\fP argument, respectively, which must be of +type int. If the precision is given as just \(aq.\(aq, the precision is taken to be +zero. A negative precision is taken as if the precision were omitted. This +gives the minimum number of digits to appear for \fBd\fP, \fBi\fP, \fBo\fP, +\fBu\fP, \fBx\fP, and \fBX\fP conversions, the number of digits to appear +after the radix character for \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, and +\fBF\fP conversions, the maximum number of significant digits for \fBg\fP and +\fBG\fP conversions, or the maximum number of characters to be printed from a +string for \fBs\fP and \fBS\fP conversions. +.SH Length modifier +.IP h +A following integer conversion corresponds to a \fIshort\fP or \fIunsigned short\fP +argument. +.IP l +(ell) A following integer conversion corresponds to a \fIlong\fP or +\fIunsigned long\fP argument, or a following n conversion corresponds to a +pointer to a long argument +.IP ll +(ell\-ell). A following integer conversion corresponds to a \fIlong long\fP or +\fIunsigned long long\fP argument, or a following n conversion corresponds to +a pointer to a long long argument. +.IP q +A synonym for \fBll\fP. +.IP L +A following a, A, e, E, f, F, g, or G conversion corresponds to a long double +argument. +.IP z +A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP +argument. +.SH Conversion specifiers +A character that specifies the type of conversion to be applied. The +conversion specifiers and their meanings are: +.IP "d, i" +The int argument is converted to signed decimal notation. The precision, if +any, gives the minimum number of digits that must appear; if the converted +value requires fewer digits, it is padded on the left with zeros. The default +precision is 1. When 0 is printed with an explicit precision 0, the output is +empty. +.IP "o, u, x, X" +The unsigned int argument is converted to unsigned octal (o), unsigned decimal +(u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters +\fIabcdef\fP are used for \fBx\fP conversions; the letters \fIABCDEF\fP are +used for \fBX\fP conversions. The precision, if any, gives the minimum number +of digits that must appear; if the converted value requires fewer digits, it +is padded on the left with zeros. The default precision is 1. When 0 is +printed with an explicit precision 0, the output is empty. +.IP "e, E" +The double argument is rounded and output in the style \fB"[\-]d.ddde±dd"\fP +.IP "f, F" +The double argument is rounded and output to decimal notation in the style +\fB"[\-]ddd.ddd"\fP. +.IP "g, G" +The double argument is converted in style f or e. +.IP c +The int argument is converted to an unsigned char, and the resulting character +is written. +.IP s +The \fIconst char \fP* argument is expected to be a pointer to an array of +character type (pointer to a string). Characters from the array are written up +to (but not including) a terminating null byte. If a precision is specified, +no more than the number specified are written. If a precision is given, no +null byte need be present; if the precision is not specified, or is greater +than the size of the array, the array must contain a terminating null byte. +.IP p +The \fIvoid \fP* pointer argument is printed in hexadecimal. +.IP n +The number of characters written so far is stored into the integer pointed to +by the corresponding argument. +.IP % +A \(aq%\(aq symbol is written. No argument is converted. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +const char *name = "John"; + +int main(void) +{ + curl_mprintf("My name is %s\\n", name); + curl_mprintf("Pi is almost %f\\n", (double)25.0/8); +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to +a newly allocated string, or NULL if it failed. + +All other functions return the number of characters actually printed +(excluding the null byte used to end output to strings). Note that this +sometimes differ from how the POSIX versions of these functions work. +.SH SEE ALSO +.BR fprintf (3), +.BR printf (3), +.BR sprintf (3), +.BR vprintf (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_add_handle.3 b/3rdparty/curl/share/man/man3/curl_multi_add_handle.3 new file mode 100644 index 0000000..3ae30bf --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_add_handle.3 @@ -0,0 +1,73 @@ +.\" generated by cd2nroff 0.1 from curl_multi_add_handle.md +.TH curl_multi_add_handle 3 "2024-10-11" libcurl +.SH NAME +curl_multi_add_handle \- add an easy handle to a multi session +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle); +.fi +.SH DESCRIPTION +Adds the \fIeasy handle\fP to the \fImulti_handle\fP. + +While an easy handle is added to a multi stack, you cannot and you must not +use \fIcurl_easy_perform(3)\fP on that handle. After having removed the easy +handle from the multi stack again, it is perfectly fine to use it with the +easy interface again. + +If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) cache, +it is made to use a DNS cache that is shared between all easy handles within +the multi handle when \fIcurl_multi_add_handle(3)\fP is called. + +When an easy interface is added to a multi handle, it is set to use a shared +connection cache owned by the multi handle. Removing and adding new easy +handles does not affect the pool of connections or the ability to do +connection reuse. + +If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (as you +should if you are working event\-based with \fIcurl_multi_socket_action(3)\fP +and friends), that callback is called from within this function to ask for an +updated timer so that your main event loop gets the activity on this handle to +get started. + +The easy handle remains added to the multi handle until you remove it again +with \fIcurl_multi_remove_handle(3)\fP \- even when a transfer with that +specific easy handle is completed. + +You should remove the easy handle from the multi stack before you terminate +first the easy handle and then the multi handle: + +1 \- \fIcurl_multi_remove_handle(3)\fP + +2 \- \fIcurl_easy_cleanup(3)\fP + +3 \- \fIcurl_multi_cleanup(3)\fP +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + /* init a multi stack */ + CURLM *multi = curl_multi_init(); + + /* create two easy handles */ + CURL *http_handle = curl_easy_init(); + CURL *http_handle2 = curl_easy_init(); + + /* add individual transfers */ + curl_multi_add_handle(multi, http_handle); + curl_multi_add_handle(multi, http_handle2); +} +.fi +.SH AVAILABILITY +Added in curl 7.9.6 +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH SEE ALSO +.BR curl_multi_cleanup (3), +.BR curl_multi_get_handles (3), +.BR curl_multi_init (3), +.BR curl_multi_setopt (3), +.BR curl_multi_socket_action (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_assign.3 b/3rdparty/curl/share/man/man3/curl_multi_assign.3 new file mode 100644 index 0000000..1231ac8 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_assign.3 @@ -0,0 +1,64 @@ +.\" generated by cd2nroff 0.1 from curl_multi_assign.md +.TH curl_multi_assign 3 "2024-10-11" libcurl +.SH NAME +curl_multi_assign \- set data to associate with an internal socket +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd, + void *sockptr); +.fi +.SH DESCRIPTION +This function creates an association in the multi handle between the given +socket and a private pointer of the application. This is designed for +\fIcurl_multi_socket_action(3)\fP uses. + +When set, the \fIsockptr\fP pointer is passed to all future socket callbacks +for the specific \fIsockfd\fP socket. + +If the given \fIsockfd\fP is not already in use by libcurl, this function +returns an error. + +libcurl only keeps one single pointer associated with a socket, so calling +this function several times for the same socket makes the last set pointer get +used. + +The idea here being that this association (socket to private pointer) is +something that just about every application that uses this API needs and then +libcurl can just as well do it since it already has the necessary +functionality. + +It is acceptable to call this function from your multi callback functions. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *multi = curl_multi_init(); + void *ourstructp; /* pointer to our data */ + curl_socket_t fd; /* file descriptor to associate our data with */ + + /* make our struct pointer associated with socket fd */ + CURLMcode mc = curl_multi_assign(multi, fd, ourstructp); + if(mc) + printf("error: %s\\n", curl_multi_strerror(mc)); +} +.fi +.SH TYPICAL USAGE +In a typical application you allocate a struct or at least use some kind of +semi\-dynamic data for each socket that we must wait for action on when using +the \fIcurl_multi_socket_action(3)\fP approach. + +When our socket\-callback gets called by libcurl and we get to know about yet +another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out the +particular data so that when we get updates about this same socket again, we +do not have to find the struct associated with this socket by ourselves. +.SH AVAILABILITY +Added in curl 7.15.5 +.SH RETURN VALUE +The standard CURLMcode for multi interface error codes. +.SH SEE ALSO +.BR curl_multi_setopt (3), +.BR curl_multi_socket_action (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_cleanup.3 b/3rdparty/curl/share/man/man3/curl_multi_cleanup.3 new file mode 100644 index 0000000..7e732da --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_cleanup.3 @@ -0,0 +1,53 @@ +.\" generated by cd2nroff 0.1 from curl_multi_cleanup.md +.TH curl_multi_cleanup 3 "2024-10-11" libcurl +.SH NAME +curl_multi_cleanup \- close down a multi session +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_cleanup(CURLM *multi_handle); +.fi +.SH DESCRIPTION +This function is the opposite of \fIcurl_multi_init(3)\fP. Cleans up and removes a +whole multi stack. It does not free or touch any individual easy handles in +any way \- they still need to be closed individually, using the usual +\fIcurl_easy_cleanup(3)\fP way. The order of cleaning up should be: + +1 \- \fIcurl_multi_remove_handle(3)\fP before any easy handles are cleaned up + +2 \- \fIcurl_easy_cleanup(3)\fP can now be called independently since the easy +handle is no longer connected to the multi handle + +3 \- \fIcurl_multi_cleanup(3)\fP should be called when all easy handles are +removed + +Passing in a NULL pointer in \fImulti_handle\fP makes this function return +CURLM_BAD_HANDLE immediately with no other action. + +Any use of the \fBmulti_handle\fP after this function has been called and have +returned, is illegal. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *multi = curl_multi_init(); + + /* when the multi transfer is done ... */ + + /* remove all easy handles, then: */ + curl_multi_cleanup(multi); +} +.fi +.SH AVAILABILITY +Added in curl 7.9.6 +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. On success, +CURLM_OK is returned. +.SH SEE ALSO +.BR curl_easy_cleanup (3), +.BR curl_easy_init (3), +.BR curl_multi_get_handles (3), +.BR curl_multi_init (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_fdset.3 b/3rdparty/curl/share/man/man3/curl_multi_fdset.3 new file mode 100644 index 0000000..3995278 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_fdset.3 @@ -0,0 +1,105 @@ +.\" generated by cd2nroff 0.1 from curl_multi_fdset.md +.TH curl_multi_fdset 3 "2024-10-11" libcurl +.SH NAME +curl_multi_fdset \- extract file descriptor information from a multi handle +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_fdset(CURLM *multi_handle, + fd_set *read_fd_set, + fd_set *write_fd_set, + fd_set *exc_fd_set, + int *max_fd); +.fi +.SH DESCRIPTION +This function extracts file descriptor information from a given multi_handle. +libcurl returns its \fIfd_set\fP sets. The application can use these to +select() on, but be sure to \fIFD_ZERO\fP them before calling this function as +\fIcurl_multi_fdset(3)\fP only adds its own descriptors, it does not zero or +otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should +be called as soon as one of them is ready to be read from or written to. + +The \fIread_fd_set\fP argument should point to an object of type \fBfd_set\fP +that on returns specifies the file descriptors to be checked for being ready +to read. + +The \fIwrite_fd_set\fP argument should point to an object of type \fBfd_set\fP +that on return specifies the file descriptors to be checked for being ready to +write. + +The \fIexc_fd_set\fP argument should point to an object of type \fBfd_set\fP +that on return specifies the file descriptors to be checked for error +conditions. + +If no file descriptors are set by libcurl, \fImax_fd\fP contain \-1 when this +function returns. Otherwise it contains the highest descriptor number libcurl +set. When libcurl returns \-1 in \fImax_fd\fP, it is because libcurl currently +does something that is not possible for your application to monitor with a +socket and unfortunately you can then not know exactly when the current action +is completed using select(). You then need to wait a while before you proceed +and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless +\fIcurl_multi_timeout(3)\fP gives you a lower number, we suggest 100 +milliseconds or so, but you may want to test it out in your own particular +conditions to find a suitable value. + +When doing select(), you should use \fIcurl_multi_timeout(3)\fP to figure out +how long to wait for action. Call \fIcurl_multi_perform(3)\fP even if no +activity has been seen on the \fBfd_sets\fP after the timeout expires as +otherwise internal retries and timeouts may not work as you would think and +want. + +If one of the sockets used by libcurl happens to be larger than what can be +set in an \fBfd_set\fP, which on POSIX systems means that the file descriptor +is larger than \fBFD_SETSIZE\fP, then libcurl tries to not set it. Setting a +too large file descriptor in an \fBfd_set\fP implies an out of bounds write +which can cause crashes, or worse. The effect of NOT storing it might possibly +save you from the crash, but makes your program NOT wait for sockets it should +wait for... +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + fd_set fdread; + fd_set fdwrite; + fd_set fdexcep; + int maxfd; + int rc; + CURLMcode mc; + struct timeval timeout = {1, 0}; + + CURLM *multi = curl_multi_init(); + + do { + + /* call curl_multi_perform() */ + + /* get file descriptors from the transfers */ + mc = curl_multi_fdset(multi, &fdread, &fdwrite, &fdexcep, &maxfd); + + if(mc != CURLM_OK) { + fprintf(stderr, "curl_multi_fdset() failed, code %d.\\n", mc); + break; + } + + /* wait for activity on one of the sockets */ + rc = select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout); + + } while(!mc); +} +.fi +.SH AVAILABILITY +Added in curl 7.9.6 +.SH RETURN VALUE +\fBCURLMcode\fP type, general libcurl multi interface error code. See +\fIlibcurl\-errors(3)\fP +.SH SEE ALSO +.BR curl_multi_cleanup (3), +.BR curl_multi_init (3), +.BR curl_multi_perform (3), +.BR curl_multi_timeout (3), +.BR curl_multi_wait (3), +.BR curl_multi_waitfds (3), +.BR select (2) diff --git a/3rdparty/curl/share/man/man3/curl_multi_get_handles.3 b/3rdparty/curl/share/man/man3/curl_multi_get_handles.3 new file mode 100644 index 0000000..ef4e99d --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_get_handles.3 @@ -0,0 +1,62 @@ +.\" generated by cd2nroff 0.1 from curl_multi_get_handles.md +.TH curl_multi_get_handles 3 "2024-10-11" libcurl +.SH NAME +curl_multi_get_handles \- return all added easy handles +.SH SYNOPSIS +.nf +#include + +CURL **curl_multi_get_handles(CURLM *multi_handle); +.fi +.SH DESCRIPTION +Returns an array with pointers to all added easy handles. The end of the list +is marked with a NULL pointer. + +Even if there is not a single easy handle added, this still returns an array +but with only a single NULL pointer entry. + +The returned array contains all the handles that are present at the time of +the call. As soon as a handle has been removed from or a handle has been added +to the multi handle after the handle array was returned, the two data points +are out of sync. + +The order of the easy handles within the array is not guaranteed. + +The returned array must be freed with a call to \fIcurl_free(3)\fP after use. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + /* init a multi stack */ + CURLM *multi = curl_multi_init(); + CURL *curl = curl_easy_init(); + + if(curl) { + /* add the transfer */ + curl_multi_add_handle(multi, curl); + + /* extract all added handles */ + CURL **list = curl_multi_get_handles(multi); + + if(list) { + int i; + /* remove all added handles */ + for(i = 0; list[i]; i++) { + curl_multi_remove_handle(multi, list[i]); + } + curl_free(list); + } + } +} +.fi +.SH AVAILABILITY +Added in curl 8.4.0 +.SH RETURN VALUE +Returns NULL on failure. Otherwise it returns a pointer to an allocated array. +.SH SEE ALSO +.BR curl_multi_add_handle (3), +.BR curl_multi_cleanup (3), +.BR curl_multi_init (3), +.BR curl_multi_remove_handle (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_info_read.3 b/3rdparty/curl/share/man/man3/curl_multi_info_read.3 new file mode 100644 index 0000000..f5690ac --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_info_read.3 @@ -0,0 +1,88 @@ +.\" generated by cd2nroff 0.1 from curl_multi_info_read.md +.TH curl_multi_info_read 3 "2024-10-11" libcurl +.SH NAME +curl_multi_info_read \- read multi stack information +.SH SYNOPSIS +.nf +#include + +CURLMsg *curl_multi_info_read(CURLM *multi_handle, int *msgs_in_queue); +.fi +.SH DESCRIPTION +Ask the multi handle if there are any messages from the individual +transfers. Messages may include information such as an error code from the +transfer or just the fact that a transfer is completed. More details on these +should be written down as well. + +Repeated calls to this function returns a new struct each time, until a NULL +is returned as a signal that there is no more to get at this point. The +integer pointed to with \fImsgs_in_queue\fP contains the number of remaining +messages after this function was called. + +When you fetch a message using this function, it is removed from the internal +queue so calling this function again does not return the same message +again. It instead returns new messages at each new invoke until the queue is +emptied. + +\fBWARNING:\fP The data the returned pointer points to does not survive +calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or +\fIcurl_easy_cleanup(3)\fP. + +The \fICURLMsg\fP struct is simple and only contains basic information. If +more involved information is wanted, the particular "easy handle" is present +in that struct and can be used in subsequent regular +\fIcurl_easy_getinfo(3)\fP calls (or similar): + +.nf + struct CURLMsg { + CURLMSG msg; /* what this message means */ + CURL *easy_handle; /* the handle it concerns */ + union { + void *whatever; /* message-specific data */ + CURLcode result; /* return code for transfer */ + } data; + }; +.fi + +When \fBmsg\fP is \fICURLMSG_DONE\fP, the message identifies a transfer that +is done, and then \fBresult\fP contains the return code for the easy handle +that just completed. + +At this point, there are no other \fBmsg\fP types defined. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *multi = curl_multi_init(); + CURL *curl = curl_easy_init(); + if(curl) { + struct CURLMsg *m; + + /* call curl_multi_perform or curl_multi_socket_action first, then loop + through and check if there are any transfers that have completed */ + + do { + int msgq = 0; + m = curl_multi_info_read(multi, &msgq); + if(m && (m->msg == CURLMSG_DONE)) { + CURL *e = m->easy_handle; + /* m->data.result holds the error code for the transfer */ + curl_multi_remove_handle(multi, e); + curl_easy_cleanup(e); + } + } while(m); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.6 +.SH RETURN VALUE +A pointer to a filled\-in struct, or NULL if it failed or ran out of +structs. It also writes the number of messages left in the queue (after this +read) in the integer the second argument points to. +.SH SEE ALSO +.BR curl_multi_cleanup (3), +.BR curl_multi_init (3), +.BR curl_multi_perform (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_init.3 b/3rdparty/curl/share/man/man3/curl_multi_init.3 new file mode 100644 index 0000000..1cb7c30 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_init.3 @@ -0,0 +1,42 @@ +.\" generated by cd2nroff 0.1 from curl_multi_init.md +.TH curl_multi_init 3 "2024-10-11" libcurl +.SH NAME +curl_multi_init \- create a multi handle +.SH SYNOPSIS +.nf +#include + +CURLM *curl_multi_init(); +.fi +.SH DESCRIPTION +This function returns a pointer to a \fICURLM\fP handle to be used as input to +all the other multi\-functions, sometimes referred to as a multi handle in some +places in the documentation. This init call MUST have a corresponding call to +\fIcurl_multi_cleanup(3)\fP when the operation is complete. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + /* init a multi stack */ + CURLM *multi = curl_multi_init(); + CURL *curl = curl_easy_init(); + CURL *curl2 = curl_easy_init(); + + /* add individual transfers */ + curl_multi_add_handle(multi, curl); + curl_multi_add_handle(multi, curl2); +} +.fi +.SH AVAILABILITY +Added in curl 7.9.6 +.SH RETURN VALUE +If this function returns NULL, something went wrong and you cannot use the +other curl functions. +.SH SEE ALSO +.BR curl_easy_init (3), +.BR curl_global_init (3), +.BR curl_multi_add_handle (3), +.BR curl_multi_cleanup (3), +.BR curl_multi_get_handles (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_perform.3 b/3rdparty/curl/share/man/man3/curl_multi_perform.3 new file mode 100644 index 0000000..b9401db --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_perform.3 @@ -0,0 +1,90 @@ +.\" generated by cd2nroff 0.1 from curl_multi_perform.md +.TH curl_multi_perform 3 "2024-10-11" libcurl +.SH NAME +curl_multi_perform \- run all transfers until it would block +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles); +.fi +.SH DESCRIPTION +This function performs transfers on all the added handles that need attention +in a non\-blocking fashion. The easy handles have previously been added to the +multi handle with \fIcurl_multi_add_handle(3)\fP. + +When an application has found out there is data available for the multi_handle +or a timeout has elapsed, the application should call this function to +read/write whatever there is to read or write right now etc. +\fIcurl_multi_perform(3)\fP returns as soon as the reads/writes are done. This +function does not require that there actually is any data available for +reading or that data can be written, it can be called just in case. It stores +the number of handles that still transfer data in the second argument\(aqs +integer\-pointer. + +If the amount of \fIrunning_handles\fP is changed from the previous call (or +is less than the amount of easy handles you have added to the multi handle), +you know that there is one or more transfers less "running". You can then call +\fIcurl_multi_info_read(3)\fP to get information about each individual +completed transfer, and that returned info includes CURLcode and more. If an +added handle fails quickly, it may never be counted as a running_handle. You +could use \fIcurl_multi_info_read(3)\fP to track actual status of the added +handles in that case. + +When \fIrunning_handles\fP is set to zero (0) on the return of this function, +there is no longer any transfers in progress. + +When this function returns error, the state of all transfers are uncertain and +they cannot be continued. \fIcurl_multi_perform(3)\fP should not be called +again on the same multi handle after an error has been returned, unless first +removing all the handles and adding new ones. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + int still_running; + CURL *multi = curl_multi_init(); + CURL *curl = curl_easy_init(); + if(curl) { + curl_multi_add_handle(multi, curl); + do { + CURLMcode mc = curl_multi_perform(multi, &still_running); + + if(!mc && still_running) + /* wait for activity, timeout or "nothing" */ + mc = curl_multi_poll(multi, NULL, 0, 1000, NULL); + + if(mc) { + fprintf(stderr, "curl_multi_poll() failed, code %d.\\n", (int)mc); + break; + } + + /* if there are still transfers, loop! */ + } while(still_running); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.6 +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. + +This function returns errors regarding the whole multi stack. Problems on +individual transfers may have occurred even when this function returns +\fICURLM_OK\fP. Use \fIcurl_multi_info_read(3)\fP to figure out how individual +transfers did. +.SH TYPICAL USAGE +Most applications use \fIcurl_multi_poll(3)\fP to make libcurl wait for +activity on any of the ongoing transfers. As soon as one or more file +descriptor has activity or the function times out, the application calls +\fIcurl_multi_perform(3)\fP. +.SH SEE ALSO +.BR curl_multi_add_handle (3), +.BR curl_multi_cleanup (3), +.BR curl_multi_fdset (3), +.BR curl_multi_info_read (3), +.BR curl_multi_init (3), +.BR curl_multi_wait (3), +.BR libcurl-errors (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_poll.3 b/3rdparty/curl/share/man/man3/curl_multi_poll.3 new file mode 100644 index 0000000..54292d8 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_poll.3 @@ -0,0 +1,119 @@ +.\" generated by cd2nroff 0.1 from curl_multi_poll.md +.TH curl_multi_poll 3 "2024-10-11" libcurl +.SH NAME +curl_multi_poll \- poll on all easy handles in a multi handle +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_poll(CURLM *multi_handle, + struct curl_waitfd extra_fds[], + unsigned int extra_nfds, + int timeout_ms, + int *numfds); +.fi +.SH DESCRIPTION +\fIcurl_multi_poll(3)\fP polls all file descriptors used by the curl easy +handles contained in the given multi handle set. It blocks until activity is +detected on at least one of the handles or \fItimeout_ms\fP has passed. +Alternatively, if the multi handle has a pending internal timeout that has a +shorter expiry time than \fItimeout_ms\fP, that shorter time is used instead +to make sure timeout accuracy is reasonably kept. + +The calling application may pass additional curl_waitfd structures which are +similar to \fIpoll(2)\fP\(aqs \fIpollfd\fP structure to be waited on in the same +call. + +On completion, if \fInumfds\fP is non\-NULL, it gets populated with the total +number of file descriptors on which interesting events occurred. This number +can include both libcurl internal descriptors as well as descriptors provided +in \fIextra_fds\fP. + +The \fIcurl_multi_wakeup(3)\fP function can be used from another thread to +wake up this function and return faster. This is one of the details +that makes this function different than \fIcurl_multi_wait(3)\fP which cannot +be woken up this way. + +If no extra file descriptors are provided and libcurl has no file descriptor +to offer to wait for, this function instead waits during \fItimeout_ms\fP +milliseconds (or shorter if an internal timer indicates so). This is the other +detail that makes this function different than \fIcurl_multi_wait(3)\fP. + +This function is encouraged to be used instead of select(3) when using the +multi interface to allow applications to easier circumvent the common problem +with 1024 maximum file descriptors. +.SH curl_waitfd +.nf +struct curl_waitfd { + curl_socket_t fd; + short events; + short revents; +}; +.fi +.IP CURL_WAIT_POLLIN +Bit flag to curl_waitfd.events indicating the socket should poll on read +events such as new data received. +.IP CURL_WAIT_POLLPRI +Bit flag to curl_waitfd.events indicating the socket should poll on high +priority read events such as out of band data. +.IP CURL_WAIT_POLLOUT +Bit flag to curl_waitfd.events indicating the socket should poll on write +events such as the socket being clear to write without blocking. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +extern void handle_fd(int); + +int main(void) +{ + CURL *easy_handle; + CURLM *multi_handle; + int still_running = 0; + int myfd; /* this is our own file descriptor */ + + /* add the individual easy handle */ + curl_multi_add_handle(multi_handle, easy_handle); + + do { + CURLMcode mc; + int numfds; + + mc = curl_multi_perform(multi_handle, &still_running); + + if(mc == CURLM_OK) { + struct curl_waitfd myown; + myown.fd = myfd; + myown.events = CURL_WAIT_POLLIN; /* wait for input */ + myown.revents = 0; /* clear it */ + + /* wait for activity on curl's descriptors or on our own, + or timeout */ + mc = curl_multi_poll(multi_handle, &myown, 1, 1000, &numfds); + + if(myown.revents) { + /* did our descriptor receive an event? */ + handle_fd(myfd); + } + } + + if(mc != CURLM_OK) { + fprintf(stderr, "curl_multi failed, code %d.\\n", mc); + break; + } + + } while(still_running); + + curl_multi_remove_handle(multi_handle, easy_handle); +} +.fi +.SH AVAILABILITY +Added in curl 7.66.0 +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. See +\fIlibcurl\-errors(3)\fP +.SH SEE ALSO +.BR curl_multi_fdset (3), +.BR curl_multi_perform (3), +.BR curl_multi_wait (3), +.BR curl_multi_wakeup (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_remove_handle.3 b/3rdparty/curl/share/man/man3/curl_multi_remove_handle.3 new file mode 100644 index 0000000..eb6bd37 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_remove_handle.3 @@ -0,0 +1,58 @@ +.\" generated by cd2nroff 0.1 from curl_multi_remove_handle.md +.TH curl_multi_remove_handle 3 "2024-10-11" libcurl +.SH NAME +curl_multi_remove_handle \- remove an easy handle from a multi session +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle); +.fi +.SH DESCRIPTION +Removes a given \fIeasy_handle\fP from the \fImulti_handle\fP. This makes the +specified easy handle be removed from this multi handle\(aqs control. + +When the easy handle has been removed from a multi stack, it is again +perfectly legal to invoke \fIcurl_easy_perform(3)\fP on this easy handle. + +Removing an easy handle while being in use is perfectly legal and effectively +halts the transfer in progress involving that easy handle. All other easy +handles and transfers remain unaffected. + +It is fine to remove a handle at any time during a transfer, just not from +within any libcurl callback function. + +Removing an easy handle from the multi handle before the corresponding +transfer is complete might cause libcurl to close the connection \- if the +state of it and the internal protocol handler deem it necessary. Otherwise +libcurl keeps the connection alive in the connection pool associated with the +multi handle, ready to get reused for a future transfer using this multi +handle. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLM *multi = curl_multi_init(); + int queued = 0; + + /* when an easy handle has completed, remove it */ + CURLMsg *msg = curl_multi_info_read(multi, &queued); + if(msg) { + if(msg->msg == CURLMSG_DONE) { + /* a transfer ended */ + fprintf(stderr, "Transfer completed\\n"); + curl_multi_remove_handle(multi, msg->easy_handle); + } + } +} +.fi +.SH AVAILABILITY +Added in curl 7.9.6 +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH SEE ALSO +.BR curl_multi_add_handle (3), +.BR curl_multi_cleanup (3), +.BR curl_multi_init (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_setopt.3 b/3rdparty/curl/share/man/man3/curl_multi_setopt.3 new file mode 100644 index 0000000..51450ea --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_setopt.3 @@ -0,0 +1,78 @@ +.\" generated by cd2nroff 0.1 from curl_multi_setopt.md +.TH curl_multi_setopt 3 "2024-10-11" libcurl +.SH NAME +curl_multi_setopt \- set options for a curl multi handle +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_setopt(CURLM *multi, CURLMoption option, parameter); +.fi +.SH DESCRIPTION +\fIcurl_multi_setopt(3)\fP is used to tell a libcurl multi handle how to behave. By +using the appropriate options to \fIcurl_multi_setopt(3)\fP, you can change +libcurl\(aqs behavior when using that multi handle. All options are set with the +\fIoption\fP followed by the \fIparameter\fP. That parameter can be a \fBlong\fP, a +\fBfunction pointer\fP, an \fBobject pointer\fP or a \fBcurl_off_t\fP type, +depending on what the specific option expects. Read this manual carefully as +bad input values may cause libcurl to behave badly. You can only set one +option in each function call. +.SH OPTIONS +.IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE +\fBdeprecated\fP See \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP +.IP CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE +\fBdeprecated\fP See \fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP +.IP CURLMOPT_MAXCONNECTS +Size of connection cache. See \fICURLMOPT_MAXCONNECTS(3)\fP +.IP CURLMOPT_MAX_CONCURRENT_STREAMS +Max concurrent streams for http2. See \fICURLMOPT_MAX_CONCURRENT_STREAMS(3)\fP +.IP CURLMOPT_MAX_HOST_CONNECTIONS +Max number of connections to a single host. See +\fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP +.IP CURLMOPT_MAX_PIPELINE_LENGTH +\fBdeprecated\fP. See \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP +.IP CURLMOPT_MAX_TOTAL_CONNECTIONS +Max simultaneously open connections. See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP +.IP CURLMOPT_PIPELINING +Enable HTTP multiplexing. See \fICURLMOPT_PIPELINING(3)\fP +.IP CURLMOPT_PIPELINING_SERVER_BL +\fBdeprecated\fP. See \fICURLMOPT_PIPELINING_SERVER_BL(3)\fP +.IP CURLMOPT_PIPELINING_SITE_BL +\fBdeprecated\fP. See \fICURLMOPT_PIPELINING_SITE_BL(3)\fP +.IP CURLMOPT_PUSHDATA +Pointer to pass to push callback. See \fICURLMOPT_PUSHDATA(3)\fP +.IP CURLMOPT_PUSHFUNCTION +Callback that approves or denies server pushes. See \fICURLMOPT_PUSHFUNCTION(3)\fP +.IP CURLMOPT_SOCKETDATA +Custom pointer passed to the socket callback. See \fICURLMOPT_SOCKETDATA(3)\fP +.IP CURLMOPT_SOCKETFUNCTION +Callback informed about what to wait for. See \fICURLMOPT_SOCKETFUNCTION(3)\fP +.IP CURLMOPT_TIMERDATA +Custom pointer to pass to timer callback. See \fICURLMOPT_TIMERDATA(3)\fP +.IP CURLMOPT_TIMERFUNCTION +Callback to receive timeout values. See \fICURLMOPT_TIMERFUNCTION(3)\fP +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf + +#define MAX_PARALLEL 45 + +int main(void) +{ + CURLM *multi; + /* Limit the amount of simultaneous connections curl should allow: */ + curl_multi_setopt(multi, CURLMOPT_MAXCONNECTS, (long)MAX_PARALLEL); +} +.fi +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +The standard CURLMcode for multi interface error codes. Note that it returns a +CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl +does not know of. +.SH SEE ALSO +.BR curl_multi_cleanup (3), +.BR curl_multi_info_read (3), +.BR curl_multi_init (3), +.BR curl_multi_socket (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_socket.3 b/3rdparty/curl/share/man/man3/curl_multi_socket.3 new file mode 100644 index 0000000..d845c65 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_socket.3 @@ -0,0 +1,68 @@ +.\" generated by cd2nroff 0.1 from curl_multi_socket.md +.TH curl_multi_socket 3 "2024-10-11" libcurl +.SH NAME +curl_multi_socket \- read/write available data +.SH SYNOPSIS +.nf +#include +CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd, + int *running_handles); +.fi +.SH DESCRIPTION +This function is deprecated. Do not use. See \fIcurl_multi_socket_action(3)\fP +instead. + +At return, the integer \fBrunning_handles\fP points to contains the number of +still running easy handles within the multi handle. When this number reaches +zero, all transfers are complete/done. Note that when you call +\fIcurl_multi_socket(3)\fP on a specific socket and the counter decreases by one, it +DOES NOT necessarily mean that this exact socket/transfer is the one that +completed. Use \fIcurl_multi_info_read(3)\fP to figure out which easy handle that +completed. + +The \fIcurl_multi_socket(3)\fP functions inform the application about updates in the +socket (file descriptor) status by doing none, one, or multiple calls to the +socket callback function set with the \fICURLMOPT_SOCKETFUNCTION(3)\fP option to +\fIcurl_multi_setopt(3)\fP. They update the status with changes since the previous +time the callback was called. + +Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option with +\fIcurl_multi_setopt(3)\fP. Your application then gets called with information on +how long to wait for socket actions at most before doing the timeout action: +call the \fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set +to CURL_SOCKET_TIMEOUT. You can also use the \fIcurl_multi_timeout(3)\fP function to +poll the value at any given time, but for an event\-based system using the +callback is far better than relying on polling the timeout value. + +Usage of \fIcurl_multi_socket(3)\fP is deprecated, whereas the function is +equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to 0. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + /* the event-library gets told when there activity on the socket 'fd', + which we translate to a call to curl_multi_socket_action() */ + int running; + int rc; + int fd; + CURLM *multi; + rc = curl_multi_socket(multi, fd, &running); +} +.fi +.SH DEPRECATED +\fIcurl_multi_socket(3)\fP is deprecated, use \fIcurl_multi_socket_action(3)\fP instead! +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. + +The return code is for the whole multi stack. Problems still might have +occurred on individual transfers even when one of these functions return OK. +.SH SEE ALSO +.BR curl_multi_cleanup (3), +.BR curl_multi_fdset (3), +.BR curl_multi_info_read (3), +.BR curl_multi_init (3), +.BR the hiperfifo.c example diff --git a/3rdparty/curl/share/man/man3/curl_multi_socket_action.3 b/3rdparty/curl/share/man/man3/curl_multi_socket_action.3 new file mode 100644 index 0000000..66aca54 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_socket_action.3 @@ -0,0 +1,103 @@ +.\" generated by cd2nroff 0.1 from curl_multi_socket_action.md +.TH curl_multi_socket_action 3 "2024-10-11" libcurl +.SH NAME +curl_multi_socket_action \- read/write available data given an action +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_socket_action(CURLM *multi_handle, + curl_socket_t sockfd, + int ev_bitmask, + int *running_handles); +.fi +.SH DESCRIPTION +When the application has detected action on a socket handled by libcurl, it +should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument +set to the socket with the action. When the events on a socket are known, they +can be passed as an events bitmask \fBev_bitmask\fP by first setting +\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of +events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or +CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and +libcurl tests the descriptor internally. It is also permissible to pass +CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the +whole process or when a timeout occurs. + +At return, \fBrunning_handles\fP points to the number of running easy handles +within the multi handle. When this number reaches zero, all transfers are +complete/done. When you call \fIcurl_multi_socket_action(3)\fP on a specific +socket and the counter decreases by one, it DOES NOT necessarily mean that +this exact socket/transfer is the one that completed. Use +\fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed. + +The \fIcurl_multi_socket_action(3)\fP function informs the application about +updates in the socket (file descriptor) status by doing none, one, or multiple +calls to the socket callback function set with the +\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They +update the status with changes since the previous time the callback was +called. + +Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option +with \fIcurl_multi_setopt(3)\fP. Your application then gets called with +information on how long to wait for socket actions at most before doing the +timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the +\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the +\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but +for an event\-based system using the callback is far better than relying on +polling the timeout value. + +When this function returns error, the state of all transfers are uncertain and +they cannot be continued. \fIcurl_multi_socket_action(3)\fP should not be +called again on the same multi handle after an error has been returned, unless +first removing all the handles and adding new ones. +.SH TYPICAL USAGE +1. Create a multi handle + +2. Set the socket callback with \fICURLMOPT_SOCKETFUNCTION(3)\fP + +3. Set the timeout callback with \fICURLMOPT_TIMERFUNCTION(3)\fP, to get to +know what timeout value to use when waiting for socket activities. + +4. Add easy handles with curl_multi_add_handle() + +5. Provide some means to manage the sockets libcurl is using, so you can check +them for activity. This can be done through your application code, or by way +of an external library such as libevent or glib. + +6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...) +to kickstart everything. To get one or more callbacks called. + +7. Wait for activity on any of libcurl\(aqs sockets, use the timeout value your +callback has been told. + +8, When activity is detected, call curl_multi_socket_action() for the +socket(s) that got action. If no activity is detected and the timeout expires, +call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + /* the event-library gets told when there activity on the socket 'fd', + which we translate to a call to curl_multi_socket_action() */ + int running; + CURLM *multi; /* the stack we work with */ + int fd; /* the descriptor that had action */ + int bitmask; /* what activity that happened */ + CURLMcode mc = curl_multi_socket_action(multi, fd, bitmask, &running); + if(mc) + printf("error: %s\\n", curl_multi_strerror(mc)); +} +.fi +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. See +\fIlibcurl\-errors(3)\fP +.SH SEE ALSO +.BR curl_multi_cleanup (3), +.BR curl_multi_fdset (3), +.BR curl_multi_info_read (3), +.BR curl_multi_init (3), +.BR the hiperfifo.c example diff --git a/3rdparty/curl/share/man/man3/curl_multi_socket_all.3 b/3rdparty/curl/share/man/man3/curl_multi_socket_all.3 new file mode 100644 index 0000000..936bf3a --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_socket_all.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from curl_multi_socket_all.md +.TH curl_multi_socket_all 3 "2024-10-11" libcurl +.SH NAME +curl_multi_socket_all \- reads/writes available data for all easy handles +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_socket_all(CURLM *multi_handle, + int *running_handles); +.fi +.SH DESCRIPTION +This function is deprecated. Do not use. See \fIcurl_multi_socket_action(3)\fP +instead. + +At return, the integer \fBrunning_handles\fP points to contains the number of +still running easy handles within the multi handle. When this number reaches +zero, all transfers are complete/done. + +Force libcurl to (re\-)check all its internal sockets and transfers instead of +just a single one by calling \fIcurl_multi_socket_all(3)\fP. Note that there should +not be any reason to use this function. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + int running; + int rc; + CURLM *multi; + rc = curl_multi_socket_all(multi, &running); +} +.fi +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. + +The return code is for the whole multi stack. Problems still might have +occurred on individual transfers even when one of these functions return OK. +.SH SEE ALSO +.BR curl_multi_cleanup (3), +.BR curl_multi_fdset (3), +.BR curl_multi_info_read (3), +.BR curl_multi_init (3), +.BR the hiperfifo.c example diff --git a/3rdparty/curl/share/man/man3/curl_multi_strerror.3 b/3rdparty/curl/share/man/man3/curl_multi_strerror.3 new file mode 100644 index 0000000..752060b --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_strerror.3 @@ -0,0 +1,36 @@ +.\" generated by cd2nroff 0.1 from curl_multi_strerror.md +.TH curl_multi_strerror 3 "2024-10-11" libcurl +.SH NAME +curl_multi_strerror \- return string describing error code +.SH SYNOPSIS +.nf +#include + +const char *curl_multi_strerror(CURLMcode errornum); +.fi +.SH DESCRIPTION +This function returns a string describing the \fICURLMcode\fP error code +passed in the argument \fIerrornum\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + int still_running; + CURLM *multi = curl_multi_init(); + + CURLMcode mc = curl_multi_perform(multi, &still_running); + if(mc) + printf("error: %s\\n", curl_multi_strerror(mc)); +} +.fi +.SH AVAILABILITY +Added in curl 7.12.0 +.SH RETURN VALUE +A pointer to a null\-terminated string. +.SH SEE ALSO +.BR curl_easy_strerror (3), +.BR curl_share_strerror (3), +.BR curl_url_strerror (3), +.BR libcurl-errors (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_timeout.3 b/3rdparty/curl/share/man/man3/curl_multi_timeout.3 new file mode 100644 index 0000000..e5738f5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_timeout.3 @@ -0,0 +1,72 @@ +.\" generated by cd2nroff 0.1 from curl_multi_timeout.md +.TH curl_multi_timeout 3 "2024-10-11" libcurl +.SH NAME +curl_multi_timeout \- how long to wait for action before proceeding +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout); +.fi +.SH DESCRIPTION +An application using the libcurl multi interface should call +\fIcurl_multi_timeout(3)\fP to figure out how long it should wait for socket +actions \- at most \- before proceeding. + +Proceeding means either doing the socket\-style timeout action: call the +\fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set +to CURL_SOCKET_TIMEOUT, or call \fIcurl_multi_perform(3)\fP if you are using +the simpler and older multi interface approach. + +The timeout value returned in the long \fBtimeout\fP points to, is in number +of milliseconds at this moment. If 0, it means you should proceed immediately +without waiting for anything. If it returns \-1, there is no timeout at all set. + +An application that uses the \fImulti_socket\fP API should not use this function. +It should instead use the \fICURLMOPT_TIMERFUNCTION(3)\fP option for proper and +desired behavior. + +Note: if libcurl returns a \-1 timeout here, it just means that libcurl +currently has no stored timeout value. You must not wait too long (more than a +few seconds perhaps) before you call \fIcurl_multi_perform(3)\fP again. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + struct timeval timeout; + long timeo; + fd_set fdread; + fd_set fdwrite; + fd_set fdexcep; + int maxfd; + CURLM *multi = curl_multi_init(); + + curl_multi_timeout(multi, &timeo); + if(timeo < 0) + /* no set timeout, use a default */ + timeo = 980; + + timeout.tv_sec = timeo / 1000; + timeout.tv_usec = (timeo % 1000) * 1000; + + /* wait for activities no longer than the set timeout */ + select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout); +} +.fi +.SH TYPICAL USAGE +Call \fIcurl_multi_timeout(3)\fP, then wait for action on the sockets. Figure +out which sockets to wait for by calling \fIcurl_multi_fdset(3)\fP. + +When there is activity or timeout, call \fIcurl_multi_perform(3)\fP and then +loop \- until all transfers are complete. +.SH AVAILABILITY +Added in curl 7.15.4 +.SH RETURN VALUE +The standard CURLMcode for multi interface error codes. +.SH SEE ALSO +.BR curl_multi_fdset (3), +.BR curl_multi_info_read (3), +.BR curl_multi_setopt (3), +.BR curl_multi_socket (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_wait.3 b/3rdparty/curl/share/man/man3/curl_multi_wait.3 new file mode 100644 index 0000000..725b851 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_wait.3 @@ -0,0 +1,98 @@ +.\" generated by cd2nroff 0.1 from curl_multi_wait.md +.TH curl_multi_wait 3 "2024-10-11" libcurl +.SH NAME +curl_multi_wait \- poll on all easy handles in a multi handle +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_wait(CURLM *multi_handle, + struct curl_waitfd extra_fds[], + unsigned int extra_nfds, + int timeout_ms, + int *numfds); +.fi +.SH DESCRIPTION +\fIcurl_multi_wait(3)\fP polls all file descriptors used by the curl easy +handles contained in the given multi handle set. It blocks until activity is +detected on at least one of the handles or \fItimeout_ms\fP has passed. +Alternatively, if the multi handle has a pending internal timeout that has a +shorter expiry time than \fItimeout_ms\fP, that shorter time is being used +instead to make sure timeout accuracy is reasonably kept. + +The calling application may pass additional \fIcurl_waitfd\fP structures which +are similar to \fIpoll(2)\fP\(aqs \fIpollfd\fP structure to be waited on in the +same call. + +On completion, if \fInumfds\fP is non\-NULL, it gets populated with the total +number of file descriptors on which interesting events occurred. This number +can include both libcurl internal descriptors as well as descriptors provided +in \fIextra_fds\fP. + +If no extra file descriptors are provided and libcurl has no file descriptor +to offer to wait for, this function returns immediately. (Consider using +\fIcurl_multi_poll(3)\fP to avoid this behavior.) + +This function is encouraged to be used instead of select(3) when using the +multi interface to allow applications to easier circumvent the common problem +with 1024 maximum file descriptors. +.SH curl_waitfd +.nf +struct curl_waitfd { + curl_socket_t fd; + short events; + short revents; +}; +.fi +.IP CURL_WAIT_POLLIN +Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on read +events such as new data received. +.IP CURL_WAIT_POLLPRI +Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on high +priority read events such as out of band data. +.IP CURL_WAIT_POLLOUT +Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on +write events such as the socket being clear to write without blocking. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *easy; + CURLM *multi = curl_multi_init(); + int still_running; + + /* add the individual easy handle */ + curl_multi_add_handle(multi, easy); + + do { + CURLMcode mc; + int numfds; + + mc = curl_multi_perform(multi, &still_running); + + if(mc == CURLM_OK) { + /* wait for activity, timeout or "nothing" */ + mc = curl_multi_wait(multi, NULL, 0, 1000, &numfds); + } + + if(mc != CURLM_OK) { + fprintf(stderr, "curl_multi failed, code %d.\\n", mc); + break; + } + + } while(still_running); + + curl_multi_remove_handle(multi, easy); +} +.fi +.SH AVAILABILITY +Added in curl 7.28.0 +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. See +\fIlibcurl\-errors(3)\fP +.SH SEE ALSO +.BR curl_multi_fdset (3), +.BR curl_multi_perform (3), +.BR curl_multi_poll (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_waitfds.3 b/3rdparty/curl/share/man/man3/curl_multi_waitfds.3 new file mode 100644 index 0000000..eee17a1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_waitfds.3 @@ -0,0 +1,94 @@ +.\" generated by cd2nroff 0.1 from curl_multi_waitfds.md +.TH curl_multi_waitfds 3 "2024-10-11" libcurl +.SH NAME +curl_multi_waitfds \- extract file descriptor information from a multi handle +.SH SYNOPSIS +.nf +#include +#include + +CURLMcode curl_multi_waitfds(CURLM *multi, + struct curl_waitfd *ufds, + unsigned int size, + unsigned int *fd_count); +.fi +.SH DESCRIPTION +This function extracts \fIcurl_waitfd\fP structures which are similar to +\fIpoll(2)\fP\(aqs \fIpollfd\fP structure from a given multi_handle. + +These structures can be used for polling on multi_handle file descriptors in a +fashion similar to \fIcurl_multi_poll(3)\fP. The \fIcurl_multi_perform(3)\fP +function should be called as soon as one of them is ready to be read from or +written to. + +libcurl fills provided \fIufds\fP array up to the \fIsize\fP. +If a number of descriptors used by the multi_handle is greater than the +\fIsize\fP parameter then libcurl returns CURLM_OUT_OF_MEMORY error. + +If the \fIfd_count\fP argument is not a null pointer, it points to a variable +that on returns specifies the number of descriptors used by the multi_handle to +be checked for being ready to read or write. + +The client code can pass \fIsize\fP equal to zero just to get the number of the +descriptors and allocate appropriate storage for them to be used in a +subsequent function call. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +#include + +int main(void) +{ + CURLMcode mc; + struct curl_waitfd *ufds; + + CURLM *multi = curl_multi_init(); + + do { + /* call curl_multi_perform() */ + + /* get the count of file descriptors from the transfers */ + unsigned int fd_count = 0; + + mc = curl_multi_waitfds(multi, NULL, 0, &fd_count); + + if(mc != CURLM_OK) { + fprintf(stderr, "curl_multi_waitfds() failed, code %d.\\n", mc); + break; + } + + if(!fd_count) + continue; /* no descriptors yet */ + + /* Allocate storage for our descriptors. + * Note that a better approach can be used to minimize allocations and + * deallocations, if needed, like pre-allocated or grow-only array. + */ + ufds = (struct curl_waitfd*)malloc(fd_count * sizeof(struct curl_waitfd)); + + /* get wait descriptors from the transfers and put them into array. */ + mc = curl_multi_waitfds(multi, ufds, fd_count, NULL); + + if(mc != CURLM_OK) { + fprintf(stderr, "curl_multi_waitfds() failed, code %d.\\n", mc); + free(ufds); + break; + } + + /* Do polling on descriptors in ufds */ + + free(ufds); + } while(!mc); +} +.fi +.SH AVAILABILITY +Added in curl 8.8.0 +.SH RETURN VALUE +\fBCURLMcode\fP type, general libcurl multi interface error code. See +\fIlibcurl\-errors(3)\fP +.SH SEE ALSO +.BR curl_multi_fdset (3), +.BR curl_multi_perform (3), +.BR curl_multi_poll (3), +.BR curl_multi_wait (3) diff --git a/3rdparty/curl/share/man/man3/curl_multi_wakeup.3 b/3rdparty/curl/share/man/man3/curl_multi_wakeup.3 new file mode 100644 index 0000000..180dc2b --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_multi_wakeup.3 @@ -0,0 +1,76 @@ +.\" generated by cd2nroff 0.1 from curl_multi_wakeup.md +.TH curl_multi_wakeup 3 "2024-10-11" libcurl +.SH NAME +curl_multi_wakeup \- wake up a sleeping curl_multi_poll call +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_wakeup(CURLM *multi_handle); +.fi +.SH DESCRIPTION +This function can be called from any thread and it wakes up a sleeping +\fIcurl_multi_poll(3)\fP call that is currently (or is about to be) waiting +for activity or a timeout. + +If the function is called when there is no \fIcurl_multi_poll(3)\fP call, it +causes the next call to return immediately. + +Calling this function only guarantees to wake up the current (or the next if +there is no current) \fIcurl_multi_poll(3)\fP call, which means it is possible +that multiple calls to this function wake up the same waiting operation. + +This function has no effect on \fIcurl_multi_wait(3)\fP calls. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +extern int time_to_die(void); +extern int set_something_to_signal_thread_1_to_exit(void); +extern int decide_to_stop_thread1(); + +int main(void) +{ + CURL *easy; + CURLM *multi; + int still_running; + + /* add the individual easy handle */ + curl_multi_add_handle(multi, easy); + + /* this is thread 1 */ + do { + CURLMcode mc; + int numfds; + + mc = curl_multi_perform(multi, &still_running); + + if(mc == CURLM_OK) { + /* wait for activity, timeout or wakeup */ + mc = curl_multi_poll(multi, NULL, 0, 10000, &numfds); + } + + if(time_to_die()) + return 1; + + } while(still_running); + + curl_multi_remove_handle(multi, easy); + + /* this is thread 2 */ + + if(decide_to_stop_thread1()) { + + set_something_to_signal_thread_1_to_exit(); + + curl_multi_wakeup(multi); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.68.0 +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH SEE ALSO +.BR curl_multi_poll (3), +.BR curl_multi_wait (3) diff --git a/3rdparty/curl/share/man/man3/curl_pushheader_byname.3 b/3rdparty/curl/share/man/man3/curl_pushheader_byname.3 new file mode 100644 index 0000000..4a0ad45 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_pushheader_byname.3 @@ -0,0 +1,67 @@ +.\" generated by cd2nroff 0.1 from curl_pushheader_byname.md +.TH curl_pushheader_byname 3 "2024-10-11" libcurl +.SH NAME +curl_pushheader_byname \- get a push header by name +.SH SYNOPSIS +.nf +#include + +char *curl_pushheader_byname(struct curl_pushheaders *h, const char *name); +.fi +.SH DESCRIPTION +This is a function that is only functional within a +\fICURLMOPT_PUSHFUNCTION(3)\fP callback. It makes no sense to try to use it +elsewhere and it has no function then. + +It returns the value for the given header field name (or NULL) for the +incoming server push request. This is a shortcut so that the application does +not have to loop through all headers to find the one it is interested in. The +data this function points to is freed when this callback returns. If more than +one header field use the same name, this returns only the first one. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +#include /* for strncmp */ + +static int push_cb(CURL *parent, + CURL *easy, + size_t num_headers, + struct curl_pushheaders *headers, + void *clientp) +{ + char *headp; + int *transfers = (int *)clientp; + FILE *out; + headp = curl_pushheader_byname(headers, ":path"); + if(headp && !strncmp(headp, "/push-", 6)) { + fprintf(stderr, "The PATH is %s\\n", headp); + + /* save the push here */ + out = fopen("pushed-stream", "wb"); + + /* write to this file */ + curl_easy_setopt(easy, CURLOPT_WRITEDATA, out); + + (*transfers)++; /* one more */ + + return CURL_PUSH_OK; + } + return CURL_PUSH_DENY; +} + +int main(void) +{ + int counter; + CURLM *multi = curl_multi_init(); + curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_cb); + curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter); +} +.fi +.SH AVAILABILITY +Added in curl 7.44.0 +.SH RETURN VALUE +Returns a pointer to the header field content or NULL. +.SH SEE ALSO +.BR CURLMOPT_PUSHFUNCTION (3), +.BR curl_pushheader_bynum (3) diff --git a/3rdparty/curl/share/man/man3/curl_pushheader_bynum.3 b/3rdparty/curl/share/man/man3/curl_pushheader_bynum.3 new file mode 100644 index 0000000..1117680 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_pushheader_bynum.3 @@ -0,0 +1,54 @@ +.\" generated by cd2nroff 0.1 from curl_pushheader_bynum.md +.TH curl_pushheader_bynum 3 "2024-10-11" libcurl +.SH NAME +curl_pushheader_bynum \- get a push header by index +.SH SYNOPSIS +.nf +#include + +char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num); +.fi +.SH DESCRIPTION +This is a function that is only functional within a +\fICURLMOPT_PUSHFUNCTION(3)\fP callback. It makes no sense to try to use it +elsewhere and it has no function then. + +It returns the value for the header field at the given index \fBnum\fP, for +the incoming server push request or NULL. The data pointed to is freed by +libcurl when this callback returns. The returned pointer points to a +\&"name:value" string that gets freed when this callback returns. +.SH PROTOCOLS +This functionality affects http only +.SH EXAMPLE +.nf +/* output all the incoming push request headers */ +static int push_cb(CURL *parent, + CURL *easy, + size_t num_headers, + struct curl_pushheaders *headers, + void *clientp) +{ + int i = 0; + char *field; + do { + field = curl_pushheader_bynum(headers, i); + if(field) + fprintf(stderr, "Push header: %s\\n", field); + i++; + } while(field); + return CURL_PUSH_OK; /* permission granted */ +} + +int main(void) +{ + CURLM *multi = curl_multi_init(); + curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_cb); +} +.fi +.SH AVAILABILITY +Added in curl 7.44.0 +.SH RETURN VALUE +Returns a pointer to the header field content or NULL. +.SH SEE ALSO +.BR CURLMOPT_PUSHFUNCTION (3), +.BR curl_pushheader_byname (3) diff --git a/3rdparty/curl/share/man/man3/curl_share_cleanup.3 b/3rdparty/curl/share/man/man3/curl_share_cleanup.3 new file mode 100644 index 0000000..4a58708 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_share_cleanup.3 @@ -0,0 +1,42 @@ +.\" generated by cd2nroff 0.1 from curl_share_cleanup.md +.TH curl_share_cleanup 3 "2024-10-11" libcurl +.SH NAME +curl_share_cleanup \- close a shared object +.SH SYNOPSIS +.nf +#include + +CURLSHcode curl_share_cleanup(CURLSH *share_handle); +.fi +.SH DESCRIPTION +This function deletes a shared object. The share handle cannot be used anymore +when this function has been called. + +Passing in a NULL pointer in \fIshare_handle\fP makes this function return +immediately with no action. + +Any use of the \fBshare_handle\fP after this function has been called and have +returned, is illegal. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); + /* use the share, then ... */ + curl_share_cleanup(share); +} +.fi +.SH AVAILABILITY +Added in curl 7.10 +.SH RETURN VALUE +CURLSHE_OK (zero) means that the option was set properly, non\-zero means an +error occurred as \fI\fP defines. See the \fIlibcurl\-errors(3)\fP man +page for the full list with descriptions. If an error occurs, then the share +object is not deleted. +.SH SEE ALSO +.BR curl_share_init (3), +.BR curl_share_setopt (3) diff --git a/3rdparty/curl/share/man/man3/curl_share_init.3 b/3rdparty/curl/share/man/man3/curl_share_init.3 new file mode 100644 index 0000000..4040b29 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_share_init.3 @@ -0,0 +1,41 @@ +.\" generated by cd2nroff 0.1 from curl_share_init.md +.TH curl_share_init 3 "2024-10-11" libcurl +.SH NAME +curl_share_init \- create a share object +.SH SYNOPSIS +.nf +#include + +CURLSH *curl_share_init(); +.fi +.SH DESCRIPTION +This function returns a pointer to a \fICURLSH\fP handle to be used as input +to all the other share\-functions, sometimes referred to as a share handle in +some places in the documentation. This init call MUST have a corresponding +call to \fIcurl_share_cleanup(3)\fP when all operations using the share are +complete. + +This \fIshare handle\fP is what you pass to curl using the +\fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, to make that +specific curl handle use the data in this share. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); + if(sh) + printf("Error: %s\\n", curl_share_strerror(sh)); +} +.fi +.SH AVAILABILITY +Added in curl 7.10 +.SH RETURN VALUE +If this function returns NULL, something went wrong (out of memory, etc.) +and therefore the share object was not created. +.SH SEE ALSO +.BR curl_share_cleanup (3), +.BR curl_share_setopt (3) diff --git a/3rdparty/curl/share/man/man3/curl_share_setopt.3 b/3rdparty/curl/share/man/man3/curl_share_setopt.3 new file mode 100644 index 0000000..d7bcb22 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_share_setopt.3 @@ -0,0 +1,45 @@ +.\" generated by cd2nroff 0.1 from curl_share_setopt.md +.TH curl_share_setopt 3 "2024-10-11" libcurl +.SH NAME +curl_share_setopt \- set options for a shared object +.SH SYNOPSIS +.nf +#include + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter); +.fi +.SH DESCRIPTION +Set the \fIoption\fP to \fIparameter\fP for the given \fIshare\fP. +.SH OPTIONS +.IP CURLSHOPT_LOCKFUNC +See \fICURLSHOPT_LOCKFUNC(3)\fP. +.IP CURLSHOPT_UNLOCKFUNC +See \fICURLSHOPT_UNLOCKFUNC(3)\fP. +.IP CURLSHOPT_SHARE +See \fICURLSHOPT_SHARE(3)\fP. +.IP CURLSHOPT_UNSHARE +See \fICURLSHOPT_UNSHARE(3)\fP. +.IP CURLSHOPT_USERDATA +See \fICURLSHOPT_USERDATA(3)\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); + if(sh) + printf("Error: %s\\n", curl_share_strerror(sh)); +} +.fi +.SH AVAILABILITY +Added in curl 7.10 +.SH RETURN VALUE +CURLSHE_OK (zero) means that the option was set properly, non\-zero means an +error occurred as \fI\fP defines. See the \fIlibcurl\-errors(3)\fP man +page for the full list with descriptions. +.SH SEE ALSO +.BR curl_share_cleanup (3), +.BR curl_share_init (3) diff --git a/3rdparty/curl/share/man/man3/curl_share_strerror.3 b/3rdparty/curl/share/man/man3/curl_share_strerror.3 new file mode 100644 index 0000000..599cd47 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_share_strerror.3 @@ -0,0 +1,35 @@ +.\" generated by cd2nroff 0.1 from curl_share_strerror.md +.TH curl_share_strerror 3 "2024-10-11" libcurl +.SH NAME +curl_share_strerror \- return string describing error code +.SH SYNOPSIS +.nf +#include + +const char *curl_share_strerror(CURLSHcode errornum); +.fi +.SH DESCRIPTION +The \fIcurl_share_strerror(3)\fP function returns a string describing the +\fICURLSHcode\fP error code passed in the argument \fIerrornum\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); + if(sh) + printf("Error: %s\\n", curl_share_strerror(sh)); +} +.fi +.SH AVAILABILITY +Added in curl 7.12.0 +.SH RETURN VALUE +A pointer to a null\-terminated string. +.SH SEE ALSO +.BR curl_easy_strerror (3), +.BR curl_multi_strerror (3), +.BR curl_url_strerror (3), +.BR libcurl-errors (3) diff --git a/3rdparty/curl/share/man/man3/curl_slist_append.3 b/3rdparty/curl/share/man/man3/curl_slist_append.3 new file mode 100644 index 0000000..d659e04 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_slist_append.3 @@ -0,0 +1,60 @@ +.\" generated by cd2nroff 0.1 from curl_slist_append.md +.TH curl_slist_append 3 "2024-10-11" libcurl +.SH NAME +curl_slist_append \- add a string to an slist +.SH SYNOPSIS +.nf +#include + +struct curl_slist *curl_slist_append(struct curl_slist *list, + const char *string); +.fi +.SH DESCRIPTION +\fIcurl_slist_append(3)\fP appends a string to a linked list of strings. The +existing \fBlist\fP should be passed as the first argument and the new list is +returned from this function. Pass in NULL in the \fBlist\fP argument to create +a new list. The specified \fBstring\fP has been appended when this function +returns. \fIcurl_slist_append(3)\fP copies the string. + +The list should be freed again (after usage) with +\fIcurl_slist_free_all(3)\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *handle; + struct curl_slist *slist = NULL; + struct curl_slist *temp = NULL; + + slist = curl_slist_append(slist, "pragma:"); + + if(!slist) + return -1; + + temp = curl_slist_append(slist, "Accept:"); + + if(!temp) { + curl_slist_free_all(slist); + return -1; + } + + slist = temp; + + curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist); + + curl_easy_perform(handle); + + curl_slist_free_all(slist); /* free the list again */ +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +A null pointer is returned if anything went wrong, otherwise the new list +pointer is returned. To avoid overwriting an existing non\-empty list on +failure, the new list should be returned to a temporary variable which can +be tested for NULL before updating the original list pointer. +.SH SEE ALSO +.BR curl_slist_free_all (3) diff --git a/3rdparty/curl/share/man/man3/curl_slist_free_all.3 b/3rdparty/curl/share/man/man3/curl_slist_free_all.3 new file mode 100644 index 0000000..b29f1bd --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_slist_free_all.3 @@ -0,0 +1,46 @@ +.\" generated by cd2nroff 0.1 from curl_slist_free_all.md +.TH curl_slist_free_all 3 "2024-10-11" libcurl +.SH NAME +curl_slist_free_all \- free an entire curl_slist list +.SH SYNOPSIS +.nf +#include + +void curl_slist_free_all(struct curl_slist *list); +.fi +.SH DESCRIPTION +curl_slist_free_all() removes all traces of a previously built curl_slist +linked list. + +Passing in a NULL pointer in \fIlist\fP makes this function return immediately +with no action. + +Any use of the \fBlist\fP after this function has been called and have returned, +is illegal. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *handle; + struct curl_slist *slist = NULL; + + slist = curl_slist_append(slist, "X-libcurl: coolness"); + + if(!slist) + return -1; + + curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist); + + curl_easy_perform(handle); + + curl_slist_free_all(slist); /* free the list again */ +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Nothing. +.SH SEE ALSO +.BR curl_slist_append (3) diff --git a/3rdparty/curl/share/man/man3/curl_strequal.3 b/3rdparty/curl/share/man/man3/curl_strequal.3 new file mode 100644 index 0000000..374a6aa --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_strequal.3 @@ -0,0 +1,41 @@ +.\" generated by cd2nroff 0.1 from curl_strequal.md +.TH curl_strequal 3 "2024-10-11" libcurl +.SH NAME +curl_strequal \- compare two strings ignoring case +.SH SYNOPSIS +.nf +#include + +int curl_strequal(const char *str1, const char *str2); +.fi +.SH DESCRIPTION +The \fIcurl_strequal(3)\fP function compares the two strings \fIstr1\fP and \fIstr2\fP, +ignoring the case of the characters. It returns a non\-zero (TRUE) integer if +the strings are identical. + +This function uses plain ASCII based comparisons completely disregarding the +locale \- contrary to how \fBstrcasecmp\fP and other system case insensitive +string comparisons usually work. + +This function is provided by libcurl to enable applications to compare strings +in a truly portable manner. There are no standard portable case insensitive +string comparison functions. This function works on all platforms. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(int argc, char **argv) +{ + const char *name = "compare"; + if(curl_strequal(name, argv[1])) + printf("Name and input matches\\n"); +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Non\-zero if the strings are identical. Zero if they are not. +.SH SEE ALSO +.BR curl_strnequal (3), +.BR strcasecmp (3), +.BR strcmp (3) diff --git a/3rdparty/curl/share/man/man3/curl_strnequal.3 b/3rdparty/curl/share/man/man3/curl_strnequal.3 new file mode 100644 index 0000000..c3da90b --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_strnequal.3 @@ -0,0 +1,44 @@ +.\" generated by cd2nroff 0.1 from curl_strnequal.md +.TH curl_strnequal 3 "2024-10-11" libcurl +.SH NAME +curl_strnequal \- compare two strings ignoring case +.SH SYNOPSIS +.nf +#include + +int curl_strnequal(const char *str1, const char *str2, size_t length); +.fi +.SH DESCRIPTION +The \fIcurl_strnequal(3)\fP function compares the two strings \fIstr1\fP and \fIstr2\fP, +ignoring the case of the characters. It returns a non\-zero (TRUE) integer if +the strings are identical. + +This function compares no more than the first \fIlength\fP bytes of \fIstr1\fP and +\fIstr2\fP. + +This function uses plain ASCII based comparisons completely disregarding the +locale \- contrary to how \fBstrcasecmp\fP and other system case insensitive +string comparisons usually work. + +This function is provided by libcurl to enable applications to compare strings +in a truly portable manner. There are no standard portable case insensitive +string comparison functions. This function works on all platforms. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(int argc, char **argv) +{ + const char *name = "compare"; + if(curl_strnequal(name, argv[1], 5)) + printf("Name and input matches in the 5 first bytes\\n"); +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +Non\-zero if the strings are identical. Zero if they are not. +.SH SEE ALSO +.BR curl_strequal (3), +.BR strcasecmp (3), +.BR strcmp (3) diff --git a/3rdparty/curl/share/man/man3/curl_unescape.3 b/3rdparty/curl/share/man/man3/curl_unescape.3 new file mode 100644 index 0000000..0548b7f --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_unescape.3 @@ -0,0 +1,52 @@ +.\" generated by cd2nroff 0.1 from curl_unescape.md +.TH curl_unescape 3 "2024-10-11" libcurl +.SH NAME +curl_unescape \- URL decode a string +.SH SYNOPSIS +.nf +#include + +char *curl_unescape(const char *input, int length); +.fi +.SH DESCRIPTION +Deprecated. Use \fIcurl_easy_unescape(3)\fP instead. + +This function converts the URL encoded string \fBinput\fP to a "plain string" +and return that as a new allocated string. All input characters that are URL +encoded (%XX where XX is a two\-digit hexadecimal number) are converted to +their plain text versions. + +If the \fBlength\fP argument is set to 0, \fIcurl_unescape(3)\fP calls +strlen() on \fBinput\fP to find out the size. + +You must \fIcurl_free(3)\fP the returned string when you are done with it. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + char *decoded = curl_unescape("%63%75%72%6c", 12); + if(decoded) { + /* do not assume printf() works on the decoded data */ + printf("Decoded: "); + /* ... */ + curl_free(decoded); + } + } +} +.fi +.SH DEPRECATED +Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function might +be removed in a future release. +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +A pointer to a null\-terminated string or NULL if it failed. +.SH SEE ALSO +.BR RFC 2396, +.BR curl_easy_escape (3), +.BR curl_easy_unescape (3), +.BR curl_free (3) diff --git a/3rdparty/curl/share/man/man3/curl_url.3 b/3rdparty/curl/share/man/man3/curl_url.3 new file mode 100644 index 0000000..bf6319d --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_url.3 @@ -0,0 +1,49 @@ +.\" generated by cd2nroff 0.1 from curl_url.md +.TH curl_url 3 "2024-10-11" libcurl +.SH NAME +curl_url \- create a URL handle +.SH SYNOPSIS +.nf +#include + +CURLU *curl_url(); +.fi +.SH DESCRIPTION +This function allocates a URL object and returns a \fICURLU\fP handle for it, +to be used as input to all other URL API functions. + +This is a handle to a URL object that holds or can hold URL components for a +single URL. When the object is first created, there is of course no components +stored. They are then set in the object with the \fIcurl_url_set(3)\fP +function. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLUcode rc; + CURLU *url = curl_url(); + rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + if(!rc) { + char *scheme; + rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0); + if(!rc) { + printf("the scheme is %s\\n", scheme); + curl_free(scheme); + } + curl_url_cleanup(url); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.62.0 +.SH RETURN VALUE +Returns a \fBCURLU \fP* if successful, or NULL if out of memory. +.SH SEE ALSO +.BR CURLOPT_CURLU (3), +.BR curl_url_cleanup (3), +.BR curl_url_dup (3), +.BR curl_url_get (3), +.BR curl_url_set (3), +.BR curl_url_strerror (3) diff --git a/3rdparty/curl/share/man/man3/curl_url_cleanup.3 b/3rdparty/curl/share/man/man3/curl_url_cleanup.3 new file mode 100644 index 0000000..4cb300b --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_url_cleanup.3 @@ -0,0 +1,39 @@ +.\" generated by cd2nroff 0.1 from curl_url_cleanup.md +.TH curl_url_cleanup 3 "2024-10-11" libcurl +.SH NAME +curl_url_cleanup \- free the URL handle +.SH SYNOPSIS +.nf +#include + +void curl_url_cleanup(CURLU *handle); +.fi +.SH DESCRIPTION +Frees all the resources associated with the given \fICURLU\fP handle! + +Passing in a NULL pointer in \fIhandle\fP makes this function return +immediately with no action. + +Any use of the \fBhandle\fP after this function has been called and have +returned, is illegal. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLU *url = curl_url(); + curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + curl_url_cleanup(url); +} +.fi +.SH AVAILABILITY +Added in curl 7.62.0 +.SH RETURN VALUE +none +.SH SEE ALSO +.BR CURLOPT_CURLU (3), +.BR curl_url (3), +.BR curl_url_dup (3), +.BR curl_url_get (3), +.BR curl_url_set (3) diff --git a/3rdparty/curl/share/man/man3/curl_url_dup.3 b/3rdparty/curl/share/man/man3/curl_url_dup.3 new file mode 100644 index 0000000..5a72f9b --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_url_dup.3 @@ -0,0 +1,41 @@ +.\" generated by cd2nroff 0.1 from curl_url_dup.md +.TH curl_url_dup 3 "2024-10-11" libcurl +.SH NAME +curl_url_dup \- duplicate a URL handle +.SH SYNOPSIS +.nf +#include + +CURLU *curl_url_dup(const CURLU *inhandle); +.fi +.SH DESCRIPTION +Duplicates the URL object the input \fICURLU\fP \fIinhandle\fP identifies and +returns a pointer to the copy as a new \fICURLU\fP handle. The new handle also +needs to be freed with \fIcurl_url_cleanup(3)\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLUcode rc; + CURLU *url = curl_url(); + CURLU *url2; + rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + if(!rc) { + url2 = curl_url_dup(url); /* clone it! */ + curl_url_cleanup(url2); + } + curl_url_cleanup(url); +} +.fi +.SH AVAILABILITY +Added in curl 7.62.0 +.SH RETURN VALUE +Returns a new handle or NULL if out of memory. +.SH SEE ALSO +.BR CURLOPT_CURLU (3), +.BR curl_url (3), +.BR curl_url_cleanup (3), +.BR curl_url_get (3), +.BR curl_url_set (3) diff --git a/3rdparty/curl/share/man/man3/curl_url_get.3 b/3rdparty/curl/share/man/man3/curl_url_get.3 new file mode 100644 index 0000000..d04b887 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_url_get.3 @@ -0,0 +1,190 @@ +.\" generated by cd2nroff 0.1 from curl_url_get.md +.TH curl_url_get 3 "2024-10-11" libcurl +.SH NAME +curl_url_get \- extract a part from a URL +.SH SYNOPSIS +.nf +#include + +CURLUcode curl_url_get(const CURLU *url, + CURLUPart part, + char **content, + unsigned int flags); +.fi +.SH DESCRIPTION +Given a \fIurl\fP handle of a URL object, this function extracts an individual +piece or the full URL from it. + +The \fIpart\fP argument specifies which part to extract (see list below) and +\fIcontent\fP points to a \(aqchar *\(aq to get updated to point to a newly +allocated string with the contents. + +The \fIflags\fP argument is a bitmask with individual features. + +The returned content pointer must be freed with \fIcurl_free(3)\fP after use. +.SH FLAGS +The flags argument is zero, one or more bits set in a bitmask. +.IP CURLU_DEFAULT_PORT +If the handle has no port stored, this option makes \fIcurl_url_get(3)\fP +return the default port for the used scheme. +.IP CURLU_DEFAULT_SCHEME +If the handle has no scheme stored, this option makes \fIcurl_url_get(3)\fP +return the default scheme instead of error. +.IP CURLU_NO_DEFAULT_PORT +Instructs \fIcurl_url_get(3)\fP to not return a port number if it matches the +default port for the scheme. +.IP CURLU_URLDECODE +Asks \fIcurl_url_get(3)\fP to URL decode the contents before returning it. It +does not decode the scheme, the port number or the full URL. + +The query component also gets plus\-to\-space conversion as a bonus when this +bit is set. + +Note that this URL decoding is charset unaware and you get a zero terminated +string back with data that could be intended for a particular encoding. + +If there are byte values lower than 32 in the decoded string, the get +operation returns an error instead. +.IP CURLU_URLENCODE +If set, \fIcurl_url_get(3)\fP URL encodes the hostname part when a full URL is +retrieved. If not set (default), libcurl returns the URL with the hostname raw +to support IDN names to appear as\-is. IDN hostnames are typically using +non\-ASCII bytes that otherwise gets percent\-encoded. + +Note that even when not asking for URL encoding, the \(aq%\(aq (byte 37) is URL +encoded to make sure the hostname remains valid. +.IP CURLU_PUNYCODE +If set and \fICURLU_URLENCODE\fP is not set, and asked to retrieve the +\fBCURLUPART_HOST\fP or \fBCURLUPART_URL\fP parts, libcurl returns the host +name in its punycode version if it contains any non\-ASCII octets (and is an +IDN name). + +If libcurl is built without IDN capabilities, using this bit makes +\fIcurl_url_get(3)\fP return \fICURLUE_LACKS_IDN\fP if the hostname contains +anything outside the ASCII range. + +(Added in curl 7.88.0) +.IP CURLU_PUNY2IDN +If set and asked to retrieve the \fBCURLUPART_HOST\fP or \fBCURLUPART_URL\fP +parts, libcurl returns the hostname in its IDN (International Domain Name) +UTF\-8 version if it otherwise is a punycode version. If the punycode name +cannot be converted to IDN correctly, libcurl returns +\fICURLUE_BAD_HOSTNAME\fP. + +If libcurl is built without IDN capabilities, using this bit makes +\fIcurl_url_get(3)\fP return \fICURLUE_LACKS_IDN\fP if the hostname is using +punycode. + +(Added in curl 8.3.0) +.IP CURLU_GET_EMPTY +When this flag is used in curl_url_get(), it makes the function return empty +query and fragments parts or when used in the full URL. By default, libcurl +otherwise considers empty parts non\-existing. + +An empty query part is one where this is nothing following the question mark +(before the possible fragment). An empty fragments part is one where there is +nothing following the hash sign. + +(Added in curl 8.8.0) +.IP CURLU_NO_GUESS_SCHEME +When this flag is used in curl_url_get(), it treats the scheme as non\-existing +if it was set as a result of a previous guess; when CURLU_GUESS_SCHEME was +used parsing a URL. + +Using this flag when getting CURLUPART_SCHEME if the scheme was set as the +result of a guess makes curl_url_get() return CURLUE_NO_SCHEME. + +Using this flag when getting CURLUPART_URL if the scheme was set as the result +of a guess makes curl_url_get() return the full URL without the scheme +component. Such a URL can then only be parsed with curl_url_set() if +CURLU_GUESS_SCHEME is used. + +(Added in curl 8.9.0) +.SH PARTS +.IP CURLUPART_URL +When asked to return the full URL, \fIcurl_url_get(3)\fP returns a normalized and +possibly cleaned up version using all available URL parts. + +We advise using the \fICURLU_PUNYCODE\fP option to get the URL as "normalized" as +possible since IDN allows hostnames to be written in many different ways that +still end up the same punycode version. + +Zero\-length queries and fragments are excluded from the URL unless +CURLU_GET_EMPTY is set. +.IP CURLUPART_SCHEME +Scheme cannot be URL decoded on get. +.IP CURLUPART_USER +.IP CURLUPART_PASSWORD +.IP CURLUPART_OPTIONS +The options field is an optional field that might follow the password in the +userinfo part. It is only recognized/used when parsing URLs for the following +schemes: pop3, smtp and imap. The URL API still allows users to set and get +this field independently of scheme when not parsing full URLs. +.IP CURLUPART_HOST +The hostname. If it is an IPv6 numeric address, the zone id is not part of it +but is provided separately in \fICURLUPART_ZONEID\fP. IPv6 numerical addresses +are returned within brackets ([]). + +IPv6 names are normalized when set, which should make them as short as +possible while maintaining correct syntax. +.IP CURLUPART_ZONEID +If the hostname is a numeric IPv6 address, this field might also be set. +.IP CURLUPART_PORT +A port cannot be URL decoded on get. This number is returned in a string just +like all other parts. That string is guaranteed to hold a valid port number in +ASCII using base 10. +.IP CURLUPART_PATH +The \fIpart\fP is always at least a slash (\(aq/\(aq) even if no path was supplied +in the URL. A URL path always starts with a slash. +.IP CURLUPART_QUERY +The initial question mark that denotes the beginning of the query part is a +delimiter only. It is not part of the query contents. + +A not\-present query returns \fIpart\fP set to NULL. + +A zero\-length query returns \fIpart\fP as NULL unless CURLU_GET_EMPTY is set. + +The query part gets pluses converted to space when asked to URL decode on get +with the CURLU_URLDECODE bit. +.IP CURLUPART_FRAGMENT +The initial hash sign that denotes the beginning of the fragment is a +delimiter only. It is not part of the fragment contents. + +A not\-present fragment returns \fIpart\fP set to NULL. + +A zero\-length fragment returns \fIpart\fP as NULL unless CURLU_GET_EMPTY is set. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLUcode rc; + CURLU *url = curl_url(); + rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + if(!rc) { + char *scheme; + rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0); + if(!rc) { + printf("the scheme is %s\\n", scheme); + curl_free(scheme); + } + curl_url_cleanup(url); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.62.0 +.SH RETURN VALUE +Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went +fine. See the \fIlibcurl\-errors(3)\fP man page for the full list with +descriptions. + +If this function returns an error, no URL part is returned. +.SH SEE ALSO +.BR CURLOPT_CURLU (3), +.BR curl_url (3), +.BR curl_url_cleanup (3), +.BR curl_url_dup (3), +.BR curl_url_set (3), +.BR curl_url_strerror (3) diff --git a/3rdparty/curl/share/man/man3/curl_url_set.3 b/3rdparty/curl/share/man/man3/curl_url_set.3 new file mode 100644 index 0000000..545dc00 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_url_set.3 @@ -0,0 +1,213 @@ +.\" generated by cd2nroff 0.1 from curl_url_set.md +.TH curl_url_set 3 "2024-10-11" libcurl +.SH NAME +curl_url_set \- set a URL part +.SH SYNOPSIS +.nf +#include + +CURLUcode curl_url_set(CURLU *url, + CURLUPart part, + const char *content, + unsigned int flags); +.fi +.SH DESCRIPTION +The \fIurl\fP handle to work on, passed in as the first argument, must be a +handle previously created by \fIcurl_url(3)\fP or \fIcurl_url_dup(3)\fP. + +This function sets or updates individual URL components, or parts, held by the +URL object the handle identifies. + +The \fIpart\fP argument should identify the particular URL part (see list below) +to set or change, with \fIcontent\fP pointing to a null\-terminated string with the +new contents for that URL part. The contents should be in the form and +encoding they would use in a URL: URL encoded. + +When setting a part in the URL object that was previously already set, it +replaces the data that was previously stored for that part with the new +\fIcontent\fP. + +The caller does not have to keep \fIcontent\fP around after a successful call +as this function copies the content. + +Setting a part to a NULL pointer removes that part\(aqs contents from the \fICURLU\fP +handle. + +This function has an 8 MB maximum length limit for all provided input strings. +In the real world, excessively long fields in URLs cause problems even if this +function accepts them. + +When setting or updating contents of individual URL parts, \fIcurl_url_set(3)\fP +might accept data that would not be otherwise possible to set in the string +when it gets populated as a result of a full URL parse. Beware. If done so, +extracting a full URL later on from such components might render an invalid +URL. + +The \fIflags\fP argument is a bitmask with independent features. +.SH PARTS +.IP CURLUPART_URL +Allows the full URL of the handle to be replaced. If the handle already is +populated with a URL, the new URL can be relative to the previous. + +When successfully setting a new URL, relative or absolute, the handle contents +is replaced with the components of the newly set URL. + +Pass a pointer to a null\-terminated string to the \fIurl\fP parameter. The string +must point to a correctly formatted "RFC 3986+" URL or be a NULL pointer. The +URL parser only understands and parses the subset of URLS that are +\&"hierarchical" and therefore contain a :// separator \- not the ones that are +normally specified with only a colon separator. + +By default this API only parses URLs using schemes for protocols that are +supported built\-in. To make libcurl parse URLs generically even for schemes it +does not know about, the \fBCURLU_NON_SUPPORT_SCHEME\fP flags bit must be set. +Otherwise, this function returns \fICURLUE_UNSUPPORTED_SCHEME\fP for URL schemes +it does not recognize. + +Unless \fICURLU_NO_AUTHORITY\fP is set, a blank hostname is not allowed in +the URL. + +When a full URL is set (parsed), the hostname component is stored URL decoded. +.IP CURLUPART_SCHEME +Scheme cannot be URL decoded on set. libcurl only accepts setting schemes up +to 40 bytes long. +.IP CURLUPART_USER +If only the user part is set and not the password, the URL is represented with +a blank password. +.IP CURLUPART_PASSWORD +If only the password part is set and not the user, the URL is represented with +a blank user. +.IP CURLUPART_OPTIONS +The options field is an optional field that might follow the password in the +userinfo part. It is only recognized/used when parsing URLs for the following +schemes: pop3, smtp and imap. This function however allows users to +independently set this field. +.IP CURLUPART_HOST +The hostname. If it is International Domain Name (IDN) the string must then be +encoded as your locale says or UTF\-8 (when WinIDN is used). If it is a +bracketed IPv6 numeric address it may contain a zone id (or you can use +\fICURLUPART_ZONEID\fP). + +Note that if you set an IPv6 address, it gets ruined and causes an error if +you also set the CURLU_URLENCODE flag. + +Unless \fICURLU_NO_AUTHORITY\fP is set, a blank hostname is not allowed to set. +.IP CURLUPART_ZONEID +If the hostname is a numeric IPv6 address, this field can also be set. +.IP CURLUPART_PORT +The port number cannot be URL encoded on set. The given port number is +provided as a string and the decimal number in it must be between 0 and +65535. Anything else returns an error. +.IP CURLUPART_PATH +If a path is set in the URL without a leading slash, a slash is prepended +automatically. +.IP CURLUPART_QUERY +The query part gets spaces converted to pluses when asked to URL encode on set +with the \fICURLU_URLENCODE\fP bit. + +If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part is +appended on the end of the existing query. + +The question mark in the URL is not part of the actual query contents. +.IP CURLUPART_FRAGMENT +The hash sign in the URL is not part of the actual fragment contents. +.SH FLAGS +The flags argument is zero, one or more bits set in a bitmask. +.IP CURLU_APPENDQUERY +Can be used when setting the \fICURLUPART_QUERY\fP component. The provided new +part is then appended at the end of the existing query \- and if the previous +part did not end with an ampersand (&), an ampersand gets inserted before the +new appended part. + +When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the +first \(aq=\(aq symbol is not URL encoded. +.IP CURLU_NON_SUPPORT_SCHEME +If set, allows \fIcurl_url_set(3)\fP to set a non\-supported scheme. It then of +course cannot know if the provided scheme is a valid one or not. +.IP CURLU_URLENCODE +When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for +\fBscheme\fP, \fBport\fP and \fBURL\fP. + +When setting the path component with URL encoding enabled, the slash character +is skipped. + +The query part gets space\-to\-plus converted before the URL conversion is +applied. + +This URL encoding is charset unaware and converts the input in a byte\-by\-byte +manner. +.IP CURLU_DEFAULT_SCHEME +If set, allows the URL to be set without a scheme and then sets that to the +default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP option if both are +set. +.IP CURLU_GUESS_SCHEME +If set, allows the URL to be set without a scheme and it instead "guesses" +which scheme that was intended based on the hostname. If the outermost +subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme is +used, otherwise it picks HTTP. Conflicts with the \fICURLU_DEFAULT_SCHEME\fP +option which takes precedence if both are set. + +If guessing is not allowed and there is no default scheme set, trying to parse +a URL without a scheme returns error. + +If the scheme ends up set as a result of guessing, i.e. it is not actually +present in the parsed URL, it can later be figured out by using the +\fBCURLU_NO_GUESS_SCHEME\fP flag when subsequently getting the URL or the scheme +with \fIcurl_url_get(3)\fP. +.IP CURLU_NO_AUTHORITY +If set, skips authority checks. The RFC allows individual schemes to omit the +host part (normally the only mandatory part of the authority), but libcurl +cannot know whether this is permitted for custom schemes. Specifying the flag +permits empty authority sections, similar to how file scheme is handled. +.IP CURLU_PATH_AS_IS +When set for \fBCURLUPART_URL\fP, this skips the normalization of the +path. That is the procedure where libcurl otherwise removes sequences of +dot\-slash and dot\-dot etc. The same option used for transfers is called +\fICURLOPT_PATH_AS_IS(3)\fP. +.IP CURLU_ALLOW_SPACE +If set, the URL parser allows space (ASCII 32) where possible. The URL syntax +does normally not allow spaces anywhere, but they should be encoded as %20 +or \(aq+\(aq. When spaces are allowed, they are still not allowed in the scheme. +When space is used and allowed in a URL, it is stored as\-is unless +\fICURLU_URLENCODE\fP is also set, which then makes libcurl URL encode the +space before stored. This affects how the URL is constructed when +\fIcurl_url_get(3)\fP is subsequently used to extract the full URL or +individual parts. (Added in 7.78.0) +.IP CURLU_DISALLOW_USER +If set, the URL parser does not accept embedded credentials for the +\fBCURLUPART_URL\fP, and instead returns \fBCURLUE_USER_NOT_ALLOWED\fP for +such URLs. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLUcode rc; + CURLU *url = curl_url(); + rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + if(!rc) { + /* change it to an FTP URL */ + rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0); + } + curl_url_cleanup(url); +} +.fi +.SH AVAILABILITY +Added in curl 7.78.0 +.SH RETURN VALUE +Returns a \fICURLUcode\fP error value, which is CURLUE_OK (0) if everything +went fine. See the \fIlibcurl\-errors(3)\fP man page for the full list with +descriptions. + +The input string passed to \fIcurl_url_set(3)\fP must be shorter than eight +million bytes. Otherwise this function returns \fBCURLUE_MALFORMED_INPUT\fP. + +If this function returns an error, no URL part is set. +.SH SEE ALSO +.BR CURLOPT_CURLU (3), +.BR curl_url (3), +.BR curl_url_cleanup (3), +.BR curl_url_dup (3), +.BR curl_url_get (3), +.BR curl_url_strerror (3) diff --git a/3rdparty/curl/share/man/man3/curl_url_strerror.3 b/3rdparty/curl/share/man/man3/curl_url_strerror.3 new file mode 100644 index 0000000..e804e4a --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_url_strerror.3 @@ -0,0 +1,38 @@ +.\" generated by cd2nroff 0.1 from curl_url_strerror.md +.TH curl_url_strerror 3 "2024-10-11" libcurl +.SH NAME +curl_url_strerror \- return string describing error code +.SH SYNOPSIS +.nf +#include + +const char *curl_url_strerror(CURLUcode errornum); +.fi +.SH DESCRIPTION +This function returns a string describing the CURLUcode error code passed in +the argument \fIerrornum\fP. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + CURLUcode rc; + CURLU *url = curl_url(); + rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + if(rc) + printf("URL error: %s\\n", curl_url_strerror(rc)); + curl_url_cleanup(url); +} +.fi +.SH AVAILABILITY +Added in curl 7.80.0 +.SH RETURN VALUE +A pointer to a null\-terminated string. +.SH SEE ALSO +.BR curl_easy_strerror (3), +.BR curl_multi_strerror (3), +.BR curl_share_strerror (3), +.BR curl_url_get (3), +.BR curl_url_set (3), +.BR libcurl-errors (3) diff --git a/3rdparty/curl/share/man/man3/curl_version.3 b/3rdparty/curl/share/man/man3/curl_version.3 new file mode 100644 index 0000000..24239d3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_version.3 @@ -0,0 +1,31 @@ +.\" generated by cd2nroff 0.1 from curl_version.md +.TH curl_version 3 "2024-10-11" libcurl +.SH NAME +curl_version \- returns the libcurl version string +.SH SYNOPSIS +.nf +#include + +char *curl_version(); +.fi +.SH DESCRIPTION +Returns a human readable string with the version number of libcurl and some of +its important components (like OpenSSL version). + +We recommend using \fIcurl_version_info(3)\fP instead! +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + printf("libcurl version %s\\n", curl_version()); +} +.fi +.SH AVAILABILITY +Added in curl 7.1 +.SH RETURN VALUE +A pointer to a null\-terminated string. The string resides in a statically +allocated buffer and must not be freed by the caller. +.SH SEE ALSO +.BR curl_version_info (3) diff --git a/3rdparty/curl/share/man/man3/curl_version_info.3 b/3rdparty/curl/share/man/man3/curl_version_info.3 new file mode 100644 index 0000000..bc0ae81 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_version_info.3 @@ -0,0 +1,309 @@ +.\" generated by cd2nroff 0.1 from curl_version_info.md +.TH curl_version_info 3 "2024-10-11" libcurl +.SH NAME +curl_version_info \- returns runtime libcurl version info +.SH SYNOPSIS +.nf +#include + +curl_version_info_data *curl_version_info(CURLversion age); +.fi +.SH DESCRIPTION +Returns a pointer to a filled in static struct with information about various +features in the running version of libcurl. \fIage\fP should be set to the +version of this functionality by the time you write your program. This way, +libcurl always returns a proper struct that your program understands, while +programs in the future might get a different struct. \fBCURLVERSION_NOW\fP is +the most recent one for the library you have installed: +.nf + data = curl_version_info(CURLVERSION_NOW); +.fi +Applications should use this information to judge if things are possible to do +or not, instead of using compile\-time checks, as dynamic/DLL libraries can be +changed independent of applications. + +This function can alter the returned static data as long as +\fIcurl_global_init(3)\fP has not been called. It is therefore not thread\-safe +before libcurl initialization occurs. + +The curl_version_info_data struct looks like this + +.nf +typedef struct { + CURLversion age; /* see description below */ + + const char *version; /* human readable string */ + unsigned int version_num; /* numeric representation */ + const char *host; /* human readable string */ + int features; /* bitmask, see below */ + char *ssl_version; /* human readable string */ + long ssl_version_num; /* not used, always zero */ + const char *libz_version; /* human readable string */ + const char *const *protocols; /* protocols */ + + /* when 'age' is CURLVERSION_SECOND or higher, the members below exist */ + const char *ares; /* human readable string */ + int ares_num; /* number */ + + /* when 'age' is CURLVERSION_THIRD or higher, the members below exist */ + const char *libidn; /* human readable string */ + + /* when 'age' is CURLVERSION_FOURTH or higher (>= 7.16.1), the members + below exist */ + int iconv_ver_num; /* '_libiconv_version' if iconv support enabled */ + + const char *libssh_version; /* human readable string */ + + /* when 'age' is CURLVERSION_FIFTH or higher (>= 7.57.0), the members + below exist */ + unsigned int brotli_ver_num; /* Numeric Brotli version + (MAJOR << 24) | (MINOR << 12) | PATCH */ + const char *brotli_version; /* human readable string. */ + + /* when 'age' is CURLVERSION_SIXTH or higher (>= 7.66.0), the members + below exist */ + unsigned int nghttp2_ver_num; /* Numeric nghttp2 version + (MAJOR << 16) | (MINOR << 8) | PATCH */ + const char *nghttp2_version; /* human readable string. */ + + const char *quic_version; /* human readable quic (+ HTTP/3) library + + version or NULL */ + + /* when 'age' is CURLVERSION_SEVENTH or higher (>= 7.70.0), the members + below exist */ + const char *cainfo; /* the built-in default CURLOPT_CAINFO, might + be NULL */ + const char *capath; /* the built-in default CURLOPT_CAPATH, might + be NULL */ + /* when 'age' is CURLVERSION_EIGHTH or higher (>= 7.71.0), the members + below exist */ + unsigned int zstd_ver_num; /* Numeric Zstd version + (MAJOR << 24) | (MINOR << 12) | PATCH */ + const char *zstd_version; /* human readable string. */ + /* when 'age' is CURLVERSION_NINTH or higher (>= 7.75.0), the members + below exist */ + const char *hyper_version; /* human readable string. */ + /* when 'age' is CURLVERSION_TENTH or higher (>= 7.77.0), the members + below exist */ + const char *gsasl_version; /* human readable string. */ + /* when 'age' is CURLVERSION_ELEVENTH or higher (>= 7.87.0), the members + below exist */ + const char *const *feature_names; /* Feature names. */ + /* when 'age' is CURLVERSION_TWELFTH or higher (>= 8.8.0), the members + below exist */ + const char *const *rtmp_version; /* human readable string */ +} curl_version_info_data; +.fi + +\fIage\fP describes what the age of this struct is. The number depends on how +new the libcurl you are using is. You are however guaranteed to get a struct +that you have a matching struct for in the header, as you tell libcurl your +\&"age" with the input argument. + +\fIversion\fP is just an ASCII string for the libcurl version. + +\fIversion_num\fP is a 24 bit number created like this: <8 bits major number> | +<8 bits minor number> | <8 bits patch number>. Version 7.9.8 is therefore +returned as 0x070908. + +\fIhost\fP is an ASCII string showing what host information that this libcurl +was built for. As discovered by a configure script or set by the build +environment. + +\fIfeatures\fP is a bit mask representing available features. It can have none, +one or more bits set. The use of this field is deprecated: use +\fIfeature_names\fP instead. The feature names description below lists the +associated bits. + +\fIfeature_names\fP is a pointer to an array of string pointers, containing the +names of the features that libcurl supports. The array is terminated by a NULL +entry. See the list of features names below. + +\fIssl_version\fP is an ASCII string for the TLS library name + version used. If +libcurl has no SSL support, this is NULL. For example "Schannel", "Secure +Transport" or "OpenSSL/1.1.0g". + +\fIssl_version_num\fP is always 0. + +\fIlibz_version\fP is an ASCII string (there is no numerical version). If +libcurl has no libz support, this is NULL. + +\fIprotocols\fP is a pointer to an array of char * pointers, containing the +names protocols that libcurl supports (using lowercase letters). The protocol +names are the same as would be used in URLs. The array is terminated by a NULL +entry. +.SH FEATURES +.IP alt-svc +\fIfeatures\fP mask bit: CURL_VERSION_ALTSVC + +HTTP Alt\-Svc parsing and the associated options (Added in 7.64.1) +.IP AsynchDNS +\fIfeatures\fP mask bit: CURL_VERSION_ASYNCHDNS + +libcurl was built with support for asynchronous name lookups, which allows +more exact timeouts (even on Windows) and less blocking when using the multi +interface. (added in 7.10.7) +.IP brotli +\fIfeatures\fP mask bit: CURL_VERSION_BROTLI + +supports HTTP Brotli content encoding using libbrotlidec (Added in 7.57.0) +.IP Debug +\fIfeatures\fP mask bit: CURL_VERSION_DEBUG + +libcurl was built with debug capabilities (added in 7.10.6) +.IP ECH +\fIfeatures\fP mask bit: non\-existent + +libcurl was built with ECH support (experimental, added in 8.8.0) +.IP gsasl +\fIfeatures\fP mask bit: CURL_VERSION_GSASL + +libcurl was built with libgsasl and thus with some extra SCRAM\-SHA +authentication methods. (added in 7.76.0) +.IP GSS-API +\fIfeatures\fP mask bit: CURL_VERSION_GSSAPI + +libcurl was built with support for GSS\-API. This makes libcurl use provided +functions for Kerberos and SPNEGO authentication. It also allows libcurl +to use the current user credentials without the app having to pass them on. +(Added in 7.38.0) +.IP HSTS +\fIfeatures\fP mask bit: CURL_VERSION_HSTS + +libcurl was built with support for HSTS (HTTP Strict Transport Security) +(Added in 7.74.0) +.IP HTTP2 +\fIfeatures\fP mask bit: CURL_VERSION_HTTP2 + +libcurl was built with support for HTTP2. +(Added in 7.33.0) +.IP HTTP3 +\fIfeatures\fP mask bit: CURL_VERSION_HTTP3 + +HTTP/3 and QUIC support are built\-in (Added in 7.66.0) +.IP HTTPS-proxy +\fIfeatures\fP mask bit: CURL_VERSION_HTTPS_PROXY + +libcurl was built with support for HTTPS\-proxy. +(Added in 7.52.0) +.IP IDN +\fIfeatures\fP mask bit: CURL_VERSION_IDN + +libcurl was built with support for IDNA, domain names with international +letters. (Added in 7.12.0) +.IP IPv6 +\fIfeatures\fP mask bit: CURL_VERSION_IPV6 + +supports IPv6 +.IP Kerberos +\fIfeatures\fP mask bit: CURL_VERSION_KERBEROS5 + +supports Kerberos V5 authentication for FTP, IMAP, LDAP, POP3, SMTP and +SOCKSv5 proxy. (Added in 7.40.0) +.IP Largefile +\fIfeatures\fP mask bit: CURL_VERSION_LARGEFILE + +libcurl was built with support for large files. (Added in 7.11.1) +.IP libz +\fIfeatures\fP mask bit: CURL_VERSION_LIBZ + +supports HTTP deflate using libz (Added in 7.10) +.IP MultiSSL +\fIfeatures\fP mask bit: CURL_VERSION_MULTI_SSL + +libcurl was built with multiple SSL backends. For details, see +\fIcurl_global_sslset(3)\fP. +(Added in 7.56.0) +.IP NTLM +\fIfeatures\fP mask bit: CURL_VERSION_NTLM + +supports HTTP NTLM (added in 7.10.6) +.IP NTLM_WB +\fIfeatures\fP mask bit: CURL_VERSION_NTLM_WB + +libcurl was built with support for NTLM delegation to a winbind helper. +(Added in 7.22.0) This feature was removed from curl in 8.8.0. +.IP PSL +\fIfeatures\fP mask bit: CURL_VERSION_PSL + +libcurl was built with support for Mozilla\(aqs Public Suffix List. This makes +libcurl ignore cookies with a domain that is on the list. +(Added in 7.47.0) +.IP SPNEGO +\fIfeatures\fP mask bit: CURL_VERSION_SPNEGO + +libcurl was built with support for SPNEGO authentication (Simple and Protected +GSS\-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8) +.IP SSL +\fIfeatures\fP mask bit: CURL_VERSION_SSL + +supports SSL (HTTPS/FTPS) (Added in 7.10) +.IP SSPI +\fIfeatures\fP mask bit: CURL_VERSION_SSPI + +libcurl was built with support for SSPI. This is only available on Windows and +makes libcurl use Windows\-provided functions for Kerberos, NTLM, SPNEGO and +Digest authentication. It also allows libcurl to use the current user +credentials without the app having to pass them on. (Added in 7.13.2) +.IP threadsafe +\fIfeatures\fP mask bit: CURL_VERSION_THREADSAFE + +libcurl was built with thread\-safety support (Atomic or SRWLOCK) to protect +curl initialization. (Added in 7.84.0) See \fIlibcurl\-thread(3)\fP +.IP TLS-SRP +\fIfeatures\fP mask bit: CURL_VERSION_TLSAUTH_SRP + +libcurl was built with support for TLS\-SRP (in one or more of the built\-in TLS +backends). (Added in 7.21.4) +.IP TrackMemory +\fIfeatures\fP mask bit: CURL_VERSION_CURLDEBUG + +libcurl was built with memory tracking debug capabilities. This is mainly of +interest for libcurl hackers. (added in 7.19.6) +.IP Unicode +\fIfeatures\fP mask bit: CURL_VERSION_UNICODE + +libcurl was built with Unicode support on Windows. This makes non\-ASCII +characters work in filenames and options passed to libcurl. (Added in 7.72.0) +.IP UnixSockets +\fIfeatures\fP mask bit: CURL_VERSION_UNIX_SOCKETS + +libcurl was built with support for Unix domain sockets. +(Added in 7.40.0) +.IP zstd +\fIfeatures\fP mask bit: CURL_VERSION_ZSTD + +supports HTTP zstd content encoding using zstd library (Added in 7.72.0) +.IP "no name" +\fIfeatures\fP mask bit: CURL_VERSION_CONV + +libcurl was built with support for character conversions, as provided by the +CURLOPT_CONV_* callbacks. Always 0 since 7.82.0. (Added in 7.15.4, +deprecated.) +.IP "no name" +\fIfeatures\fP mask bit: CURL_VERSION_GSSNEGOTIATE + +supports HTTP GSS\-Negotiate (added in 7.10.6, deprecated in 7.38.0) +.IP "no name" +\fIfeatures\fP mask bit: CURL_VERSION_KERBEROS4 + +supports Kerberos V4 (when using FTP). Legacy bit. Deprecated since 7.33.0. +.SH PROTOCOLS +This functionality affects all supported protocols +.SH EXAMPLE +.nf +int main(void) +{ + curl_version_info_data *ver = curl_version_info(CURLVERSION_NOW); + printf("libcurl version %u.%u.%u\\n", + (ver->version_num >> 16) & 0xff, + (ver->version_num >> 8) & 0xff, + ver->version_num & 0xff); +} +.fi +.SH AVAILABILITY +Added in curl 7.10.0 +.SH RETURN VALUE +A pointer to a curl_version_info_data struct. +.SH SEE ALSO +.BR curl_version (3) diff --git a/3rdparty/curl/share/man/man3/curl_ws_meta.3 b/3rdparty/curl/share/man/man3/curl_ws_meta.3 new file mode 100644 index 0000000..bc8d699 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_ws_meta.3 @@ -0,0 +1,106 @@ +.\" generated by cd2nroff 0.1 from curl_ws_meta.md +.TH curl_ws_meta 3 "2024-10-11" libcurl +.SH NAME +curl_ws_meta \- meta data WebSocket information +.SH SYNOPSIS +.nf +#include + +const struct curl_ws_frame *curl_ws_meta(CURL *curl); +.fi +.SH DESCRIPTION +This function call is EXPERIMENTAL. + +When the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP) is invoked on +received WebSocket traffic, \fIcurl_ws_meta(3)\fP can be called from within +the callback to provide additional information about the current frame. + +This function only works from within the callback, and only when receiving +WebSocket data. + +This function requires an easy handle as input argument for libcurl to know +what transfer the question is about, but as there is no such pointer provided +to the callback by libcurl itself, applications that want to use +\fIcurl_ws_meta(3)\fP need to pass it on to the callback on its own. +.SH struct curl_ws_frame +.nf +struct curl_ws_frame { + int age; + int flags; + curl_off_t offset; + curl_off_t bytesleft; +}; +.fi +.IP age +This field specify the age of this struct. It is always zero for now. +.IP flags +This is a bitmask with individual bits set that describes the WebSocket data. +See the list below. +.IP offset +When this frame is a continuation of fragment data already delivered, this is +the offset into the final fragment where this piece belongs. +.IP bytesleft +If this is not a complete fragment, the \fIbytesleft\fP field informs about how +many additional bytes are expected to arrive before this fragment is complete. +.SH FLAGS +.IP CURLWS_TEXT +The buffer contains text data. Note that this makes a difference to WebSocket +but libcurl itself does not make any verification of the content or +precautions that you actually receive valid UTF\-8 content. +.IP CURLWS_BINARY +This is binary data. +.IP CURLWS_CONT +This is not the final fragment of the message, it implies that there is +another fragment coming as part of the same message. +.IP CURLWS_CLOSE +This transfer is now closed. +.IP CURLWS_PING +This as an incoming ping message, that expects a pong response. +.SH PROTOCOLS +This functionality affects ws only +.SH EXAMPLE +.nf + +/* we pass a pointer to this struct to the callback */ +struct customdata { + CURL *easy; + void *ptr; +}; + +static size_t writecb(unsigned char *buffer, + size_t size, size_t nitems, void *p) +{ + struct customdata *c = (struct customdata *)p; + const struct curl_ws_frame *m = curl_ws_meta(c->easy); + + printf("flags: %x\\n", m->flags); +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct customdata custom; + custom.easy = curl; + custom.ptr = NULL; + curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb); + curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom); + + curl_easy_perform(curl); + + } +} +.fi +.SH AVAILABILITY +Added in curl 7.86.0 +.SH RETURN VALUE +This function returns a pointer to a \fIcurl_ws_frame\fP struct with read\-only +information that is valid for this specific callback invocation. If it cannot +return this information, or if the function is called in the wrong context, it +returns NULL. +.SH SEE ALSO +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3), +.BR curl_ws_recv (3), +.BR curl_ws_send (3), +.BR libcurl-ws (3) diff --git a/3rdparty/curl/share/man/man3/curl_ws_recv.3 b/3rdparty/curl/share/man/man3/curl_ws_recv.3 new file mode 100644 index 0000000..3e93682 --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_ws_recv.3 @@ -0,0 +1,58 @@ +.\" generated by cd2nroff 0.1 from curl_ws_recv.md +.TH curl_ws_recv 3 "2024-10-11" libcurl +.SH NAME +curl_ws_recv \- receive WebSocket data +.SH SYNOPSIS +.nf +#include + +CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen, + size_t *recv, const struct curl_ws_frame **meta); +.fi +.SH DESCRIPTION +This function call is EXPERIMENTAL. + +Retrieves as much as possible of a received WebSocket data fragment into the +\fBbuffer\fP, but not more than \fBbuflen\fP bytes. \fIrecv\fP is set to the +number of bytes actually stored. + +If there is more fragment data to deliver than what fits in the provided +\fIbuffer\fP, libcurl returns a full buffer and the application needs to call +this function again to continue draining the buffer. + +The \fImeta\fP pointer gets set to point to a \fIconst struct curl_ws_frame\fP +that contains information about the received data. See the +\fIcurl_ws_meta(3)\fP for details on that struct. +.SH PROTOCOLS +This functionality affects ws only +.SH EXAMPLE +.nf +int main(void) +{ + size_t rlen; + const struct curl_ws_frame *meta; + char buffer[256]; + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res = curl_ws_recv(curl, buffer, sizeof(buffer), &rlen, &meta); + if(res) + printf("error: %s\\n", curl_easy_strerror(res)); + } +} +.fi +.SH AVAILABILITY +Added in curl 7.86.0 +.SH RETURN VALUE +Returns \fBCURLE_OK\fP if everything is okay, and a non\-zero number for +errors. Returns \fBCURLE_GOT_NOTHING\fP if the associated connection is +closed. + +Instead of blocking, the function returns \fBCURLE_AGAIN\fP. The correct +behavior is then to wait for the socket to signal readability before calling +this function again. +.SH SEE ALSO +.BR curl_easy_getinfo (3), +.BR curl_easy_perform (3), +.BR curl_easy_setopt (3), +.BR curl_ws_send (3), +.BR libcurl-ws (3) diff --git a/3rdparty/curl/share/man/man3/curl_ws_send.3 b/3rdparty/curl/share/man/man3/curl_ws_send.3 new file mode 100644 index 0000000..c737eaa --- /dev/null +++ b/3rdparty/curl/share/man/man3/curl_ws_send.3 @@ -0,0 +1,94 @@ +.\" generated by cd2nroff 0.1 from curl_ws_send.md +.TH curl_ws_send 3 "2024-10-11" libcurl +.SH NAME +curl_ws_send \- send WebSocket data +.SH SYNOPSIS +.nf +#include + +CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen, + size_t *sent, curl_off_t fragsize, + unsigned int flags); +.fi +.SH DESCRIPTION +This function call is EXPERIMENTAL. + +Send the specific message fragment over an established WebSocket +connection. The \fIbuffer\fP holds the data to send and it is \fIbuflen\fP +number of payload bytes in that memory area. + +\fIsent\fP is returned as the number of payload bytes actually sent. + +To send a (huge) fragment using multiple calls with partial content per +invoke, set the \fICURLWS_OFFSET\fP bit and the \fIfragsize\fP argument as the +total expected size for the first part, then set the \fICURLWS_OFFSET\fP with +a zero \fIfragsize\fP for the following parts. + +If not sending a partial fragment or if this is raw mode, \fIfragsize\fP +should be set to zero. + +If \fBCURLWS_RAW_MODE\fP is enabled in \fICURLOPT_WS_OPTIONS(3)\fP, the +\fBflags\fP argument should be set to 0. + +To send a message consisting of multiple frames, set the \fICURLWS_CONT\fP bit +in all frames except the final one. + +Warning: while it is possible to invoke this function from a callback, +such a call is blocking in this situation, e.g. only returns after all data +has been sent or an error is encountered. +.SH FLAGS +.IP CURLWS_TEXT +The buffer contains text data. Note that this makes a difference to WebSocket +but libcurl itself does not make any verification of the content or +precautions that you actually send valid UTF\-8 content. +.IP CURLWS_BINARY +This is binary data. +.IP CURLWS_CONT +This is not the final fragment of the message, which implies that there is +another fragment coming as part of the same message where this bit is not set. +.IP CURLWS_CLOSE +Close this transfer. +.IP CURLWS_PING +This is a ping. +.IP CURLWS_PONG +This is a pong. +.IP CURLWS_OFFSET +The provided data is only a partial fragment and there is more coming in a +following call to \fIcurl_ws_send()\fP. When sending only a piece of the +fragment like this, the \fIfragsize\fP must be provided with the total +expected fragment size in the first call and it needs to be zero in subsequent +calls. +.SH PROTOCOLS +This functionality affects ws only +.SH EXAMPLE +.nf +#include /* for strlen */ + +const char *send_payload = "magic"; + +int main(void) +{ + size_t sent; + CURLcode res; + CURL *curl = curl_easy_init(); + curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/"); + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L); + curl_easy_perform(curl); + res = curl_ws_send(curl, send_payload, strlen(send_payload), &sent, 0, + CURLWS_PING); + curl_easy_cleanup(curl); + return (int)res; +} +.fi +.SH AVAILABILITY +Added in curl 7.86.0 +.SH RETURN VALUE +\fICURLE_OK\fP (zero) means that the data was sent properly, non\-zero means an +error occurred as \fI\fP defines. See the \fIlibcurl\-errors(3)\fP man +page for the full list with descriptions. +.SH SEE ALSO +.BR curl_easy_getinfo (3), +.BR curl_easy_perform (3), +.BR curl_easy_setopt (3), +.BR curl_ws_recv (3), +.BR libcurl-ws (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-easy.3 b/3rdparty/curl/share/man/man3/libcurl-easy.3 new file mode 100644 index 0000000..a3e6ed3 --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-easy.3 @@ -0,0 +1,42 @@ +.\" generated by cd2nroff 0.1 from libcurl-easy.md +.TH libcurl-easy 3 "2024-10-11" libcurl +.SH NAME +libcurl\-easy \- easy interface overview +.SH DESCRIPTION +When using libcurl\(aqs "easy" interface you init your session and get a handle +(often referred to as an "easy handle"), which you use as input to the easy +interface functions you use. Use \fIcurl_easy_init(3)\fP to get the handle. + +You continue by setting all the options you want in the upcoming transfer, the +most important among them is the URL itself (you cannot transfer anything +without a specified URL). You might want to set some callbacks as well that +are called from the library when data is available etc. For example +\fICURLOPT_WRITEFUNCTION(3)\fP. \fIcurl_easy_setopt(3)\fP is used for all this. + +\fICURLOPT_URL(3)\fP is the only option you really must set, as otherwise there can +be no transfer. Another commonly used option is \fICURLOPT_VERBOSE(3)\fP that helps +you see what libcurl is doing under the hood, which is useful when debugging +for example. The \fIcurl_easy_setopt(3)\fP man page has a full index of the over 300 +available options. + +If you at any point would like to blank all previously set options for a +single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also make a +clone of an easy handle (with all its set options) using +\fIcurl_easy_duphandle(3)\fP. + +When all is setup, you tell libcurl to perform the transfer using +\fIcurl_easy_perform(3)\fP. It performs the entire transfer operation and does not +return until it is done (successfully or not). + +After the transfer has been made, you can set new options and make another +transfer, or if you are done, cleanup the session by calling +\fIcurl_easy_cleanup(3)\fP. If you want persistent connections, you do not cleanup +immediately, but instead run ahead and perform other transfers using the same +easy handle. +.SH SEE ALSO +.BR curl_easy_cleanup (3), +.BR curl_easy_init (3), +.BR curl_easy_setopt (3), +.BR libcurl (3), +.BR libcurl-errors (3), +.BR libcurl-multi (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-env-dbg.3 b/3rdparty/curl/share/man/man3/libcurl-env-dbg.3 new file mode 100644 index 0000000..d9586f1 --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-env-dbg.3 @@ -0,0 +1,92 @@ +.\" generated by cd2nroff 0.1 from libcurl-env-dbg.md +.TH libcurl-env-dbg 3 "2024-10-11" libcurl +.SH NAME +libcurl\-env\-dbg \- environment variables libcurl DEBUGBUILD understands +.SH DESCRIPTION +This is a set of variables only recognized and used if libcurl was built +\&"debug enabled", which should never be true for a library used in production. +These variables are intended for internal use only, subject to change and have +many effects on the behavior of libcurl. Refer to the source code to determine +how exactly they are being used. +.IP CURL_ALTSVC_HTTP +Bypass the AltSvc HTTPS protocol restriction if this variable exists. +.IP CURL_DBG_SOCK_RBLOCK +The percentage of recv() calls that should be answered with a EAGAIN at random. +For TCP/UNIX sockets. +.IP CURL_DBG_SOCK_RMAX +The maximum data that shall be received from the network in one recv() call. +For TCP/UNIX sockets. This is applied to every recv. + +Example: \fBCURL_DBG_SOCK_RMAX=400\fP means recv buffer size is limited to a +maximum of 400 bytes. +.IP CURL_DBG_SOCK_WBLOCK +The percentage of send() calls that should be answered with a EAGAIN at random. +For TCP/UNIX sockets. +.IP CURL_DBG_SOCK_WPARTIAL +The percentage of data that shall be written to the network. For TCP/UNIX +sockets. This is applied to every send. + +Example: \fBCURL_DBG_SOCK_WPARTIAL=80\fP means a send with 1000 bytes would +only send 800. +.IP CURL_DBG_QUIC_WBLOCK +The percentage of send() calls that should be answered with EAGAIN at random. +QUIC only. +.IP CURL_DEBUG +Trace logging behavior as an alternative to calling \fIcurl_global_trace(3)\fP. + +Example: \fBCURL_DEBUG=http/2\fP means trace details about HTTP/2 handling. + +In the curl command line tool, built with \fI\--enable\-debug\fP, this environment +variable adds to arguments like \fI\--verbose\fP, \fI\-vvv\fP. At least a single \fI\-v\fP +is needed to make the run emit trace output, but when it does, the contents +of \fICURL_DEBUG\fP are added and can override existing options. + +Example: \fBCURL_DEBUG=tcp,\-http/2 curl \-vv url\fP means trace protocol details, +triggered by \fI\-vv\fP, add tracing of TCP in addition and remove tracing of +HTTP/2. +.IP CURL_DEBUG_SIZE +Fake the size returned by CURLINFO_HEADER_SIZE and CURLINFO_REQUEST_SIZE. +.IP CURL_GETHOSTNAME +Fake the local machine\(aqs unqualified hostname for NTLM and SMTP. +.IP CURL_HSTS_HTTP +Bypass the HSTS HTTPS protocol restriction if this variable exists. +.IP CURL_FORCETIME +A time of 0 is used for AWS signatures and NTLM if this variable exists. +.IP CURL_ENTROPY +A fixed faked value to use instead of a proper random number so that functions +in libcurl that are otherwise getting random outputs can be tested for what +they generate. +.IP CURL_SMALLREQSEND +An alternative size of HTTP data to be sent at a time only if smaller than the +current. +.IP CURL_SMALLSENDS +An alternative size of socket data to be sent at a time only if smaller than +the current. +.IP CURL_TIME +Fake Unix timestamp to use for AltSvc, HSTS and CURLINFO variables that are +time related. + +This variable can also be used to fake the data returned by some CURLINFO +variables that are not time\-related (such as CURLINFO_LOCAL_PORT), and in that +case the value is not a timestamp. +.IP CURL_TRACE +LDAP tracing is enabled if this variable exists and its value is 1 or greater. + +OpenLDAP tracing is separate. Refer to CURL_OPENLDAP_TRACE. +.IP CURL_OPENLDAP_TRACE +OpenLDAP tracing is enabled if this variable exists and its value is 1 or +greater. There is a number of debug levels, refer to \fIopenldap.c\fP comments. +.IP CURL_WS_CHUNK_SIZE +Used to influence the buffer chunk size used for WebSocket encoding and +decoding. +.IP CURL_FORBID_REUSE +Used to set the CURLOPT_FORBID_REUSE flag on each transfer initiated +by the curl command line tool. The value of the environment variable +does not matter. +.IP CURL_GRACEFUL_SHUTDOWN +Make a blocking, graceful shutdown of all remaining connections when +a multi handle is destroyed. This implicitly triggers for easy handles +that are run via easy_perform. The value of the environment variable +gives the shutdown timeout in milliseconds. +.SH SEE ALSO +.BR libcurl-env (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-env.3 b/3rdparty/curl/share/man/man3/libcurl-env.3 new file mode 100644 index 0000000..b33e637 --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-env.3 @@ -0,0 +1,68 @@ +.\" generated by cd2nroff 0.1 from libcurl-env.md +.TH libcurl-env 3 "2024-10-11" libcurl +.SH NAME +libcurl\-env \- environment variables libcurl understands +.SH DESCRIPTION +libcurl reads and understands a set of environment variables that if set +controls and changes behaviors. This is the full list of variables to set and +description of what they do. Also note that curl, the command line tool, +supports a set of additional environment variables independently of this. +.IP [scheme]_proxy +When libcurl is given a URL to use in a transfer, it first extracts the scheme +part from the URL and checks if there is a given proxy set for that in its +corresponding environment variable. A URL like https://example.com makes +libcurl use the \fBhttp_proxy\fP variable, while a URL like ftp://example.com +uses the \fBftp_proxy\fP variable. + +These proxy variables are also checked for in their uppercase versions, except +the \fBhttp_proxy\fP one which is only used lowercase. Note also that some +systems actually have a case insensitive handling of environment variables and +then of course \fBHTTP_PROXY\fP still works. + +An exception exists for the WebSocket \fBws\fP and \fBwss\fP URL schemes, where +libcurl first checks \fBws_proxy\fP or \fBwss_proxy\fP but if they are not set, it +falls back and tries the http and https versions instead if set. +.IP ALL_PROXY +This is a setting to set proxy for all URLs, independently of what scheme is +being used. Note that the scheme specific variables overrides this one if set. +.IP CURL_SSL_BACKEND +When libcurl is built to support multiple SSL backends, it selects a specific +backend at first use. If no selection is done by the program using libcurl, +this variable\(aqs selection is used. Setting a name that is not a built\-in +alternative makes libcurl stay with the default. + +SSL backend names (case\-insensitive): BearSSL, GnuTLS, mbedTLS, +nss, OpenSSL, Rustls, Schannel, Secure\-Transport, wolfSSL +.IP HOME +When the netrc feature is used (\fICURLOPT_NETRC(3)\fP), this variable is +checked as the primary way to find the "current" home directory in which +the .netrc file is likely to exist. +.IP USERPROFILE +When the netrc feature is used (\fICURLOPT_NETRC(3)\fP), this variable is +checked as the secondary way to find the "current" home directory (on Windows +only) in which the .netrc file is likely to exist. +.IP LOGNAME +Username to use when invoking the \fIntlm\-wb\fP tool, if \fINTLMUSER\fP was +not set. +.IP NO_PROXY +This has the same functionality as the \fICURLOPT_NOPROXY(3)\fP option: it +gives libcurl a comma\-separated list of hostname patterns for which libcurl +should not use a proxy. +.IP NTLMUSER +Username to use when invoking the \fIntlm\-wb\fP tool. +.IP SSLKEYLOGFILE +When set and libcurl runs with a SSL backend that supports this feature, +libcurl saves SSL secrets into the given filename. Using those SSL secrets, +other tools (such as Wireshark) can decrypt the SSL communication and +analyze/view the traffic. + +These secrets and this file might be sensitive. Users are advised to take +precautions so that they are not stolen or otherwise inadvertently revealed. +.IP USER +Username to use when invoking the \fIntlm\-wb\fP tool, if \fINTLMUSER\fP and \fILOGNAME\fP +were not set. +.SH Debug Variables +Debug variables are intended for internal use and are documented in +\fIlibcurl\-env\-dbg(3)\fP. +.SH SEE ALSO +.BR libcurl-env-dbg (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-errors.3 b/3rdparty/curl/share/man/man3/libcurl-errors.3 new file mode 100644 index 0000000..df99d5d --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-errors.3 @@ -0,0 +1,422 @@ +.\" generated by cd2nroff 0.1 from libcurl-errors.md +.TH libcurl-errors 3 "2024-10-11" libcurl +.SH NAME +libcurl\-errors \- error codes in libcurl +.SH DESCRIPTION +This man page includes most, if not all, available error codes in libcurl. +Why they occur and possibly what you can do to fix the problem are also included. +.SH CURLcode +Almost all "easy" interface functions return a CURLcode error code. No matter +what, using the \fIcurl_easy_setopt(3)\fP option \fICURLOPT_ERRORBUFFER(3)\fP +is a good idea as it gives you a human readable error string that may offer +more details about the cause of the error than just the error code. +\fIcurl_easy_strerror(3)\fP can be called to get an error string from a given +CURLcode number. + +CURLcode is one of the following: +.IP "CURLE_OK (0)" +All fine. Proceed as usual. +.IP "CURLE_UNSUPPORTED_PROTOCOL (1)" +The URL you passed to libcurl used a protocol that this libcurl does not +support. The support might be a compile\-time option that you did not use, it +can be a misspelled protocol string or just a protocol libcurl has no code +for. +.IP "CURLE_FAILED_INIT (2)" +Early initialization code failed. This is likely to be an internal error or +problem, or a resource problem where something fundamental could not get done +at init time. +.IP "CURLE_URL_MALFORMAT (3)" +The URL was not properly formatted. +.IP "CURLE_NOT_BUILT_IN (4)" +A requested feature, protocol or option was not found built\-in in this libcurl +due to a build\-time decision. This means that a feature or option was not +enabled or explicitly disabled when libcurl was built and in order to get it +to function you have to get a rebuilt libcurl. +.IP "CURLE_COULDNT_RESOLVE_PROXY (5)" +Could not resolve proxy. The given proxy host could not be resolved. +.IP "CURLE_COULDNT_RESOLVE_HOST (6)" +Could not resolve host. The given remote host was not resolved. +.IP "CURLE_COULDNT_CONNECT (7)" +Failed to connect() to host or proxy. +.IP "CURLE_WEIRD_SERVER_REPLY (8)" +The server sent data libcurl could not parse. This error code was known as +\fICURLE_FTP_WEIRD_SERVER_REPLY\fP before 7.51.0. +.IP "CURLE_REMOTE_ACCESS_DENIED (9)" +We were denied access to the resource given in the URL. For FTP, this occurs +while trying to change to the remote directory. +.IP "CURLE_FTP_ACCEPT_FAILED (10)" +While waiting for the server to connect back when an active FTP session is +used, an error code was sent over the control connection or similar. +.IP "CURLE_FTP_WEIRD_PASS_REPLY (11)" +After having sent the FTP password to the server, libcurl expects a proper +reply. This error code indicates that an unexpected code was returned. +.IP "CURLE_FTP_ACCEPT_TIMEOUT (12)" +During an active FTP session while waiting for the server to connect, the +\fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP (or the internal default) timeout expired. +.IP "CURLE_FTP_WEIRD_PASV_REPLY (13)" +libcurl failed to get a sensible result back from the server as a response to +either a PASV or a EPSV command. The server is flawed. +.IP "CURLE_FTP_WEIRD_227_FORMAT (14)" +FTP servers return a 227\-line as a response to a PASV command. If libcurl +fails to parse that line, this return code is passed back. +.IP "CURLE_FTP_CANT_GET_HOST (15)" +An internal failure to lookup the host used for the new connection. +.IP "CURLE_HTTP2 (16)" +A problem was detected in the HTTP2 framing layer. This is somewhat generic +and can be one out of several problems, see the error buffer for details. +.IP "CURLE_FTP_COULDNT_SET_TYPE (17)" +Received an error when trying to set the transfer mode to binary or ASCII. +.IP "CURLE_PARTIAL_FILE (18)" +A file transfer was shorter or larger than expected. This happens when the +server first reports an expected transfer size, and then delivers data that +does not match the previously given size. +.IP "CURLE_FTP_COULDNT_RETR_FILE (19)" +This was either a weird reply to a \(aqRETR\(aq command or a zero byte transfer +complete. +.IP "Obsolete error (20)" +Not used in modern versions. +.IP "CURLE_QUOTE_ERROR (21)" +When sending custom "QUOTE" commands to the remote server, one of the commands +returned an error code that was 400 or higher (for FTP) or otherwise +indicated unsuccessful completion of the command. +.IP "CURLE_HTTP_RETURNED_ERROR (22)" +This is returned if \fICURLOPT_FAILONERROR(3)\fP is set TRUE and the HTTP server +returns an error code that is >= 400. +.IP "CURLE_WRITE_ERROR (23)" +An error occurred when writing received data to a local file, or an error was +returned to libcurl from a write callback. +.IP "Obsolete error (24)" +Not used in modern versions. +.IP "CURLE_UPLOAD_FAILED (25)" +Failed starting the upload. For FTP, the server typically denied the STOR +command. The error buffer usually contains the server\(aqs explanation for this. +.IP "CURLE_READ_ERROR (26)" +There was a problem reading a local file or an error returned by the read +callback. +.IP "CURLE_OUT_OF_MEMORY (27)" +A memory allocation request failed. This is serious badness and +things are severely screwed up if this ever occurs. +.IP "CURLE_OPERATION_TIMEDOUT (28)" +Operation timeout. The specified time\-out period was reached according to the +conditions. +.IP "Obsolete error (29)" +Not used in modern versions. +.IP "CURLE_FTP_PORT_FAILED (30)" +The FTP PORT command returned error. This mostly happens when you have not +specified a good enough address for libcurl to use. See +\fICURLOPT_FTPPORT(3)\fP. +.IP "CURLE_FTP_COULDNT_USE_REST (31)" +The FTP REST command returned error. This should never happen if the server is +sane. +.IP "Obsolete error (32)" +Not used in modern versions. +.IP "CURLE_RANGE_ERROR (33)" +The server does not support or accept range requests. +.IP "CURLE_HTTP_POST_ERROR (34)" +This is an odd error that mainly occurs due to internal confusion. +.IP "CURLE_SSL_CONNECT_ERROR (35)" +A problem occurred somewhere in the SSL/TLS handshake. You really want the +error buffer and read the message there as it pinpoints the problem slightly +more. Could be certificates (file formats, paths, permissions), passwords, and +others. +.IP "CURLE_BAD_DOWNLOAD_RESUME (36)" +The download could not be resumed because the specified offset was out of the +file boundary. +.IP "CURLE_FILE_COULDNT_READ_FILE (37)" +A file given with FILE:// could not be opened. Most likely because the file +path does not identify an existing file. Did you check file permissions? +.IP "CURLE_LDAP_CANNOT_BIND (38)" +LDAP cannot bind. LDAP bind operation failed. +.IP "CURLE_LDAP_SEARCH_FAILED (39)" +LDAP search failed. +.IP "Obsolete error (40)" +Not used in modern versions. +.IP "CURLE_FUNCTION_NOT_FOUND (41)" +Function not found. A required zlib function was not found. +.IP "CURLE_ABORTED_BY_CALLBACK (42)" +Aborted by callback. A callback returned "abort" to libcurl. +.IP "CURLE_BAD_FUNCTION_ARGUMENT (43)" +A function was called with a bad parameter. +.IP "Obsolete error (44)" +Not used in modern versions. +.IP "CURLE_INTERFACE_FAILED (45)" +Interface error. A specified outgoing interface could not be used. Set which +interface to use for outgoing connections\(aq source IP address with +\fICURLOPT_INTERFACE(3)\fP. +.IP "Obsolete error (46)" +Not used in modern versions. +.IP "CURLE_TOO_MANY_REDIRECTS (47)" +Too many redirects. When following redirects, libcurl hit the maximum amount. +Set your limit with \fICURLOPT_MAXREDIRS(3)\fP. +.IP "CURLE_UNKNOWN_OPTION (48)" +An option passed to libcurl is not recognized/known. Refer to the appropriate +documentation. This is most likely a problem in the program that uses +libcurl. The error buffer might contain more specific information about which +exact option it concerns. +.IP "CURLE_SETOPT_OPTION_SYNTAX (49)" +An option passed in to a setopt was wrongly formatted. See error message for +details about what option. +.IP "Obsolete errors (50-51)" +Not used in modern versions. +.IP "CURLE_GOT_NOTHING (52)" +Nothing was returned from the server, and under the circumstances, getting +nothing is considered an error. +.IP "CURLE_SSL_ENGINE_NOTFOUND (53)" +The specified crypto engine was not found. +.IP "CURLE_SSL_ENGINE_SETFAILED (54)" +Failed setting the selected SSL crypto engine as default. +.IP "CURLE_SEND_ERROR (55)" +Failed sending network data. +.IP "CURLE_RECV_ERROR (56)" +Failure with receiving network data. +.IP "Obsolete error (57)" +Not used in modern versions. +.IP "CURLE_SSL_CERTPROBLEM (58)" +problem with the local client certificate. +.IP "CURLE_SSL_CIPHER (59)" +Could not use specified cipher. +.IP "CURLE_PEER_FAILED_VERIFICATION (60)" +The remote server\(aqs SSL certificate or SSH fingerprint was deemed not OK. +This error code has been unified with CURLE_SSL_CACERT since 7.62.0. Its +previous value was 51. +.IP "CURLE_BAD_CONTENT_ENCODING (61)" +Unrecognized transfer encoding. +.IP "Obsolete error (62)" +Not used in modern versions. +.IP "CURLE_FILESIZE_EXCEEDED (63)" +Maximum file size exceeded. +.IP "CURLE_USE_SSL_FAILED (64)" +Requested FTP SSL level failed. +.IP "CURLE_SEND_FAIL_REWIND (65)" +When doing a send operation curl had to rewind the data to retransmit, but the +rewinding operation failed. +.IP "CURLE_SSL_ENGINE_INITFAILED (66)" +Initiating the SSL Engine failed. +.IP "CURLE_LOGIN_DENIED (67)" +The remote server denied curl to login (Added in 7.13.1) +.IP "CURLE_TFTP_NOTFOUND (68)" +File not found on TFTP server. +.IP "CURLE_TFTP_PERM (69)" +Permission problem on TFTP server. +.IP "CURLE_REMOTE_DISK_FULL (70)" +Out of disk space on the server. +.IP "CURLE_TFTP_ILLEGAL (71)" +Illegal TFTP operation. +.IP "CURLE_TFTP_UNKNOWNID (72)" +Unknown TFTP transfer ID. +.IP "CURLE_REMOTE_FILE_EXISTS (73)" +File already exists and is not overwritten. +.IP "CURLE_TFTP_NOSUCHUSER (74)" +This error should never be returned by a properly functioning TFTP server. +.IP "Obsolete error (75-76)" +Not used in modern versions. +.IP "CURLE_SSL_CACERT_BADFILE (77)" +Problem with reading the SSL CA cert (path? access rights?) +.IP "CURLE_REMOTE_FILE_NOT_FOUND (78)" +The resource referenced in the URL does not exist. +.IP "CURLE_SSH (79)" +An unspecified error occurred during the SSH session. +.IP "CURLE_SSL_SHUTDOWN_FAILED (80)" +Failed to shut down the SSL connection. +.IP "CURLE_AGAIN (81)" +Socket is not ready for send/recv. Wait until it is ready and try again. This +return code is only returned from \fIcurl_easy_recv(3)\fP and \fIcurl_easy_send(3)\fP +(Added in 7.18.2) +.IP "CURLE_SSL_CRL_BADFILE (82)" +Failed to load CRL file (Added in 7.19.0) +.IP "CURLE_SSL_ISSUER_ERROR (83)" +Issuer check failed (Added in 7.19.0) +.IP "CURLE_FTP_PRET_FAILED (84)" +The FTP server does not understand the PRET command at all or does not support +the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST(3)\fP, a +custom LIST command is sent with the PRET command before PASV as well. (Added +in 7.20.0) +.IP "CURLE_RTSP_CSEQ_ERROR (85)" +Mismatch of RTSP CSeq numbers. +.IP "CURLE_RTSP_SESSION_ERROR (86)" +Mismatch of RTSP Session Identifiers. +.IP "CURLE_FTP_BAD_FILE_LIST (87)" +Unable to parse FTP file list (during FTP wildcard downloading). +.IP "CURLE_CHUNK_FAILED (88)" +Chunk callback reported error. +.IP "CURLE_NO_CONNECTION_AVAILABLE (89)" +(For internal use only, is never returned by libcurl) No connection available, +the session is queued. (added in 7.30.0) +.IP "CURLE_SSL_PINNEDPUBKEYNOTMATCH (90)" +Failed to match the pinned key specified with \fICURLOPT_PINNEDPUBLICKEY(3)\fP. +.IP "CURLE_SSL_INVALIDCERTSTATUS (91)" +Status returned failure when asked with \fICURLOPT_SSL_VERIFYSTATUS(3)\fP. +.IP "CURLE_HTTP2_STREAM (92)" +Stream error in the HTTP/2 framing layer. +.IP "CURLE_RECURSIVE_API_CALL (93)" +An API function was called from inside a callback. +.IP "CURLE_AUTH_ERROR (94)" +An authentication function returned an error. +.IP "CURLE_HTTP3 (95)" +A problem was detected in the HTTP/3 layer. This is somewhat generic and can +be one out of several problems, see the error buffer for details. +.IP "CURLE_QUIC_CONNECT_ERROR (96)" +QUIC connection error. This error may be caused by an SSL library error. QUIC +is the protocol used for HTTP/3 transfers. +.IP "CURLE_PROXY (97)" +Proxy handshake error. \fICURLINFO_PROXY_ERROR(3)\fP provides extra details on +the specific problem. +.IP "CURLE_SSL_CLIENTCERT (98)" +SSL Client Certificate required. +.IP "CURLE_UNRECOVERABLE_POLL (99)" +An internal call to poll() or select() returned error that is not recoverable. +.IP "CURLE_TOO_LARGE (100)" +A value or data field grew larger than allowed. +.IP "CURLE_ECH_REQUIRED (101)"" +ECH was attempted but failed. +.SH CURLMcode +This is the generic return code used by functions in the libcurl multi +interface. Also consider \fIcurl_multi_strerror(3)\fP. +.IP "CURLM_CALL_MULTI_PERFORM (-1)" +This is not really an error. It means you should call +\fIcurl_multi_perform(3)\fP again without doing select() or similar in +between. Before version 7.20.0 (released on February 9 2010) this could be returned by +\fIcurl_multi_perform(3)\fP, but in later versions this return code is never +used. +.IP "CURLM_OK (0)" +Things are fine. +.IP "CURLM_BAD_HANDLE (1)" +The passed\-in handle is not a valid \fICURLM\fP handle. +.IP "CURLM_BAD_EASY_HANDLE (2)" +An easy handle was not good/valid. It could mean that it is not an easy handle +at all, or possibly that the handle already is in use by this or another multi +handle. +.IP "CURLM_OUT_OF_MEMORY (3)" +You are doomed. +.IP "CURLM_INTERNAL_ERROR (4)" +This can only be returned if libcurl bugs. Please report it to us! +.IP "CURLM_BAD_SOCKET (5)" +The passed\-in socket is not a valid one that libcurl already knows about. +(Added in 7.15.4) +.IP "CURLM_UNKNOWN_OPTION (6)" +curl_multi_setopt() with unsupported option +(Added in 7.15.4) +.IP "CURLM_ADDED_ALREADY (7)" +An easy handle already added to a multi handle was attempted to get added a +second time. (Added in 7.32.1) +.IP "CURLM_RECURSIVE_API_CALL (8)" +An API function was called from inside a callback. +.IP "CURLM_WAKEUP_FAILURE (9)" +Wake up is unavailable or failed. +.IP "CURLM_BAD_FUNCTION_ARGUMENT (10)" +A function was called with a bad parameter. +.IP "CURLM_ABORTED_BY_CALLBACK (11)" +A multi handle callback returned error. +.IP "CURLM_UNRECOVERABLE_POLL (12)" +An internal call to poll() or select() returned error that is not recoverable. +.SH CURLSHcode +The "share" interface returns a \fBCURLSHcode\fP to indicate when an error has +occurred. Also consider \fIcurl_share_strerror(3)\fP. +.IP "CURLSHE_OK (0)" +All fine. Proceed as usual. +.IP "CURLSHE_BAD_OPTION (1)" +An invalid option was passed to the function. +.IP "CURLSHE_IN_USE (2)" +The share object is currently in use. +.IP "CURLSHE_INVALID (3)" +An invalid share object was passed to the function. +.IP "CURLSHE_NOMEM (4)" +Not enough memory was available. +(Added in 7.12.0) +.IP "CURLSHE_NOT_BUILT_IN (5)" +The requested sharing could not be done because the library you use do not have +that particular feature enabled. (Added in 7.23.0) +.SH CURLUcode +The URL interface returns a \fICURLUcode\fP to indicate when an error has +occurred. Also consider \fIcurl_url_strerror(3)\fP. +.IP "CURLUE_OK (0)" +All fine. Proceed as usual. +.IP "CURLUE_BAD_HANDLE (1)" +An invalid URL handle was passed as argument. +.IP "CURLUE_BAD_PARTPOINTER (2)" +An invalid \(aqpart\(aq argument was passed as argument. +.IP "CURLUE_MALFORMED_INPUT (3)" +A malformed input was passed to a URL API function. +.IP "CURLUE_BAD_PORT_NUMBER (4)" +The port number was not a decimal number between 0 and 65535. +.IP "CURLUE_UNSUPPORTED_SCHEME (5)" +This libcurl build does not support the given URL scheme. +.IP "CURLUE_URLDECODE (6)" +URL decode error, most likely because of rubbish in the input. +.IP "CURLUE_OUT_OF_MEMORY (7)" +A memory function failed. +.IP "CURLUE_USER_NOT_ALLOWED (8)" +Credentials was passed in the URL when prohibited. +.IP "CURLUE_UNKNOWN_PART (9)" +An unknown part ID was passed to a URL API function. +.IP "CURLUE_NO_SCHEME (10)" +There is no scheme part in the URL. +.IP "CURLUE_NO_USER (11)" +There is no user part in the URL. +.IP "CURLUE_NO_PASSWORD (12)" +There is no password part in the URL. +.IP "CURLUE_NO_OPTIONS (13)" +There is no options part in the URL. +.IP "CURLUE_NO_HOST (14)" +There is no host part in the URL. +.IP "CURLUE_NO_PORT (15)" +There is no port part in the URL. +.IP "CURLUE_NO_QUERY (16)" +There is no query part in the URL. +.IP "CURLUE_NO_FRAGMENT (17)" +There is no fragment part in the URL. +.IP "CURLUE_NO_ZONEID (18)" +There is no zone id set in the URL. +.IP "CURLUE_BAD_FILE_URL (19)" +The file:// URL is invalid. +.IP "CURLUE_BAD_FRAGMENT (20)" +The fragment part of the URL contained bad or invalid characters. +.IP "CURLUE_BAD_HOSTNAME (21)" +The hostname contained bad or invalid characters. +.IP "CURLUE_BAD_IPV6 (22)" +The IPv6 address hostname contained bad or invalid characters. +.IP "CURLUE_BAD_LOGIN (23)" +The login part of the URL contained bad or invalid characters. +.IP "CURLUE_BAD_PASSWORD (24)" +The password part of the URL contained bad or invalid characters. +.IP "CURLUE_BAD_PATH (25)" +The path part of the URL contained bad or invalid characters. +.IP "CURLUE_BAD_QUERY (26)" +The query part of the URL contained bad or invalid characters. +.IP "CURLUE_BAD_SCHEME (27)" +The scheme part of the URL contained bad or invalid characters. +.IP "CURLUE_BAD_SLASHES (28)" +The URL contained an invalid number of slashes. +.IP "CURLUE_BAD_USER (29)" +The user part of the URL contained bad or invalid characters. +.IP "CURLUE_LACKS_IDN (30)" +libcurl lacks IDN support. +.IP "CURLUE_TOO_LARGE (31)" +A value or data field is larger than allowed. +.SH CURLHcode +The header interface returns a \fICURLHcode\fP to indicate when an error has +occurred. +.IP "CURLHE_OK (0)" +All fine. Proceed as usual. +.IP "CURLHE_BADINDEX (1)" +There is no header with the requested index. +.IP "CURLHE_MISSING (2)" +No such header exists. +.IP "CURLHE_NOHEADERS (3)" +No headers at all have been recorded. +.IP "CURLHE_NOREQUEST (4)" +There was no such request number. +.IP "CURLHE_OUT_OF_MEMORY (5)" +Out of resources +.IP "CURLHE_BAD_ARGUMENT (6)" +One or more of the given arguments are bad. +.IP "CURLHE_NOT_BUILT_IN (7)" +HTTP support or the header API has been disabled in the build. +.SH SEE ALSO +.BR CURLOPT_DEBUGFUNCTION (3), +.BR CURLOPT_ERRORBUFFER (3), +.BR CURLOPT_VERBOSE (3), +.BR curl_easy_strerror (3), +.BR curl_multi_strerror (3), +.BR curl_share_strerror (3), +.BR curl_url_strerror (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-multi.3 b/3rdparty/curl/share/man/man3/libcurl-multi.3 new file mode 100644 index 0000000..bfbaa6d --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-multi.3 @@ -0,0 +1,161 @@ +.\" generated by cd2nroff 0.1 from libcurl-multi.md +.TH libcurl-multi 3 "2024-10-11" libcurl +.SH NAME +libcurl\-multi \- how to use the multi interface +.SH DESCRIPTION +This is an overview on how to use the libcurl multi interface in your C +programs. There are specific man pages for each function mentioned in +here. There is also the \fIlibcurl\-tutorial(3)\fP man page for a complete +tutorial to programming with libcurl and the \fIlibcurl\-easy(3)\fP man page +for an overview of the libcurl easy interface. + +All functions in the multi interface are prefixed with curl_multi. +.SH OBJECTIVES +The multi interface offers several abilities that the easy interface does not. +They are mainly: + +1. Enable a "pull" interface. The application that uses libcurl decides where +and when to ask libcurl to get/send data. + +2. Enable multiple simultaneous transfers in the same thread without making it +complicated for the application. + +3. Enable the application to wait for action on its own file descriptors and +curl\(aqs file descriptors simultaneously. + +4. Enable event\-based handling and scaling transfers up to and beyond +thousands of parallel connections. +.SH ONE MULTI HANDLE MANY EASY HANDLES +To use the multi interface, you must first create a \(aqmulti handle\(aq with +\fIcurl_multi_init(3)\fP. This handle is then used as input to all further +curl_multi_* functions. + +With a multi handle and the multi interface you can do several simultaneous +transfers in parallel. Each single transfer is built up around an easy +handle. You create all the easy handles you need, and setup the appropriate +options for each easy handle using \fIcurl_easy_setopt(3)\fP. + +There are two flavors of the multi interface, the select() oriented one and +the event based one we call multi_socket. You benefit from reading through the +description of both versions to fully understand how they work and +differentiate. We start out with the select() oriented version. + +When an easy handle is setup and ready for transfer, then instead of using +\fIcurl_easy_perform(3)\fP like when using the easy interface for transfers, +you should add the easy handle to the multi handle with +\fIcurl_multi_add_handle(3)\fP. You can add more easy handles to a multi +handle at any point, even if other transfers are already running. + +Should you change your mind, the easy handle is again removed from the multi +stack using \fIcurl_multi_remove_handle(3)\fP. Once removed from the multi +handle, you can again use other easy interface functions like +\fIcurl_easy_perform(3)\fP on the handle or whatever you think is +necessary. You can remove handles at any point during transfers. + +Adding the easy handle to the multi handle does not start the transfer. +Remember that one of the main ideas with this interface is to let your +application drive. You drive the transfers by invoking +\fIcurl_multi_perform(3)\fP. libcurl then transfers data if there is anything +available to transfer. It uses the callbacks and everything else you have +setup in the individual easy handles. It transfers data on all current +transfers in the multi stack that are ready to transfer anything. It may be +all, it may be none. When there is nothing more to do for now, it returns back +to the calling application. + +Your application extracts info from libcurl about when it would like to get +invoked to transfer data or do other work. The most convenient way is to use +\fIcurl_multi_poll(3)\fP that helps you wait until the application should call +libcurl again. The older API to accomplish the same thing is +\fIcurl_multi_fdset(3)\fP that extracts \fIfd_sets\fP from libcurl to use in +select() or poll() calls in order to get to know when the transfers in the +multi stack might need attention. Both these APIs allow for your program to +wait for input on your own private file descriptors at the same time. +\fIcurl_multi_timeout(3)\fP also helps you with providing a suitable timeout +period for your select() calls. + +\fIcurl_multi_perform(3)\fP stores the number of still running transfers in +one of its input arguments, and by reading that you can figure out when all +the transfers in the multi handles are done. \(aqdone\(aq does not mean +successful. One or more of the transfers may have failed. + +To get information about completed transfers, to figure out success or not and +similar, \fIcurl_multi_info_read(3)\fP should be called. It can return a +message about a current or previous transfer. Repeated invokes of the function +get more messages until the message queue is empty. The information you +receive there includes an easy handle pointer which you may use to identify +which easy handle the information regards. + +When a single transfer is completed, the easy handle is still left added to +the multi stack. You need to first remove the easy handle with +\fIcurl_multi_remove_handle(3)\fP and then close it with +\fIcurl_easy_cleanup(3)\fP, or possibly set new options to it and add it again +with \fIcurl_multi_add_handle(3)\fP to start another transfer. + +When all transfers in the multi stack are done, close the multi handle with +\fIcurl_multi_cleanup(3)\fP. Be careful and please note that you \fBMUST\fP +invoke separate \fIcurl_easy_cleanup(3)\fP calls for every single easy handle +to clean them up properly. + +If you want to reuse an easy handle that was added to the multi handle for +transfer, you must first remove it from the multi stack and then re\-add it +again (possibly after having altered some options at your own choice). +.SH MULTI_SOCKET +\fIcurl_multi_socket_action(3)\fP function offers a way for applications to +not only avoid being forced to use select(), but it also offers a much more +high\-performance API that makes a significant difference for applications +using large numbers of simultaneous connections. + +\fIcurl_multi_socket_action(3)\fP is then used instead of +\fIcurl_multi_perform(3)\fP. + +When using this API, you add easy handles to the multi handle just as with the +normal multi interface. Then you also set two callbacks with the +\fICURLMOPT_SOCKETFUNCTION(3)\fP and \fICURLMOPT_TIMERFUNCTION(3)\fP options +to \fIcurl_multi_setopt(3)\fP. They are two callback functions that libcurl +calls with information about what sockets to wait for, and for what activity, +and what the current timeout time is \- if that expires libcurl should be +notified. + +The multi_socket API is designed to inform your application about which +sockets libcurl is currently using and for what activities (read and/or write) +on those sockets your application is expected to wait for. + +Your application must make sure to receive all sockets informed about in the +\fICURLMOPT_SOCKETFUNCTION(3)\fP callback and make sure it reacts on the given +activity on them. When a socket has the given activity, you call +\fIcurl_multi_socket_action(3)\fP specifying which socket and action there +are. + +The \fICURLMOPT_TIMERFUNCTION(3)\fP callback is called to set a timeout. When +that timeout expires, your application should call the +\fIcurl_multi_socket_action(3)\fP function saying it was due to a timeout. + +This API is typically used with an event\-driven underlying functionality (like +libevent, libev, kqueue, epoll or similar) with which the application +\&"subscribes" on socket changes. This allows applications and libcurl to much +better scale upward and beyond thousands of simultaneous transfers without +losing performance. + +When you have added your initial set of handles, you call +\fIcurl_multi_socket_action(3)\fP with CURL_SOCKET_TIMEOUT set in the +\fIsockfd\fP argument, and you get callbacks invoked that set you up and you +then continue to call \fIcurl_multi_socket_action(3)\fP accordingly when you +get activity on the sockets you have been asked to wait on, or if the timeout +timer expires. + +You can poll \fIcurl_multi_info_read(3)\fP to see if any transfer has +completed, as it then has a message saying so. +.SH BLOCKING +A few areas in the code are still using blocking code, even when used from the +multi interface. While we certainly want and intend for these to get fixed in +the future, you should be aware of the following current restrictions: + +.nf + - Name resolves unless the c-ares or threaded-resolver backends are used + - file:// transfers + - TELNET transfers +.fi +.SH SEE ALSO +.BR libcurl (3), +.BR libcurl-easy (3), +.BR libcurl-errors (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-security.3 b/3rdparty/curl/share/man/man3/libcurl-security.3 new file mode 100644 index 0000000..7ae2a95 --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-security.3 @@ -0,0 +1,417 @@ +.\" generated by cd2nroff 0.1 from libcurl-security.md +.TH libcurl-security 3 "2024-10-11" libcurl +.SH NAME +libcurl\-security \- security considerations when using libcurl +.SH Security +The libcurl project takes security seriously. The library is written with +caution and precautions are taken to mitigate many kinds of risks encountered +while operating with potentially malicious servers on the Internet. It is a +powerful library, however, which allows application writers to make trade\-offs +between ease of writing and exposure to potential risky operations. If used +the right way, you can use libcurl to transfer data pretty safely. + +Many applications are used in closed networks where users and servers can +(possibly) be trusted, but many others are used on arbitrary servers and are +fed input from potentially untrusted users. Following is a discussion about +some risks in the ways in which applications commonly use libcurl and +potential mitigations of those risks. It is not comprehensive, but shows +classes of attacks that robust applications should consider. The Common +Weakness Enumeration project at https://cwe.mitre.org/ is a good reference for +many of these and similar types of weaknesses of which application writers +should be aware. +.SH Command Lines +If you use a command line tool (such as curl) that uses libcurl, and you give +options to the tool on the command line those options can get read by other +users of your system when they use \fIps\fP or other tools to list currently +running processes. + +To avoid these problems, never feed sensitive things to programs using command +line options. Write them to a protected file and use the \-K option to avoid +this. +.SH .netrc +\&.netrc is a pretty handy file/feature that allows you to login quickly and +automatically to frequently visited sites. The file contains passwords in +clear text and is a real security risk. In some cases, your .netrc is also +stored in a home directory that is NFS mounted or used on another network +based file system, so the clear text password flies through your network every +time anyone reads that file. + +For applications that enable .netrc use, a user who manage to set the right +URL might then be possible to pass on passwords. + +To avoid these problems, do not use .netrc files and never store passwords in +plain text anywhere. +.SH Clear Text Passwords +Many of the protocols libcurl supports send name and password unencrypted as +clear text (HTTP Basic authentication, FTP, TELNET etc). It is easy for anyone +on your network or a network nearby yours to just fire up a network analyzer +tool and eavesdrop on your passwords. Do not let the fact that HTTP Basic uses +base64 encoded passwords fool you. They may not look readable at a first +glance, but they are easily "deciphered" by anyone within seconds. + +To avoid this problem, use an authentication mechanism or other protocol that +does not let snoopers see your password: Digest, CRAM\-MD5, Kerberos, SPNEGO or +NTLM authentication. Or even better: use authenticated protocols that protect +the entire connection and everything sent over it. +.SH Unauthenticated Connections +Protocols that do not have any form of cryptographic authentication cannot +with any certainty know that they communicate with the right remote server. + +If your application is using a fixed scheme or fixed hostname, it is not safe +as long as the connection is unauthenticated. There can be a man\-in\-the\-middle +or in fact the whole server might have been replaced by an evil actor. + +Unauthenticated protocols are unsafe. The data that comes back to curl may +have been injected by an attacker. The data that curl sends might be modified +before it reaches the intended server. If it even reaches the intended server +at all. + +Remedies: +.IP "Restrict operations to authenticated transfers" +Use authenticated protocols protected with HTTPS or SSH. +.IP "Make sure the server's certificate etc is verified" +Never ever switch off certificate verification. +.SH Redirects +The \fICURLOPT_FOLLOWLOCATION(3)\fP option automatically follows HTTP +redirects sent by a remote server. These redirects can refer to any kind of +URL, not just HTTP. libcurl restricts the protocols allowed to be used in +redirects for security reasons: only HTTP, HTTPS, FTP and FTPS are +enabled by default. Applications may opt to restrict that set further. + +A redirect to a file: URL would cause the libcurl to read (or write) arbitrary +files from the local filesystem. If the application returns the data back to +the user (as would happen in some kinds of CGI scripts), an attacker could +leverage this to read otherwise forbidden data (e.g. +\fBfile://localhost/etc/passwd\fP). + +If authentication credentials are stored in the ~/.netrc file, or Kerberos is +in use, any other URL type (not just file:) that requires authentication is +also at risk. A redirect such as \fBftp://some\-internal\-server/private\-file\fP would +then return data even when the server is password protected. + +In the same way, if an unencrypted SSH private key has been configured for the +user running the libcurl application, SCP: or SFTP: URLs could access password +or private\-key protected resources, +e.g. \fBsftp://user@some\-internal\-server/etc/passwd\fP + +The \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP and \fICURLOPT_NETRC(3)\fP options can be +used to mitigate against this kind of attack. + +A redirect can also specify a location available only on the machine running +libcurl, including servers hidden behind a firewall from the attacker. +E.g. \fBhttp://127.0.0.1/\fP or \fBhttp://intranet/delete\-stuff.cgi?delete=all\fP or +\fBtftp://bootp\-server/pc\-config\-data\fP + +Applications can mitigate against this by disabling +\fICURLOPT_FOLLOWLOCATION(3)\fP and handling redirects itself, sanitizing URLs +as necessary. Alternately, an app could leave \fICURLOPT_FOLLOWLOCATION(3)\fP +enabled but set \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP and install a +\fICURLOPT_OPENSOCKETFUNCTION(3)\fP or \fICURLOPT_PREREQFUNCTION(3)\fP callback +function in which addresses are sanitized before use. +.SH CRLF in Headers +For all options in libcurl which specify headers, including but not limited to +\fICURLOPT_HTTPHEADER(3)\fP, \fICURLOPT_PROXYHEADER(3)\fP, +\fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_REFERER(3)\fP +and \fICURLOPT_RANGE(3)\fP, libcurl sends the headers as\-is and does not apply +any special sanitation or normalization to them. + +If you allow untrusted user input into these options without sanitizing CRLF +sequences in them, someone malicious may be able to modify the request in a +way you did not intend such as injecting new headers. +.SH Local Resources +A user who can control the DNS server of a domain being passed in within a URL +can change the address of the host to a local, private address which a +server\-side libcurl\-using application could then use. E.g. the innocuous URL +\fBhttp://fuzzybunnies.example.com/\fP could actually resolve to the IP +address of a server behind a firewall, such as 127.0.0.1 or +10.1.2.3. Applications can mitigate against this by setting a +\fICURLOPT_OPENSOCKETFUNCTION(3)\fP or \fICURLOPT_PREREQFUNCTION(3)\fP and +checking the address before a connection. + +All the malicious scenarios regarding redirected URLs apply just as well to +non\-redirected URLs, if the user is allowed to specify an arbitrary URL that +could point to a private resource. For example, a web app providing a +translation service might happily translate \fBfile://localhost/etc/passwd\fP +and display the result. Applications can mitigate against this with the +\fICURLOPT_PROTOCOLS_STR(3)\fP option as well as by similar mitigation techniques +for redirections. + +A malicious FTP server could in response to the PASV command return an IP +address and port number for a server local to the app running libcurl but +behind a firewall. Applications can mitigate against this by using the +\fICURLOPT_FTP_SKIP_PASV_IP(3)\fP option or \fICURLOPT_FTPPORT(3)\fP. + +Local servers sometimes assume local access comes from friends and trusted +users. An application that expects https://example.com/file_to_read that and +instead gets http://192.168.0.1/my_router_config might print a file that would +otherwise be protected by the firewall. + +Allowing your application to connect to local hosts, be it the same machine +that runs the application or a machine on the same local network, might be +possible to exploit by an attacker who then perhaps can "port\-scan" the +particular hosts \- depending on how the application and servers acts. +.SH IPv4 Addresses +Some users might be tempted to filter access to local resources or similar +based on numerical IPv4 addresses used in URLs. This is a bad and error\-prone +idea because of the many different ways a numerical IPv4 address can be +specified and libcurl accepts: one to four dot\-separated fields using one of +or a mix of decimal, octal or hexadecimal encoding. +.SH IPv6 Addresses +libcurl handles IPv6 addresses transparently and just as easily as IPv4 +addresses. That means that a sanitizing function that filters out addresses +like 127.0.0.1 is not sufficient \- the equivalent IPv6 addresses \fB::1\fP, +\fB::\fP, \fB0:00::0:1\fP, \fB::127.0.0.1\fP and \fB::ffff:7f00:1\fP supplied +somehow by an attacker would all bypass a naive filter and could allow access +to undesired local resources. IPv6 also has special address blocks like +link\-local and site\-local that generally should not be accessed by a +server\-side libcurl\-using application. A poorly configured firewall installed +in a data center, organization or server may also be configured to limit IPv4 +connections but leave IPv6 connections wide open. In some cases, setting +\fICURLOPT_IPRESOLVE(3)\fP to CURL_IPRESOLVE_V4 can be used to limit resolved +addresses to IPv4 only and bypass these issues. +.SH Uploads +When uploading, a redirect can cause a local (or remote) file to be +overwritten. Applications must not allow any unsanitized URL to be passed in +for uploads. Also, \fICURLOPT_FOLLOWLOCATION(3)\fP should not be used on +uploads. Instead, the applications should consider handling redirects itself, +sanitizing each URL first. +.SH Authentication +Use of \fICURLOPT_UNRESTRICTED_AUTH(3)\fP could cause authentication +information to be sent to an unknown second server. Applications can mitigate +against this by disabling \fICURLOPT_FOLLOWLOCATION(3)\fP and handling +redirects itself, sanitizing where necessary. + +Use of the CURLAUTH_ANY option to \fICURLOPT_HTTPAUTH(3)\fP could result in username +and password being sent in clear text to an HTTP server. Instead, use +CURLAUTH_ANYSAFE which ensures that the password is encrypted over the +network, or else fail the request. + +Use of the CURLUSESSL_TRY option to \fICURLOPT_USE_SSL(3)\fP could result in +username and password being sent in clear text to an FTP server. Instead, use +CURLUSESSL_CONTROL to ensure that an encrypted connection is used or else fail +the request. +.SH Cookies +If cookies are enabled and cached, then a user could craft a URL which +performs some malicious action to a site whose authentication is already +stored in a cookie. E.g. +\fBhttp://mail.example.com/delete\-stuff.cgi?delete=all\fP Applications can +mitigate against this by disabling cookies or clearing them between requests. +.SH Dangerous SCP URLs +SCP URLs can contain raw commands within the scp: URL, which is a side effect +of how the SCP protocol is designed. E.g. +.nf + scp://user:pass@host/a;date >/tmp/test; +.fi +Applications must not allow unsanitized SCP: URLs to be passed in for +downloads. +.SH file:// +By default curl and libcurl support file:// URLs. Such a URL is always an +access, or attempted access, to a local resource. If your application wants to +avoid that, keep control of what URLs to use and/or prevent curl/libcurl from +using the protocol. + +By default, libcurl prohibits redirects to file:// URLs. +.SH Warning: file:// on Windows +The Windows operating system tries automatically, and without any way for +applications to disable it, to establish a connection to another host over the +network and access it (over SMB or other protocols), if only the correct file +path is accessed. + +When first realizing this, the curl team tried to filter out such attempts in +order to protect applications for inadvertent probes of for example internal +networks etc. This resulted in CVE\-2019\-15601 and the associated security fix. + +However, we have since been made aware of the fact that the previous fix was far +from adequate as there are several other ways to accomplish more or less the +same thing: accessing a remote host over the network instead of the local file +system. + +The conclusion we have come to is that this is a weakness or feature in the +Windows operating system itself, that we as an application cannot safely +protect users against. It would just be a whack\-a\-mole race we do not want to +participate in. There are too many ways to do it and there is no knob we can +use to turn off the practice. + +If you use curl or libcurl on Windows (any version), disable the use of the +FILE protocol in curl or be prepared that accesses to a range of "magic paths" +potentially make your system access other hosts on your network. curl cannot +protect you against this. +.SH What if the user can set the URL +Applications may find it tempting to let users set the URL that it can work +on. That is probably fine, but opens up for mischief and trickery that you as +an application author may want to address or take precautions against. + +If your curl\-using script allow a custom URL do you also, perhaps +unintentionally, allow the user to pass other options to the curl command line +if creative use of special characters are applied? + +If the user can set the URL, the user can also specify the scheme part to +other protocols that you did not intend for users to use and perhaps did not +consider. curl supports over 20 different URL schemes. "http://" might be what +you thought, "ftp://" or "imap://" might be what the user gives your +application. Also, cross\-protocol operations might be done by using a +particular scheme in the URL but point to a server doing a different protocol +on a non\-standard port. + +Remedies: +.IP "Use --proto" +curl command lines can use \fI\--proto\fP to limit what URL schemes it accepts +.IP "Use CURLOPT_PROTOCOLS_STR" +libcurl programs can use \fICURLOPT_PROTOCOLS_STR(3)\fP to limit what URL schemes it accepts +.IP "consider not allowing the user to set the full URL" +Maybe just let the user provide data for parts of it? Or maybe filter input to +only allow specific choices? +.SH RFC 3986 vs WHATWG URL +curl supports URLs mostly according to how they are defined in RFC 3986, and +has done so since the beginning. + +Web browsers mostly adhere to the WHATWG URL Specification. + +This deviance makes some URLs copied between browsers (or returned over HTTP +for redirection) and curl not work the same way. It can also cause problems if +an application parses URLs differently from libcurl and makes different +assumptions about a link. This can mislead users into getting the wrong thing, +connecting to the wrong host or otherwise not working identically. + +Within an application, this can be mitigated by always using the +\fIcurl_url(3)\fP API to parse URLs, ensuring that they are parsed the same way +as within libcurl itself. +.SH FTP uses two connections +When performing an FTP transfer, two TCP connections are used: one for setting +up the transfer and one for the actual data. + +FTP is not only unauthenticated, but the setting up of the second transfer is +also a weak spot. The second connection to use for data, is either setup with +the PORT/EPRT command that makes the server connect back to the client on the +given IP+PORT, or with PASV/EPSV that makes the server setup a port to listen +to and tells the client to connect to a given IP+PORT. + +Again, unauthenticated means that the connection might be meddled with by a +man\-in\-the\-middle or that there is a malicious server pretending to be the +right one. + +A malicious FTP server can respond to PASV commands with the IP+PORT of a +totally different machine. Perhaps even a third party host, and when there are +many clients trying to connect to that third party, it could create a +Distributed Denial\-Of\-Service attack out of it. If the client makes an upload +operation, it can make the client send the data to another site. If the +attacker can affect what data the client uploads, it can be made to work as a +HTTP request and then the client could be made to issue HTTP requests to third +party hosts. + +An attacker that manages to control curl\(aqs command line options can tell curl +to send an FTP PORT command to ask the server to connect to a third party host +instead of back to curl. + +The fact that FTP uses two connections makes it vulnerable in a way that is +hard to avoid. +.SH Active FTP passes on the local IP address +If you use curl/libcurl to do \fIactive\fP FTP transfers, curl passes on the +address of your local IP to the remote server \- even when for example using a +SOCKS or HTTP proxy in between curl and the target server. +.SH Denial of Service +A malicious server could cause libcurl to effectively hang by sending data +slowly, or even no data at all but just keeping the TCP connection open. This +could effectively result in a denial\-of\-service attack. The +\fICURLOPT_TIMEOUT(3)\fP and/or \fICURLOPT_LOW_SPEED_LIMIT(3)\fP options can +be used to mitigate against this. + +A malicious server could cause libcurl to download an infinite amount of data, +potentially causing system resources to be exhausted resulting in a system or +application crash. Setting the \fICURLOPT_MAXFILESIZE_LARGE(3)\fP option is not +sufficient to guard against this. Instead, applications should monitor the +amount of data received within the write or progress callback and abort once +the limit is reached. + +A malicious HTTP server could cause an infinite redirection loop, causing a +denial\-of\-service. This can be mitigated by using the +\fICURLOPT_MAXREDIRS(3)\fP option. +.SH Arbitrary Headers +User\-supplied data must be sanitized when used in options like +\fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_HTTPHEADER(3)\fP, +\fICURLOPT_POSTFIELDS(3)\fP and others that are used to generate structured +data. Characters like embedded carriage returns or ampersands could allow the +user to create additional headers or fields that could cause malicious +transactions. +.SH Server-supplied Names +A server can supply data which the application may, in some cases, use as a +filename. The curl command\-line tool does this with \fI\--remote\-header\-name\fP, +using the Content\-disposition: header to generate a filename. An application +could also use \fICURLINFO_EFFECTIVE_URL(3)\fP to generate a filename from a +server\-supplied redirect URL. Special care must be taken to sanitize such +names to avoid the possibility of a malicious server supplying one like +\fB"/etc/passwd"\fP, \fB"autoexec.bat"\fP, \fB"prn:"\fP or even \fB".bashrc"\fP. +.SH Server Certificates +A secure application should never use the \fICURLOPT_SSL_VERIFYPEER(3)\fP +option to disable certificate validation. There are numerous attacks that are +enabled by applications that fail to properly validate server TLS/SSL +certificates, thus enabling a malicious server to spoof a legitimate +one. HTTPS without validated certificates is potentially as insecure as a +plain HTTP connection. +.SH Showing What You Do +Relatedly, be aware that in situations when you have problems with libcurl and +ask someone for help, everything you reveal in order to get best possible help +might also impose certain security related risks. Hostnames, usernames, paths, +operating system specifics, etc. (not to mention passwords of course) may in +fact be used by intruders to gain additional information of a potential +target. + +Be sure to limit access to application logs if they could hold private or +security\-related data. Besides the obvious candidates like usernames and +passwords, things like URLs, cookies or even filenames could also hold +sensitive data. + +To avoid this problem, you must of course use your common sense. Often, you +can just edit out the sensitive data or just search/replace your true +information with faked data. +.SH setuid applications using libcurl +libcurl\-using applications that set the \(aqsetuid\(aq bit to run with elevated or +modified rights also implicitly give that extra power to libcurl and this +should only be done after careful considerations. + +Giving setuid powers to the application means that libcurl can save files using +those new rights (if for example the \fISSLKEYLOGFILE\fP environment variable is +set). Also: if the application wants these powers to read or manage secrets +that the user is otherwise not able to view (like credentials for a login +etc), it should be noted that libcurl still might understand proxy environment +variables that allow the user to redirect libcurl operations to use a proxy +controlled by the user. +.SH File descriptors, fork and NTLM +An application that uses libcurl and invokes \fIfork()\fP gets all file +descriptors duplicated in the child process, including the ones libcurl +created. + +libcurl itself uses \fIfork()\fP and \fIexecl()\fP if told to use the +\fBCURLAUTH_NTLM_WB\fP authentication method which then invokes the helper +command in a child process with file descriptors duplicated. Make sure that +only the trusted and reliable helper program is invoked! + +This feature was removed from curl in 8.8.0. +.SH Secrets in memory +When applications pass usernames, passwords or other sensitive data to +libcurl to be used for upcoming transfers, those secrets are kept around as\-is +in memory. In many cases they are stored in the heap for as long as the handle +itself for which the options are set. + +If an attacker can access the heap, like maybe by reading swap space or via a +core dump file, such data might be accessible. + +Further, when eventually closing a handle and the secrets are no longer +needed, libcurl does not explicitly clear memory before freeing it, so +credentials may be left in freed data. +.SH Saving files +libcurl cannot protect against attacks where an attacker has write access to +the same directory where libcurl is directed to save files. +.SH Cookies +If libcurl is built with PSL (\fBPublic Suffix List\fP) support, it detects and +discards cookies that are specified for such suffix domains that should not be +allowed to have cookies. + +if libcurl is \fInot\fP built with PSL support, it has no ability to stop super +cookies. +.SH Report Security Problems +Should you detect or just suspect a security problem in libcurl or curl, +contact the project curl security team immediately. See +https://curl.se/dev/secprocess.html for details. +.SH SEE ALSO +.BR libcurl-thread (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-share.3 b/3rdparty/curl/share/man/man3/libcurl-share.3 new file mode 100644 index 0000000..eecfe82 --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-share.3 @@ -0,0 +1,47 @@ +.\" generated by cd2nroff 0.1 from libcurl-share.md +.TH libcurl-share 3 "2024-10-11" libcurl +.SH NAME +libcurl\-share \- how to use the share interface +.SH DESCRIPTION +This is an overview on how to use the libcurl share interface in your C +programs. There are specific man pages for each function mentioned in +here. + +All functions in the share interface are prefixed with curl_share. +.SH OBJECTIVES +The share interface was added to enable sharing of data between curl handles. +.SH ONE SET OF DATA - MANY TRANSFERS +You can have multiple easy handles share data between them. Have them update +and use the \fBsame\fP cookie database, DNS cache, TLS session cache and/or +connection cache! This way, each single transfer takes advantage from data +updates made by the other transfer(s). +.SH SHARE OBJECT +You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle +for a newly created one. + +You tell the shared object what data you want it to share by using +\fIcurl_share_setopt(3)\fP. + +Since you can use this share from multiple threads, and libcurl has no +internal thread synchronization, you must provide mutex callbacks if you are +using this multi\-threaded. You set lock and unlock functions with +\fIcurl_share_setopt(3)\fP too. + +Then, you make an easy handle to use this share, you set the +\fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, and pass in +share handle. You can make any number of easy handles share the same share +handle. + +To make an easy handle stop using that particular share, you set +\fICURLOPT_SHARE(3)\fP to NULL for that easy handle. To make a handle stop +sharing a particular data, you can \fICURLSHOPT_UNSHARE(3)\fP it. + +When you are done using the share, make sure that no easy handle is still using +it, and call \fIcurl_share_cleanup(3)\fP on the handle. +.SH SEE ALSO +.BR curl_share_cleanup (3), +.BR curl_share_init (3), +.BR curl_share_setopt (3), +.BR libcurl-easy (3), +.BR libcurl-errors (3), +.BR libcurl-multi (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-symbols.3 b/3rdparty/curl/share/man/man3/libcurl-symbols.3 new file mode 100644 index 0000000..2f38fc5 --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-symbols.3 @@ -0,0 +1,2289 @@ +.\" generated by cd2nroff 0.1 from libcurl-symbols.md +.TH libcurl-symbols 3 "2024-10-11" libcurl +.SH libcurl symbols +This man page details version information for public symbols provided in the +libcurl header files. This lists the first version in which the symbol was +introduced and for some symbols two additional information pieces: + +The first version in which the symbol is marked "deprecated" \- meaning that +since that version no new code should be written to use the symbol as it is +marked for getting removed in a future. + +The last version that featured the specific symbol. Using the symbol in source +code makes it no longer compile error\-free after that specified version. + +This man page is automatically generated from the symbols\-in\-versions file. +.IP CURL_AT_LEAST_VERSION +Introduced in 7.43.0. +.IP CURL_BLOB_COPY +Introduced in 7.71.0. +.IP CURL_BLOB_NOCOPY +Introduced in 7.71.0. +.IP CURL_CHUNK_BGN_FUNC_FAIL +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURL_CHUNK_BGN_FUNC_OK +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURL_CHUNK_BGN_FUNC_SKIP +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURL_CHUNK_END_FUNC_FAIL +Introduced in 7.21.0. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP. +.IP CURL_CHUNK_END_FUNC_OK +Introduced in 7.21.0. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP. +.IP CURL_CSELECT_ERR +Introduced in 7.16.3. See \fIcurl_multi_socket_action(3)\fP. +.IP CURL_CSELECT_IN +Introduced in 7.16.3. See \fIcurl_multi_socket_action(3)\fP. +.IP CURL_CSELECT_OUT +Introduced in 7.16.3. See \fIcurl_multi_socket_action(3)\fP. +.IP CURL_DEPRECATED +Introduced in 7.87.0. +.IP CURL_DID_MEMORY_FUNC_TYPEDEFS +Introduced in 7.49.0. +.IP CURL_EASY_NONE +Introduced in 7.14.0. Last used in 7.15.4. +.IP CURL_EASY_TIMEOUT +Introduced in 7.14.0. Last used in 7.15.4. +.IP CURL_ERROR_SIZE +Introduced in 7.1. +.IP CURL_FNMATCHFUNC_FAIL +Introduced in 7.21.0. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP. +.IP CURL_FNMATCHFUNC_MATCH +Introduced in 7.21.0. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP. +.IP CURL_FNMATCHFUNC_NOMATCH +Introduced in 7.21.0. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP. +.IP CURL_FORMADD_DISABLED +Introduced in 7.12.1. Deprecated since 7.56.0. +.IP CURL_FORMADD_ILLEGAL_ARRAY +Introduced in 7.9.8. Deprecated since 7.56.0. +.IP CURL_FORMADD_INCOMPLETE +Introduced in 7.9.8. Deprecated since 7.56.0. +.IP CURL_FORMADD_MEMORY +Introduced in 7.9.8. Deprecated since 7.56.0. +.IP CURL_FORMADD_NULL +Introduced in 7.9.8. Deprecated since 7.56.0. +.IP CURL_FORMADD_OK +Introduced in 7.9.8. Deprecated since 7.56.0. +.IP CURL_FORMADD_OPTION_TWICE +Introduced in 7.9.8. Deprecated since 7.56.0. +.IP CURL_FORMADD_UNKNOWN_OPTION +Introduced in 7.9.8. Deprecated since 7.56.0. +.IP CURL_GLOBAL_ACK_EINTR +Introduced in 7.30.0. See \fIcurl_global_init(3)\fP. +.IP CURL_GLOBAL_ALL +Introduced in 7.8. See \fIcurl_global_init(3)\fP. +.IP CURL_GLOBAL_DEFAULT +Introduced in 7.8. See \fIcurl_global_init(3)\fP. +.IP CURL_GLOBAL_NOTHING +Introduced in 7.8. See \fIcurl_global_init(3)\fP. +.IP CURL_GLOBAL_SSL +Introduced in 7.8. See \fIcurl_global_init(3)\fP. +.IP CURL_GLOBAL_WIN32 +Introduced in 7.8.1. See \fIcurl_global_init(3)\fP. +.IP CURL_HET_DEFAULT +Introduced in 7.59.0. See \fICURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)\fP. +.IP CURL_HTTP_VERSION_1_0 +Introduced in 7.9.1. See \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURL_HTTP_VERSION_1_1 +Introduced in 7.9.1. See \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURL_HTTP_VERSION_2 +Introduced in 7.43.0. See \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURL_HTTP_VERSION_2_0 +Introduced in 7.33.0. See \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE +Introduced in 7.49.0. See \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURL_HTTP_VERSION_2TLS +Introduced in 7.47.0. See \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURL_HTTP_VERSION_3 +Introduced in 7.66.0. See \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURL_HTTP_VERSION_3ONLY +Introduced in 7.88.0. See \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURL_HTTP_VERSION_NONE +Introduced in 7.9.1. See \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURL_HTTPPOST_BUFFER +Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. +.IP CURL_HTTPPOST_CALLBACK +Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. +.IP CURL_HTTPPOST_FILENAME +Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. +.IP CURL_HTTPPOST_LARGE +Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. +.IP CURL_HTTPPOST_PTRBUFFER +Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. +.IP CURL_HTTPPOST_PTRCONTENTS +Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. +.IP CURL_HTTPPOST_PTRNAME +Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. +.IP CURL_HTTPPOST_READFILE +Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. +.IP CURL_IGNORE_DEPRECATION +Introduced in 7.87.0. +.IP CURL_IPRESOLVE_V4 +Introduced in 7.10.8. See \fICURLOPT_IPRESOLVE(3)\fP. +.IP CURL_IPRESOLVE_V6 +Introduced in 7.10.8. See \fICURLOPT_IPRESOLVE(3)\fP. +.IP CURL_IPRESOLVE_WHATEVER +Introduced in 7.10.8. See \fICURLOPT_IPRESOLVE(3)\fP. +.IP CURL_ISOCPP +Introduced in 7.10.2. +.IP CURL_LOCK_ACCESS_NONE +Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_ACCESS_SHARED +Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_ACCESS_SINGLE +Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_DATA_CONNECT +Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_DATA_COOKIE +Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_DATA_DNS +Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_DATA_HSTS +Introduced in 7.88.0. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_DATA_NONE +Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_DATA_PSL +Introduced in 7.61.0. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_DATA_SHARE +Introduced in 7.10.4. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_DATA_SSL_SESSION +Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURL_LOCK_TYPE_CONNECT +Introduced in 7.10. Last used in 7.10.2. +.IP CURL_LOCK_TYPE_COOKIE +Introduced in 7.10. Last used in 7.10.2. +.IP CURL_LOCK_TYPE_DNS +Introduced in 7.10. Last used in 7.10.2. +.IP CURL_LOCK_TYPE_NONE +Introduced in 7.10. Last used in 7.10.2. +.IP CURL_LOCK_TYPE_SSL_SESSION +Introduced in 7.10. Last used in 7.10.2. +.IP CURL_MAX_HTTP_HEADER +Introduced in 7.19.7. +.IP CURL_MAX_READ_SIZE +Introduced in 7.53.0. +.IP CURL_MAX_WRITE_SIZE +Introduced in 7.9.7. +.IP CURL_NETRC_IGNORED +Introduced in 7.9.8. +.IP CURL_NETRC_OPTIONAL +Introduced in 7.9.8. +.IP CURL_NETRC_REQUIRED +Introduced in 7.9.8. +.IP CURL_POLL_IN +Introduced in 7.14.0. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. +.IP CURL_POLL_INOUT +Introduced in 7.14.0. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. +.IP CURL_POLL_NONE +Introduced in 7.14.0. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. +.IP CURL_POLL_OUT +Introduced in 7.14.0. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. +.IP CURL_POLL_REMOVE +Introduced in 7.14.0. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. +.IP CURL_PREREQFUNC_ABORT +Introduced in 7.79.0. +.IP CURL_PREREQFUNC_OK +Introduced in 7.79.0. +.IP CURL_PROGRESS_BAR +Introduced in 7.1.1. Last used in 7.4.1. +.IP CURL_PROGRESS_STATS +Introduced in 7.1.1. Last used in 7.4.1. +.IP CURL_PROGRESSFUNC_CONTINUE +Introduced in 7.68.0. +.IP CURL_PULL_SYS_POLL_H +Introduced in 7.56.0. +.IP CURL_PUSH_DENY +Introduced in 7.44.0. +.IP CURL_PUSH_ERROROUT +Introduced in 7.72.0. +.IP CURL_PUSH_OK +Introduced in 7.44.0. +.IP CURL_READFUNC_ABORT +Introduced in 7.12.1. +.IP CURL_READFUNC_PAUSE +Introduced in 7.18.0. +.IP CURL_REDIR_GET_ALL +Introduced in 7.19.1. +.IP CURL_REDIR_POST_301 +Introduced in 7.19.1. See \fICURLOPT_POSTREDIR(3)\fP. +.IP CURL_REDIR_POST_302 +Introduced in 7.19.1. See \fICURLOPT_POSTREDIR(3)\fP. +.IP CURL_REDIR_POST_303 +Introduced in 7.25.1. See \fICURLOPT_POSTREDIR(3)\fP. +.IP CURL_REDIR_POST_ALL +Introduced in 7.19.1. See \fICURLOPT_POSTREDIR(3)\fP. +.IP CURL_RTSPREQ_ANNOUNCE +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_RTSPREQ_DESCRIBE +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_RTSPREQ_GET_PARAMETER +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_RTSPREQ_NONE +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_RTSPREQ_OPTIONS +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_RTSPREQ_PAUSE +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_RTSPREQ_PLAY +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_RTSPREQ_RECEIVE +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_RTSPREQ_RECORD +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_RTSPREQ_SET_PARAMETER +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_RTSPREQ_SETUP +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_RTSPREQ_TEARDOWN +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURL_SEEKFUNC_CANTSEEK +Introduced in 7.19.5. See \fICURLOPT_SEEKFUNCTION(3)\fP. +.IP CURL_SEEKFUNC_FAIL +Introduced in 7.19.5. See \fICURLOPT_SEEKFUNCTION(3)\fP. +.IP CURL_SEEKFUNC_OK +Introduced in 7.19.5. See \fICURLOPT_SEEKFUNCTION(3)\fP. +.IP CURL_SOCKET_BAD +Introduced in 7.14.0. +.IP CURL_SOCKET_TIMEOUT +Introduced in 7.14.0. +.IP CURL_SOCKOPT_ALREADY_CONNECTED +Introduced in 7.21.5. +.IP CURL_SOCKOPT_ERROR +Introduced in 7.21.5. +.IP CURL_SOCKOPT_OK +Introduced in 7.21.5. +.IP CURL_SSLVERSION_DEFAULT +Introduced in 7.9.2. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_MAX_DEFAULT +Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_MAX_NONE +Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_MAX_TLSv1_0 +Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_MAX_TLSv1_1 +Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_MAX_TLSv1_2 +Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_MAX_TLSv1_3 +Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_SSLv2 +Introduced in 7.9.2. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_SSLv3 +Introduced in 7.9.2. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_TLSv1 +Introduced in 7.9.2. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_TLSv1_0 +Introduced in 7.34.0. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_TLSv1_1 +Introduced in 7.34.0. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_TLSv1_2 +Introduced in 7.34.0. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_SSLVERSION_TLSv1_3 +Introduced in 7.52.0. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURL_STRICTER +Introduced in 7.50.2. +.IP CURL_TIMECOND_IFMODSINCE +Introduced in 7.9.7. See \fICURLOPT_TIMECONDITION(3)\fP. +.IP CURL_TIMECOND_IFUNMODSINCE +Introduced in 7.9.7. See \fICURLOPT_TIMECONDITION(3)\fP. +.IP CURL_TIMECOND_LASTMOD +Introduced in 7.9.7. See \fICURLOPT_TIMECONDITION(3)\fP. +.IP CURL_TIMECOND_NONE +Introduced in 7.9.7. See \fICURLOPT_TIMECONDITION(3)\fP. +.IP CURL_TLSAUTH_NONE +Introduced in 7.21.4. +.IP CURL_TLSAUTH_SRP +Introduced in 7.21.4. +.IP CURL_TRAILERFUNC_ABORT +Introduced in 7.64.0. See \fICURLOPT_TRAILERFUNCTION(3)\fP. +.IP CURL_TRAILERFUNC_OK +Introduced in 7.64.0. See \fICURLOPT_TRAILERFUNCTION(3)\fP. +.IP CURL_UPKEEP_INTERVAL_DEFAULT +Introduced in 7.62.0. +.IP CURL_VERSION_ALTSVC +Introduced in 7.64.1. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_ASYNCHDNS +Introduced in 7.10.7. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_BITS +Introduced in 7.43.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_BROTLI +Introduced in 7.57.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_CONV +Introduced in 7.15.4. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_CURLDEBUG +Introduced in 7.19.6. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_DEBUG +Introduced in 7.10.6. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_GSASL +Introduced in 7.76.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_GSSAPI +Introduced in 7.38.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_GSSNEGOTIATE +Introduced in 7.10.6. Deprecated since 7.38.0. +.IP CURL_VERSION_HSTS +Introduced in 7.74.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_HTTP2 +Introduced in 7.33.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_HTTP3 +Introduced in 7.66.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_HTTPS_PROXY +Introduced in 7.52.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_IDN +Introduced in 7.12.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_IPV6 +Introduced in 7.10. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_KERBEROS4 +Introduced in 7.10. Deprecated since 7.33.0. +.IP CURL_VERSION_KERBEROS5 +Introduced in 7.40.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_LARGEFILE +Introduced in 7.11.1. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_LIBZ +Introduced in 7.10. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_MULTI_SSL +Introduced in 7.56.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_NTLM +Introduced in 7.10.6. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_NTLM_WB +Introduced in 7.22.0. Deprecated since 8.8.0. +.IP CURL_VERSION_PSL +Introduced in 7.47.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_SPNEGO +Introduced in 7.10.8. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_SSL +Introduced in 7.10. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_SSPI +Introduced in 7.13.2. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_THREADSAFE +Introduced in 7.84.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_TLSAUTH_SRP +Introduced in 7.21.4. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_UNICODE +Introduced in 7.72.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_UNIX_SOCKETS +Introduced in 7.40.0. See \fIcurl_version_info(3)\fP. +.IP CURL_VERSION_ZSTD +Introduced in 7.72.0. See \fIcurl_version_info(3)\fP. +.IP CURL_WAIT_POLLIN +Introduced in 7.28.0. +.IP CURL_WAIT_POLLOUT +Introduced in 7.28.0. +.IP CURL_WAIT_POLLPRI +Introduced in 7.28.0. +.IP CURL_WIN32 +Introduced in 7.69.0. Last used in 8.5.0. +.IP CURL_WRITEFUNC_ERROR +Introduced in 7.87.0. +.IP CURL_WRITEFUNC_PAUSE +Introduced in 7.18.0. +.IP CURL_ZERO_TERMINATED +Introduced in 7.56.0. +.IP CURLALTSVC_H1 +Introduced in 7.64.1. See \fICURLOPT_ALTSVC_CTRL(3)\fP. +.IP CURLALTSVC_H2 +Introduced in 7.64.1. See \fICURLOPT_ALTSVC_CTRL(3)\fP. +.IP CURLALTSVC_H3 +Introduced in 7.64.1. See \fICURLOPT_ALTSVC_CTRL(3)\fP. +.IP CURLALTSVC_READONLYFILE +Introduced in 7.64.1. See \fICURLOPT_ALTSVC_CTRL(3)\fP. +.IP CURLAUTH_ANY +Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLAUTH_ANYSAFE +Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLAUTH_AWS_SIGV4 +Introduced in 7.75.0. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLAUTH_BASIC +Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLAUTH_BEARER +Introduced in 7.61.0. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLAUTH_DIGEST +Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLAUTH_DIGEST_IE +Introduced in 7.19.3. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLAUTH_GSSAPI +Introduced in 7.55.0. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLAUTH_GSSNEGOTIATE +Introduced in 7.10.6. Deprecated since 7.38.0. +.IP CURLAUTH_NEGOTIATE +Introduced in 7.38.0. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLAUTH_NONE +Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLAUTH_NTLM +Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLAUTH_NTLM_WB +Introduced in 7.22.0. Deprecated since 8.8.0. +.IP CURLAUTH_ONLY +Introduced in 7.21.3. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLCLOSEPOLICY_CALLBACK +Introduced in 7.7. Deprecated since 7.16.1. +.IP CURLCLOSEPOLICY_LEAST_RECENTLY_USED +Introduced in 7.7. Deprecated since 7.16.1. +.IP CURLCLOSEPOLICY_LEAST_TRAFFIC +Introduced in 7.7. Deprecated since 7.16.1. +.IP CURLCLOSEPOLICY_NONE +Introduced in 7.7. Deprecated since 7.16.1. +.IP CURLCLOSEPOLICY_OLDEST +Introduced in 7.7. Deprecated since 7.16.1. +.IP CURLCLOSEPOLICY_SLOWEST +Introduced in 7.7. Deprecated since 7.16.1. +.IP CURLE_ABORTED_BY_CALLBACK +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_AGAIN +Introduced in 7.18.2. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_ALREADY_COMPLETE +Introduced in 7.7.2. Deprecated since 7.8. +.IP CURLE_AUTH_ERROR +Introduced in 7.66.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_BAD_CALLING_ORDER +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_BAD_CONTENT_ENCODING +Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_BAD_DOWNLOAD_RESUME +Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_BAD_FUNCTION_ARGUMENT +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_BAD_PASSWORD_ENTERED +Introduced in 7.4.2. Deprecated since 7.17.0. +.IP CURLE_CHUNK_FAILED +Introduced in 7.21.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_CONV_FAILED +Introduced in 7.15.4. Deprecated since 7.82.0. +.IP CURLE_CONV_REQD +Introduced in 7.15.4. Deprecated since 7.82.0. +.IP CURLE_COULDNT_CONNECT +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_COULDNT_RESOLVE_HOST +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_COULDNT_RESOLVE_PROXY +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FAILED_INIT +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FILE_COULDNT_READ_FILE +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FILESIZE_EXCEEDED +Introduced in 7.10.8. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_ACCEPT_FAILED +Introduced in 7.24.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_ACCEPT_TIMEOUT +Introduced in 7.24.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_ACCESS_DENIED +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_FTP_BAD_DOWNLOAD_RESUME +Introduced in 7.1. Deprecated since 7.1. +.IP CURLE_FTP_BAD_FILE_LIST +Introduced in 7.21.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_CANT_GET_HOST +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_CANT_RECONNECT +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_FTP_COULDNT_GET_SIZE +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_FTP_COULDNT_RETR_FILE +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_COULDNT_SET_ASCII +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_FTP_COULDNT_SET_BINARY +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_FTP_COULDNT_SET_TYPE +Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_COULDNT_STOR_FILE +Introduced in 7.1. Deprecated since 7.16.3. +.IP CURLE_FTP_COULDNT_USE_REST +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_PARTIAL_FILE +Introduced in 7.1. Deprecated since 7.1. +.IP CURLE_FTP_PORT_FAILED +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_PRET_FAILED +Introduced in 7.20.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_QUOTE_ERROR +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_FTP_SSL_FAILED +Introduced in 7.11.0. Deprecated since 7.17.0. +.IP CURLE_FTP_USER_PASSWORD_INCORRECT +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_FTP_WEIRD_227_FORMAT +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_WEIRD_PASS_REPLY +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_WEIRD_PASV_REPLY +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_FTP_WEIRD_SERVER_REPLY +Introduced in 7.1. Deprecated since 7.51.0. +.IP CURLE_FTP_WEIRD_USER_REPLY +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_FTP_WRITE_ERROR +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_FUNCTION_NOT_FOUND +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_GOT_NOTHING +Introduced in 7.9.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_HTTP2 +Introduced in 7.38.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_HTTP2_STREAM +Introduced in 7.49.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_HTTP3 +Introduced in 7.68.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_HTTP_NOT_FOUND +Introduced in 7.1. Deprecated since 7.10.3. +.IP CURLE_HTTP_PORT_FAILED +Introduced in 7.3. Deprecated since 7.12.0. +.IP CURLE_HTTP_POST_ERROR +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_HTTP_RANGE_ERROR +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_HTTP_RETURNED_ERROR +Introduced in 7.10.3. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_INTERFACE_FAILED +Introduced in 7.12.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_LDAP_CANNOT_BIND +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_LDAP_INVALID_URL +Introduced in 7.10.8. Deprecated since 7.82.0. +.IP CURLE_LDAP_SEARCH_FAILED +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_LIBRARY_NOT_FOUND +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_LOGIN_DENIED +Introduced in 7.13.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_MALFORMAT_USER +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_NO_CONNECTION_AVAILABLE +Introduced in 7.30.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_NOT_BUILT_IN +Introduced in 7.21.5. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_OK +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_OPERATION_TIMEDOUT +Introduced in 7.10.2. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_OPERATION_TIMEOUTED +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_OUT_OF_MEMORY +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_PARTIAL_FILE +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_PEER_FAILED_VERIFICATION +Introduced in 7.17.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_PROXY +Introduced in 7.73.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_QUIC_CONNECT_ERROR +Introduced in 7.69.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_QUOTE_ERROR +Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_RANGE_ERROR +Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_READ_ERROR +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_RECURSIVE_API_CALL +Introduced in 7.59.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_RECV_ERROR +Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_REMOTE_ACCESS_DENIED +Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_REMOTE_DISK_FULL +Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_REMOTE_FILE_EXISTS +Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_REMOTE_FILE_NOT_FOUND +Introduced in 7.16.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_RTSP_CSEQ_ERROR +Introduced in 7.20.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_RTSP_SESSION_ERROR +Introduced in 7.20.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SEND_ERROR +Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SEND_FAIL_REWIND +Introduced in 7.12.3. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SETOPT_OPTION_SYNTAX +Introduced in 7.78.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SHARE_IN_USE +Introduced in 7.9.6. Deprecated since 7.17.0. +.IP CURLE_SSH +Introduced in 7.16.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_CACERT +Introduced in 7.10. Deprecated since 7.62.0. +.IP CURLE_SSL_CACERT_BADFILE +Introduced in 7.16.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_CERTPROBLEM +Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_CIPHER +Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_CLIENTCERT +Introduced in 7.77.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_CONNECT_ERROR +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_CRL_BADFILE +Introduced in 7.19.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_ENGINE_INITFAILED +Introduced in 7.12.3. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_ENGINE_NOTFOUND +Introduced in 7.9.3. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_ENGINE_SETFAILED +Introduced in 7.9.3. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_INVALIDCERTSTATUS +Introduced in 7.41.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_ISSUER_ERROR +Introduced in 7.19.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_PEER_CERTIFICATE +Introduced in 7.8. Deprecated since 7.17.1. +.IP CURLE_SSL_PINNEDPUBKEYNOTMATCH +Introduced in 7.39.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_SSL_SHUTDOWN_FAILED +Introduced in 7.16.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_TELNET_OPTION_SYNTAX +Introduced in 7.7. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_TFTP_DISKFULL +Introduced in 7.15.0. Deprecated since 7.17.0. +.IP CURLE_TFTP_EXISTS +Introduced in 7.15.0. Deprecated since 7.17.0. +.IP CURLE_TFTP_ILLEGAL +Introduced in 7.15.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_TFTP_NOSUCHUSER +Introduced in 7.15.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_TFTP_NOTFOUND +Introduced in 7.15.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_TFTP_PERM +Introduced in 7.15.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_TFTP_UNKNOWNID +Introduced in 7.15.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_TOO_LARGE +Introduced in 8.6.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_TOO_MANY_REDIRECTS +Introduced in 7.5. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_UNKNOWN_OPTION +Introduced in 7.21.5. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_UNKNOWN_TELNET_OPTION +Introduced in 7.7. Deprecated since 7.21.5. +.IP CURLE_UNRECOVERABLE_POLL +Introduced in 7.84.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_UNSUPPORTED_PROTOCOL +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_UPLOAD_FAILED +Introduced in 7.16.3. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_URL_MALFORMAT +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_URL_MALFORMAT_USER +Introduced in 7.1. Deprecated since 7.17.0. +.IP CURLE_USE_SSL_FAILED +Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_WEIRD_SERVER_REPLY +Introduced in 7.51.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_WRITE_ERROR +Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLE_ECH_REQUIRED +Introduced in 8.8.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLFILETYPE_DEVICE_BLOCK +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFILETYPE_DEVICE_CHAR +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFILETYPE_DIRECTORY +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFILETYPE_DOOR +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFILETYPE_FILE +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFILETYPE_NAMEDPIPE +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFILETYPE_SOCKET +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFILETYPE_SYMLINK +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFILETYPE_UNKNOWN +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFINFOFLAG_KNOWN_FILENAME +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFINFOFLAG_KNOWN_FILETYPE +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFINFOFLAG_KNOWN_GID +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFINFOFLAG_KNOWN_HLINKCOUNT +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFINFOFLAG_KNOWN_PERM +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFINFOFLAG_KNOWN_SIZE +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFINFOFLAG_KNOWN_TIME +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFINFOFLAG_KNOWN_UID +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLFORM_ARRAY +Introduced in 7.9.1. Deprecated since 7.56.0. +.IP CURLFORM_ARRAY_END +Introduced in 7.9.1. Deprecated since 7.9.5. +.IP CURLFORM_ARRAY_START +Introduced in 7.9.1. Deprecated since 7.9.5. +.IP CURLFORM_BUFFER +Introduced in 7.9.8. Deprecated since 7.56.0. +.IP CURLFORM_BUFFERLENGTH +Introduced in 7.9.8. Deprecated since 7.56.0. +.IP CURLFORM_BUFFERPTR +Introduced in 7.9.8. Deprecated since 7.56.0. +.IP CURLFORM_CONTENTHEADER +Introduced in 7.9.3. Deprecated since 7.56.0. +.IP CURLFORM_CONTENTLEN +Introduced in 7.46.0. Deprecated since 7.56.0. +.IP CURLFORM_CONTENTSLENGTH +Introduced in 7.9. Deprecated since 7.56.0. +.IP CURLFORM_CONTENTTYPE +Introduced in 7.9. Deprecated since 7.56.0. +.IP CURLFORM_COPYCONTENTS +Introduced in 7.9. Deprecated since 7.56.0. +.IP CURLFORM_COPYNAME +Introduced in 7.9. Deprecated since 7.56.0. +.IP CURLFORM_END +Introduced in 7.9. Deprecated since 7.56.0. +.IP CURLFORM_FILE +Introduced in 7.9. Deprecated since 7.56.0. +.IP CURLFORM_FILECONTENT +Introduced in 7.9.1. Deprecated since 7.56.0. +.IP CURLFORM_FILENAME +Introduced in 7.9.6. Deprecated since 7.56.0. +.IP CURLFORM_NAMELENGTH +Introduced in 7.9. Deprecated since 7.56.0. +.IP CURLFORM_NOTHING +Introduced in 7.9. Deprecated since 7.56.0. +.IP CURLFORM_PTRCONTENTS +Introduced in 7.9. Deprecated since 7.56.0. +.IP CURLFORM_PTRNAME +Introduced in 7.9. Deprecated since 7.56.0. +.IP CURLFORM_STREAM +Introduced in 7.18.2. Deprecated since 7.56.0. +.IP CURLFTP_CREATE_DIR +Introduced in 7.19.4. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP. +.IP CURLFTP_CREATE_DIR_NONE +Introduced in 7.19.4. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP. +.IP CURLFTP_CREATE_DIR_RETRY +Introduced in 7.19.4. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP. +.IP CURLFTPAUTH_DEFAULT +Introduced in 7.12.2. See \fICURLOPT_FTPSSLAUTH(3)\fP. +.IP CURLFTPAUTH_SSL +Introduced in 7.12.2. See \fICURLOPT_FTPSSLAUTH(3)\fP. +.IP CURLFTPAUTH_TLS +Introduced in 7.12.2. See \fICURLOPT_FTPSSLAUTH(3)\fP. +.IP CURLFTPMETHOD_DEFAULT +Introduced in 7.15.3. See \fICURLOPT_FTP_FILEMETHOD(3)\fP. +.IP CURLFTPMETHOD_MULTICWD +Introduced in 7.15.3. See \fICURLOPT_FTP_FILEMETHOD(3)\fP. +.IP CURLFTPMETHOD_NOCWD +Introduced in 7.15.3. See \fICURLOPT_FTP_FILEMETHOD(3)\fP. +.IP CURLFTPMETHOD_SINGLECWD +Introduced in 7.15.3. See \fICURLOPT_FTP_FILEMETHOD(3)\fP. +.IP CURLFTPSSL_ALL +Introduced in 7.11.0. Deprecated since 7.17.0. +.IP CURLFTPSSL_CCC_ACTIVE +Introduced in 7.16.2. See \fICURLOPT_USE_SSL(3)\fP. +.IP CURLFTPSSL_CCC_NONE +Introduced in 7.16.2. See \fICURLOPT_USE_SSL(3)\fP. +.IP CURLFTPSSL_CCC_PASSIVE +Introduced in 7.16.1. See \fICURLOPT_USE_SSL(3)\fP. +.IP CURLFTPSSL_CONTROL +Introduced in 7.11.0. Deprecated since 7.17.0. +.IP CURLFTPSSL_NONE +Introduced in 7.11.0. Deprecated since 7.17.0. +.IP CURLFTPSSL_TRY +Introduced in 7.11.0. Deprecated since 7.17.0. +.IP CURLGSSAPI_DELEGATION_FLAG +Introduced in 7.22.0. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP. +.IP CURLGSSAPI_DELEGATION_NONE +Introduced in 7.22.0. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP. +.IP CURLGSSAPI_DELEGATION_POLICY_FLAG +Introduced in 7.22.0. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP. +.IP CURLH_1XX +Introduced in 7.83.0. See \fIcurl_easy_header(3)\fP. +.IP CURLH_CONNECT +Introduced in 7.83.0. See \fIcurl_easy_header(3)\fP. +.IP CURLH_HEADER +Introduced in 7.83.0. See \fIcurl_easy_header(3)\fP. +.IP CURLH_PSEUDO +Introduced in 7.83.0. See \fIcurl_easy_header(3)\fP. +.IP CURLH_TRAILER +Introduced in 7.83.0. See \fIcurl_easy_header(3)\fP. +.IP CURLHE_BAD_ARGUMENT +Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLHE_BADINDEX +Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLHE_MISSING +Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLHE_NOHEADERS +Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLHE_NOREQUEST +Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLHE_NOT_BUILT_IN +Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLHE_OK +Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLHE_OUT_OF_MEMORY +Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLHEADER_SEPARATE +Introduced in 7.37.0. See \fICURLOPT_HEADEROPT(3)\fP. +.IP CURLHEADER_UNIFIED +Introduced in 7.37.0. See \fICURLOPT_HEADEROPT(3)\fP. +.IP CURLHSTS_ENABLE +Introduced in 7.74.0. See \fICURLOPT_HSTS_CTRL(3)\fP. +.IP CURLHSTS_READONLYFILE +Introduced in 7.74.0. See \fICURLOPT_HSTS_CTRL(3)\fP. +.IP CURLINFO_ACTIVESOCKET +Introduced in 7.45.0. +.IP CURLINFO_APPCONNECT_TIME +Introduced in 7.19.0. +.IP CURLINFO_APPCONNECT_TIME_T +Introduced in 7.61.0. +.IP CURLINFO_CAINFO +Introduced in 7.84.0. +.IP CURLINFO_CAPATH +Introduced in 7.84.0. +.IP CURLINFO_CERTINFO +Introduced in 7.19.1. +.IP CURLINFO_CONDITION_UNMET +Introduced in 7.19.4. +.IP CURLINFO_CONN_ID +Introduced in 8.2.0. +.IP CURLINFO_CONNECT_TIME +Introduced in 7.4.1. +.IP CURLINFO_CONNECT_TIME_T +Introduced in 7.61.0. +.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD +Introduced in 7.6.1. Deprecated since 7.55.0. +.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD_T +Introduced in 7.55.0. +.IP CURLINFO_CONTENT_LENGTH_UPLOAD +Introduced in 7.6.1. Deprecated since 7.55.0. +.IP CURLINFO_CONTENT_LENGTH_UPLOAD_T +Introduced in 7.55.0. +.IP CURLINFO_CONTENT_TYPE +Introduced in 7.9.4. +.IP CURLINFO_COOKIELIST +Introduced in 7.14.1. +.IP CURLINFO_DATA_IN +Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. +.IP CURLINFO_DATA_OUT +Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. +.IP CURLINFO_DOUBLE +Introduced in 7.4.1. +.IP CURLINFO_EFFECTIVE_METHOD +Introduced in 7.72.0. +.IP CURLINFO_EFFECTIVE_URL +Introduced in 7.4. +.IP CURLINFO_END +Introduced in 7.9.6. +.IP CURLINFO_FILETIME +Introduced in 7.5. +.IP CURLINFO_FILETIME_T +Introduced in 7.59.0. +.IP CURLINFO_FTP_ENTRY_PATH +Introduced in 7.15.4. +.IP CURLINFO_HEADER_IN +Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. +.IP CURLINFO_HEADER_OUT +Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. +.IP CURLINFO_HEADER_SIZE +Introduced in 7.4.1. +.IP CURLINFO_HTTP_CODE +Introduced in 7.4.1. Deprecated since 7.10.8. +.IP CURLINFO_HTTP_CONNECTCODE +Introduced in 7.10.7. +.IP CURLINFO_HTTP_VERSION +Introduced in 7.50.0. +.IP CURLINFO_HTTPAUTH_AVAIL +Introduced in 7.10.8. +.IP CURLINFO_LASTONE +Introduced in 7.4.1. +.IP CURLINFO_LASTSOCKET +Introduced in 7.15.2. Deprecated since 7.45.0. +.IP CURLINFO_LOCAL_IP +Introduced in 7.21.0. +.IP CURLINFO_LOCAL_PORT +Introduced in 7.21.0. +.IP CURLINFO_LONG +Introduced in 7.4.1. +.IP CURLINFO_MASK +Introduced in 7.4.1. +.IP CURLINFO_NAMELOOKUP_TIME +Introduced in 7.4.1. +.IP CURLINFO_NAMELOOKUP_TIME_T +Introduced in 7.61.0. +.IP CURLINFO_NONE +Introduced in 7.4.1. +.IP CURLINFO_NUM_CONNECTS +Introduced in 7.12.3. +.IP CURLINFO_OFF_T +Introduced in 7.55.0. +.IP CURLINFO_OS_ERRNO +Introduced in 7.12.2. +.IP CURLINFO_PRETRANSFER_TIME +Introduced in 7.4.1. +.IP CURLINFO_PRETRANSFER_TIME_T +Introduced in 7.61.0. +.IP CURLINFO_POSTTRANSFER_TIME_T +Introduced in 8.10.0. +.IP CURLINFO_PRIMARY_IP +Introduced in 7.19.0. +.IP CURLINFO_PRIMARY_PORT +Introduced in 7.21.0. +.IP CURLINFO_PRIVATE +Introduced in 7.10.3. +.IP CURLINFO_PROTOCOL +Introduced in 7.52.0. Deprecated since 7.85.0. +.IP CURLINFO_PROXY_ERROR +Introduced in 7.73.0. +.IP CURLINFO_PROXY_SSL_VERIFYRESULT +Introduced in 7.52.0. +.IP CURLINFO_PROXYAUTH_AVAIL +Introduced in 7.10.8. +.IP CURLINFO_PTR +Introduced in 7.54.1. +.IP CURLINFO_QUEUE_TIME_T +Introduced in 8.6.0. +.IP CURLINFO_REDIRECT_COUNT +Introduced in 7.9.7. +.IP CURLINFO_REDIRECT_TIME +Introduced in 7.9.7. +.IP CURLINFO_REDIRECT_TIME_T +Introduced in 7.61.0. +.IP CURLINFO_REDIRECT_URL +Introduced in 7.18.2. +.IP CURLINFO_REFERER +Introduced in 7.76.0. +.IP CURLINFO_REQUEST_SIZE +Introduced in 7.4.1. +.IP CURLINFO_RESPONSE_CODE +Introduced in 7.10.8. +.IP CURLINFO_RETRY_AFTER +Introduced in 7.66.0. +.IP CURLINFO_RTSP_CLIENT_CSEQ +Introduced in 7.20.0. +.IP CURLINFO_RTSP_CSEQ_RECV +Introduced in 7.20.0. +.IP CURLINFO_RTSP_SERVER_CSEQ +Introduced in 7.20.0. +.IP CURLINFO_RTSP_SESSION_ID +Introduced in 7.20.0. +.IP CURLINFO_SCHEME +Introduced in 7.52.0. +.IP CURLINFO_SIZE_DOWNLOAD +Introduced in 7.4.1. Deprecated since 7.55.0. +.IP CURLINFO_SIZE_DOWNLOAD_T +Introduced in 7.55.0. +.IP CURLINFO_SIZE_UPLOAD +Introduced in 7.4.1. Deprecated since 7.55.0. +.IP CURLINFO_SIZE_UPLOAD_T +Introduced in 7.55.0. +.IP CURLINFO_SLIST +Introduced in 7.12.3. +.IP CURLINFO_SOCKET +Introduced in 7.45.0. +.IP CURLINFO_SPEED_DOWNLOAD +Introduced in 7.4.1. Deprecated since 7.55.0. +.IP CURLINFO_SPEED_DOWNLOAD_T +Introduced in 7.55.0. +.IP CURLINFO_SPEED_UPLOAD +Introduced in 7.4.1. Deprecated since 7.55.0. +.IP CURLINFO_SPEED_UPLOAD_T +Introduced in 7.55.0. +.IP CURLINFO_SSL_DATA_IN +Introduced in 7.12.1. See \fICURLOPT_DEBUGFUNCTION(3)\fP. +.IP CURLINFO_SSL_DATA_OUT +Introduced in 7.12.1. See \fICURLOPT_DEBUGFUNCTION(3)\fP. +.IP CURLINFO_SSL_ENGINES +Introduced in 7.12.3. +.IP CURLINFO_SSL_VERIFYRESULT +Introduced in 7.5. +.IP CURLINFO_STARTTRANSFER_TIME +Introduced in 7.9.2. +.IP CURLINFO_STARTTRANSFER_TIME_T +Introduced in 7.61.0. +.IP CURLINFO_STRING +Introduced in 7.4.1. +.IP CURLINFO_TEXT +Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. +.IP CURLINFO_TLS_SESSION +Introduced in 7.34.0. Deprecated since 7.48.0. +.IP CURLINFO_TLS_SSL_PTR +Introduced in 7.48.0. +.IP CURLINFO_TOTAL_TIME +Introduced in 7.4.1. +.IP CURLINFO_TOTAL_TIME_T +Introduced in 7.61.0. +.IP CURLINFO_TYPEMASK +Introduced in 7.4.1. +.IP CURLINFO_USED_PROXY +Introduced in 8.7.0. +.IP CURLINFO_XFER_ID +Introduced in 8.2.0. +.IP CURLIOCMD_NOP +Introduced in 7.12.3. See \fICURLOPT_IOCTLFUNCTION(3)\fP. +.IP CURLIOCMD_RESTARTREAD +Introduced in 7.12.3. See \fICURLOPT_IOCTLFUNCTION(3)\fP. +.IP CURLIOE_FAILRESTART +Introduced in 7.12.3. See \fICURLOPT_IOCTLFUNCTION(3)\fP. +.IP CURLIOE_OK +Introduced in 7.12.3. See \fICURLOPT_IOCTLFUNCTION(3)\fP. +.IP CURLIOE_UNKNOWNCMD +Introduced in 7.12.3. See \fICURLOPT_IOCTLFUNCTION(3)\fP. +.IP CURLKHMATCH_MISMATCH +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHMATCH_MISSING +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHMATCH_OK +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHSTAT_DEFER +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHSTAT_FINE +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHSTAT_FINE_ADD_TO_FILE +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHSTAT_FINE_REPLACE +Introduced in 7.73.0. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHSTAT_REJECT +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHTYPE_DSS +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHTYPE_ECDSA +Introduced in 7.58.0. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHTYPE_ED25519 +Introduced in 7.58.0. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHTYPE_RSA +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHTYPE_RSA1 +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLKHTYPE_UNKNOWN +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLM_ABORTED_BY_CALLBACK +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_ADDED_ALREADY +Introduced in 7.32.1. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_BAD_EASY_HANDLE +Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_BAD_FUNCTION_ARGUMENT +Introduced in 7.69.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_BAD_HANDLE +Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_BAD_SOCKET +Introduced in 7.15.4. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_CALL_MULTI_PERFORM +Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_CALL_MULTI_SOCKET +Introduced in 7.15.5. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_INTERNAL_ERROR +Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_OK +Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_OUT_OF_MEMORY +Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_RECURSIVE_API_CALL +Introduced in 7.59.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_UNKNOWN_OPTION +Introduced in 7.15.4. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_UNRECOVERABLE_POLL +Introduced in 7.84.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLM_WAKEUP_FAILURE +Introduced in 7.68.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLMIMEOPT_FORMESCAPE +Introduced in 7.81.0. See \fICURLOPT_MIME_OPTIONS(3)\fP. +.IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE +Introduced in 7.30.0. See \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP. +.IP CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE +Introduced in 7.30.0. See \fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP. +.IP CURLMOPT_MAX_CONCURRENT_STREAMS +Introduced in 7.67.0. See \fICURLMOPT_MAX_CONCURRENT_STREAMS(3)\fP. +.IP CURLMOPT_MAX_HOST_CONNECTIONS +Introduced in 7.30.0. See \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. +.IP CURLMOPT_MAX_PIPELINE_LENGTH +Introduced in 7.30.0. See \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. +.IP CURLMOPT_MAX_TOTAL_CONNECTIONS +Introduced in 7.30.0. See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. +.IP CURLMOPT_MAXCONNECTS +Introduced in 7.16.3. See \fICURLMOPT_MAXCONNECTS(3)\fP. +.IP CURLMOPT_PIPELINING +Introduced in 7.16.0. See \fICURLMOPT_PIPELINING(3)\fP. +.IP CURLMOPT_PIPELINING_SERVER_BL +Introduced in 7.30.0. See \fICURLMOPT_PIPELINING_SERVER_BL(3)\fP. +.IP CURLMOPT_PIPELINING_SITE_BL +Introduced in 7.30.0. See \fICURLMOPT_PIPELINING_SITE_BL(3)\fP. +.IP CURLMOPT_PUSHDATA +Introduced in 7.44.0. See \fICURLMOPT_PUSHDATA(3)\fP. +.IP CURLMOPT_PUSHFUNCTION +Introduced in 7.44.0. See \fICURLMOPT_PUSHFUNCTION(3)\fP. +.IP CURLMOPT_SOCKETDATA +Introduced in 7.15.4. See \fICURLMOPT_SOCKETDATA(3)\fP. +.IP CURLMOPT_SOCKETFUNCTION +Introduced in 7.15.4. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. +.IP CURLMOPT_TIMERDATA +Introduced in 7.16.0. See \fICURLMOPT_TIMERDATA(3)\fP. +.IP CURLMOPT_TIMERFUNCTION +Introduced in 7.16.0. See \fICURLMOPT_TIMERFUNCTION(3)\fP. +.IP CURLMSG_DONE +Introduced in 7.9.6. See \fIcurl_multi_info_read(3)\fP. +.IP CURLMSG_NONE +Introduced in 7.9.6. See \fIcurl_multi_info_read(3)\fP. +.IP CURLOPT +Introduced in 7.69.0. +.IP CURLOPT_ABSTRACT_UNIX_SOCKET +Introduced in 7.53.0. See \fICURLOPT_ABSTRACT_UNIX_SOCKET(3)\fP. +.IP CURLOPT_ACCEPT_ENCODING +Introduced in 7.21.6. See \fICURLOPT_ACCEPT_ENCODING(3)\fP. +.IP CURLOPT_ACCEPTTIMEOUT_MS +Introduced in 7.24.0. See \fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP. +.IP CURLOPT_ADDRESS_SCOPE +Introduced in 7.19.0. See \fICURLOPT_ADDRESS_SCOPE(3)\fP. +.IP CURLOPT_ALTSVC +Introduced in 7.64.1. See \fICURLOPT_ALTSVC(3)\fP. +.IP CURLOPT_ALTSVC_CTRL +Introduced in 7.64.1. See \fICURLOPT_ALTSVC_CTRL(3)\fP. +.IP CURLOPT_APPEND +Introduced in 7.17.0. See \fICURLOPT_APPEND(3)\fP. +.IP CURLOPT_AUTOREFERER +Introduced in 7.1. See \fICURLOPT_AUTOREFERER(3)\fP. +.IP CURLOPT_AWS_SIGV4 +Introduced in 7.75.0. See \fICURLOPT_AWS_SIGV4(3)\fP. +.IP CURLOPT_BUFFERSIZE +Introduced in 7.10. See \fICURLOPT_BUFFERSIZE(3)\fP. +.IP CURLOPT_CAINFO +Introduced in 7.4.2. See \fICURLOPT_CAINFO(3)\fP. +.IP CURLOPT_CAINFO_BLOB +Introduced in 7.77.0. See \fICURLOPT_CAINFO_BLOB(3)\fP. +.IP CURLOPT_CAPATH +Introduced in 7.9.8. See \fICURLOPT_CAPATH(3)\fP. +.IP CURLOPT_CA_CACHE_TIMEOUT +Introduced in 7.87.0. See \fICURLOPT_CA_CACHE_TIMEOUT(3)\fP. +.IP CURLOPT_CERTINFO +Introduced in 7.19.1. See \fICURLOPT_CERTINFO(3)\fP. +.IP CURLOPT_CHUNK_BGN_FUNCTION +Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. +.IP CURLOPT_CHUNK_DATA +Introduced in 7.21.0. See \fICURLOPT_CHUNK_DATA(3)\fP. +.IP CURLOPT_CHUNK_END_FUNCTION +Introduced in 7.21.0. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP. +.IP CURLOPT_CLOSEFUNCTION +Introduced in 7.7. Deprecated since 7.11.1. +.IP CURLOPT_CLOSEPOLICY +Introduced in 7.7. Deprecated since 7.16.1. +.IP CURLOPT_CLOSESOCKETDATA +Introduced in 7.21.7. See \fICURLOPT_CLOSESOCKETDATA(3)\fP. +.IP CURLOPT_CLOSESOCKETFUNCTION +Introduced in 7.21.7. See \fICURLOPT_CLOSESOCKETFUNCTION(3)\fP. +.IP CURLOPT_CONNECT_ONLY +Introduced in 7.15.2. See \fICURLOPT_CONNECT_ONLY(3)\fP. +.IP CURLOPT_CONNECT_TO +Introduced in 7.49.0. See \fICURLOPT_CONNECT_TO(3)\fP. +.IP CURLOPT_CONNECTTIMEOUT +Introduced in 7.7. See \fICURLOPT_CONNECTTIMEOUT(3)\fP. +.IP CURLOPT_CONNECTTIMEOUT_MS +Introduced in 7.16.2. See \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP. +.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION +Introduced in 7.15.4. Deprecated since 7.82.0. +.IP CURLOPT_CONV_FROM_UTF8_FUNCTION +Introduced in 7.15.4. Deprecated since 7.82.0. +.IP CURLOPT_CONV_TO_NETWORK_FUNCTION +Introduced in 7.15.4. Deprecated since 7.82.0. +.IP CURLOPT_COOKIE +Introduced in 7.1. See \fICURLOPT_COOKIE(3)\fP. +.IP CURLOPT_COOKIEFILE +Introduced in 7.1. See \fICURLOPT_COOKIEFILE(3)\fP. +.IP CURLOPT_COOKIEJAR +Introduced in 7.9. See \fICURLOPT_COOKIEJAR(3)\fP. +.IP CURLOPT_COOKIELIST +Introduced in 7.14.1. See \fICURLOPT_COOKIELIST(3)\fP. +.IP CURLOPT_COOKIESESSION +Introduced in 7.9.7. See \fICURLOPT_COOKIESESSION(3)\fP. +.IP CURLOPT_COPYPOSTFIELDS +Introduced in 7.17.1. See \fICURLOPT_COPYPOSTFIELDS(3)\fP. +.IP CURLOPT_CRLF +Introduced in 7.1. See \fICURLOPT_CRLF(3)\fP. +.IP CURLOPT_CRLFILE +Introduced in 7.19.0. See \fICURLOPT_CRLFILE(3)\fP. +.IP CURLOPT_CURLU +Introduced in 7.63.0. See \fICURLOPT_CURLU(3)\fP. +.IP CURLOPT_CUSTOMREQUEST +Introduced in 7.1. See \fICURLOPT_CUSTOMREQUEST(3)\fP. +.IP CURLOPT_DEBUGDATA +Introduced in 7.9.6. See \fICURLOPT_DEBUGDATA(3)\fP. +.IP CURLOPT_DEBUGFUNCTION +Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. +.IP CURLOPT_DEFAULT_PROTOCOL +Introduced in 7.45.0. See \fICURLOPT_DEFAULT_PROTOCOL(3)\fP. +.IP CURLOPT_DIRLISTONLY +Introduced in 7.17.0. See \fICURLOPT_DIRLISTONLY(3)\fP. +.IP CURLOPT_DISALLOW_USERNAME_IN_URL +Introduced in 7.61.0. See \fICURLOPT_DISALLOW_USERNAME_IN_URL(3)\fP. +.IP CURLOPT_DNS_CACHE_TIMEOUT +Introduced in 7.9.3. See \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP. +.IP CURLOPT_DNS_INTERFACE +Introduced in 7.33.0. See \fICURLOPT_DNS_INTERFACE(3)\fP. +.IP CURLOPT_DNS_LOCAL_IP4 +Introduced in 7.33.0. See \fICURLOPT_DNS_LOCAL_IP4(3)\fP. +.IP CURLOPT_DNS_LOCAL_IP6 +Introduced in 7.33.0. See \fICURLOPT_DNS_LOCAL_IP6(3)\fP. +.IP CURLOPT_DNS_SERVERS +Introduced in 7.24.0. See \fICURLOPT_DNS_SERVERS(3)\fP. +.IP CURLOPT_DNS_SHUFFLE_ADDRESSES +Introduced in 7.60.0. See \fICURLOPT_DNS_SHUFFLE_ADDRESSES(3)\fP. +.IP CURLOPT_DNS_USE_GLOBAL_CACHE +Introduced in 7.9.3. Deprecated since 7.11.1. +.IP CURLOPT_DOH_SSL_VERIFYHOST +Introduced in 7.76.0. See \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP. +.IP CURLOPT_DOH_SSL_VERIFYPEER +Introduced in 7.76.0. See \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP. +.IP CURLOPT_DOH_SSL_VERIFYSTATUS +Introduced in 7.76.0. See \fICURLOPT_DOH_SSL_VERIFYSTATUS(3)\fP. +.IP CURLOPT_DOH_URL +Introduced in 7.62.0. See \fICURLOPT_DOH_URL(3)\fP. +.IP CURLOPT_ECH +Introduced in 8.8.0. See \fICURLOPT_ECH(3)\fP. +.IP CURLOPT_EGDSOCKET +Introduced in 7.7. Deprecated since 7.84.0. +.IP CURLOPT_ENCODING +Introduced in 7.10. Deprecated since 7.21.6. +.IP CURLOPT_ERRORBUFFER +Introduced in 7.1. See \fICURLOPT_ERRORBUFFER(3)\fP. +.IP CURLOPT_EXPECT_100_TIMEOUT_MS +Introduced in 7.36.0. See \fICURLOPT_EXPECT_100_TIMEOUT_MS(3)\fP. +.IP CURLOPT_FAILONERROR +Introduced in 7.1. See \fICURLOPT_FAILONERROR(3)\fP. +.IP CURLOPT_FILE +Introduced in 7.1. Deprecated since 7.9.7. +.IP CURLOPT_FILETIME +Introduced in 7.5. See \fICURLOPT_FILETIME(3)\fP. +.IP CURLOPT_FNMATCH_DATA +Introduced in 7.21.0. See \fICURLOPT_FNMATCH_DATA(3)\fP. +.IP CURLOPT_FNMATCH_FUNCTION +Introduced in 7.21.0. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP. +.IP CURLOPT_FOLLOWLOCATION +Introduced in 7.1. See \fICURLOPT_FOLLOWLOCATION(3)\fP. +.IP CURLOPT_FORBID_REUSE +Introduced in 7.7. See \fICURLOPT_FORBID_REUSE(3)\fP. +.IP CURLOPT_FRESH_CONNECT +Introduced in 7.7. See \fICURLOPT_FRESH_CONNECT(3)\fP. +.IP CURLOPT_FTP_ACCOUNT +Introduced in 7.13.0. See \fICURLOPT_FTP_ACCOUNT(3)\fP. +.IP CURLOPT_FTP_ALTERNATIVE_TO_USER +Introduced in 7.15.5. See \fICURLOPT_FTP_ALTERNATIVE_TO_USER(3)\fP. +.IP CURLOPT_FTP_CREATE_MISSING_DIRS +Introduced in 7.10.7. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP. +.IP CURLOPT_FTP_FILEMETHOD +Introduced in 7.15.1. See \fICURLOPT_FTP_FILEMETHOD(3)\fP. +.IP CURLOPT_FTP_RESPONSE_TIMEOUT +Introduced in 7.10.8. Deprecated since 7.85.0. +.IP CURLOPT_FTP_SKIP_PASV_IP +Introduced in 7.15.0. See \fICURLOPT_FTP_SKIP_PASV_IP(3)\fP. +.IP CURLOPT_FTP_SSL +Introduced in 7.11.0. Deprecated since 7.16.4. +.IP CURLOPT_FTP_SSL_CCC +Introduced in 7.16.1. See \fICURLOPT_FTP_SSL_CCC(3)\fP. +.IP CURLOPT_FTP_USE_EPRT +Introduced in 7.10.5. See \fICURLOPT_FTP_USE_EPRT(3)\fP. +.IP CURLOPT_FTP_USE_EPSV +Introduced in 7.9.2. See \fICURLOPT_FTP_USE_EPSV(3)\fP. +.IP CURLOPT_FTP_USE_PRET +Introduced in 7.20.0. See \fICURLOPT_FTP_USE_PRET(3)\fP. +.IP CURLOPT_FTPAPPEND +Introduced in 7.1. Deprecated since 7.16.4. +.IP CURLOPT_FTPASCII +Introduced in 7.1. Deprecated since 7.11.1. +.IP CURLOPT_FTPLISTONLY +Introduced in 7.1. Deprecated since 7.16.4. +.IP CURLOPT_FTPPORT +Introduced in 7.1. See \fICURLOPT_FTPPORT(3)\fP. +.IP CURLOPT_FTPSSLAUTH +Introduced in 7.12.2. See \fICURLOPT_FTPSSLAUTH(3)\fP. +.IP CURLOPT_GSSAPI_DELEGATION +Introduced in 7.22.0. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP. +.IP CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS +Introduced in 7.59.0. See \fICURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)\fP. +.IP CURLOPT_HAPROXYPROTOCOL +Introduced in 7.60.0. See \fICURLOPT_HAPROXYPROTOCOL(3)\fP. +.IP CURLOPT_HAPROXY_CLIENT_IP +Introduced in 8.2.0. See \fICURLOPT_HAPROXY_CLIENT_IP(3)\fP. +.IP CURLOPT_HEADER +Introduced in 7.1. See \fICURLOPT_HEADER(3)\fP. +.IP CURLOPT_HEADERDATA +Introduced in 7.10. See \fICURLOPT_HEADERDATA(3)\fP. +.IP CURLOPT_HEADERFUNCTION +Introduced in 7.7.2. See \fICURLOPT_HEADERFUNCTION(3)\fP. +.IP CURLOPT_HEADEROPT +Introduced in 7.37.0. See \fICURLOPT_HEADEROPT(3)\fP. +.IP CURLOPT_HSTS +Introduced in 7.74.0. See \fICURLOPT_HSTS(3)\fP. +.IP CURLOPT_HSTS_CTRL +Introduced in 7.74.0. See \fICURLOPT_HSTS_CTRL(3)\fP. +.IP CURLOPT_HSTSREADDATA +Introduced in 7.74.0. See \fICURLOPT_HSTSREADDATA(3)\fP. +.IP CURLOPT_HSTSREADFUNCTION +Introduced in 7.74.0. See \fICURLOPT_HSTSREADFUNCTION(3)\fP. +.IP CURLOPT_HSTSWRITEDATA +Introduced in 7.74.0. See \fICURLOPT_HSTSWRITEDATA(3)\fP. +.IP CURLOPT_HSTSWRITEFUNCTION +Introduced in 7.74.0. See \fICURLOPT_HSTSWRITEFUNCTION(3)\fP. +.IP CURLOPT_HTTP09_ALLOWED +Introduced in 7.64.0. See \fICURLOPT_HTTP09_ALLOWED(3)\fP. +.IP CURLOPT_HTTP200ALIASES +Introduced in 7.10.3. See \fICURLOPT_HTTP200ALIASES(3)\fP. +.IP CURLOPT_HTTP_CONTENT_DECODING +Introduced in 7.16.2. See \fICURLOPT_HTTP_CONTENT_DECODING(3)\fP. +.IP CURLOPT_HTTP_TRANSFER_DECODING +Introduced in 7.16.2. See \fICURLOPT_HTTP_TRANSFER_DECODING(3)\fP. +.IP CURLOPT_HTTP_VERSION +Introduced in 7.9.1. See \fICURLOPT_HTTP_VERSION(3)\fP. +.IP CURLOPT_HTTPAUTH +Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. +.IP CURLOPT_HTTPGET +Introduced in 7.8.1. See \fICURLOPT_HTTPGET(3)\fP. +.IP CURLOPT_HTTPHEADER +Introduced in 7.1. See \fICURLOPT_HTTPHEADER(3)\fP. +.IP CURLOPT_HTTPPOST +Introduced in 7.1. Deprecated since 7.56.0. +.IP CURLOPT_HTTPPROXYTUNNEL +Introduced in 7.3. See \fICURLOPT_HTTPPROXYTUNNEL(3)\fP. +.IP CURLOPT_HTTPREQUEST +Introduced in 7.1. Last used in 7.15.5. +.IP CURLOPT_IGNORE_CONTENT_LENGTH +Introduced in 7.14.1. See \fICURLOPT_IGNORE_CONTENT_LENGTH(3)\fP. +.IP CURLOPT_INFILE +Introduced in 7.1. Deprecated since 7.9.7. +.IP CURLOPT_INFILESIZE +Introduced in 7.1. See \fICURLOPT_INFILESIZE(3)\fP. +.IP CURLOPT_INFILESIZE_LARGE +Introduced in 7.11.0. See \fICURLOPT_INFILESIZE_LARGE(3)\fP. +.IP CURLOPT_INTERFACE +Introduced in 7.3. See \fICURLOPT_INTERFACE(3)\fP. +.IP CURLOPT_INTERLEAVEDATA +Introduced in 7.20.0. See \fICURLOPT_INTERLEAVEDATA(3)\fP. +.IP CURLOPT_INTERLEAVEFUNCTION +Introduced in 7.20.0. See \fICURLOPT_INTERLEAVEFUNCTION(3)\fP. +.IP CURLOPT_IOCTLDATA +Introduced in 7.12.3. Deprecated since 7.18.0. +.IP CURLOPT_IOCTLFUNCTION +Introduced in 7.12.3. Deprecated since 7.18.0. +.IP CURLOPT_IPRESOLVE +Introduced in 7.10.8. See \fICURLOPT_IPRESOLVE(3)\fP. +.IP CURLOPT_ISSUERCERT +Introduced in 7.19.0. See \fICURLOPT_ISSUERCERT(3)\fP. +.IP CURLOPT_ISSUERCERT_BLOB +Introduced in 7.71.0. See \fICURLOPT_ISSUERCERT_BLOB(3)\fP. +.IP CURLOPT_KEEP_SENDING_ON_ERROR +Introduced in 7.51.0. See \fICURLOPT_KEEP_SENDING_ON_ERROR(3)\fP. +.IP CURLOPT_KEYPASSWD +Introduced in 7.17.0. See \fICURLOPT_KEYPASSWD(3)\fP. +.IP CURLOPT_KRB4LEVEL +Introduced in 7.3. Deprecated since 7.17.0. +.IP CURLOPT_KRBLEVEL +Introduced in 7.16.4. See \fICURLOPT_KRBLEVEL(3)\fP. +.IP CURLOPT_LOCALPORT +Introduced in 7.15.2. See \fICURLOPT_LOCALPORT(3)\fP. +.IP CURLOPT_LOCALPORTRANGE +Introduced in 7.15.2. See \fICURLOPT_LOCALPORTRANGE(3)\fP. +.IP CURLOPT_LOGIN_OPTIONS +Introduced in 7.34.0. See \fICURLOPT_LOGIN_OPTIONS(3)\fP. +.IP CURLOPT_LOW_SPEED_LIMIT +Introduced in 7.1. See \fICURLOPT_LOW_SPEED_LIMIT(3)\fP. +.IP CURLOPT_LOW_SPEED_TIME +Introduced in 7.1. See \fICURLOPT_LOW_SPEED_TIME(3)\fP. +.IP CURLOPT_MAIL_AUTH +Introduced in 7.25.0. See \fICURLOPT_MAIL_AUTH(3)\fP. +.IP CURLOPT_MAIL_FROM +Introduced in 7.20.0. See \fICURLOPT_MAIL_FROM(3)\fP. +.IP CURLOPT_MAIL_RCPT +Introduced in 7.20.0. See \fICURLOPT_MAIL_RCPT(3)\fP. +.IP CURLOPT_MAIL_RCPT_ALLLOWFAILS +Introduced in 7.69.0. Deprecated since 8.2.0. +.IP CURLOPT_MAIL_RCPT_ALLOWFAILS +Introduced in 8.2.0. See \fICURLOPT_MAIL_RCPT_ALLOWFAILS(3)\fP. +.IP CURLOPT_QUICK_EXIT +Introduced in 7.87.0. See \fICURLOPT_QUICK_EXIT(3)\fP. +.IP CURLOPT_MAX_RECV_SPEED_LARGE +Introduced in 7.15.5. See \fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP. +.IP CURLOPT_MAX_SEND_SPEED_LARGE +Introduced in 7.15.5. See \fICURLOPT_MAX_SEND_SPEED_LARGE(3)\fP. +.IP CURLOPT_MAXAGE_CONN +Introduced in 7.65.0. See \fICURLOPT_MAXAGE_CONN(3)\fP. +.IP CURLOPT_MAXCONNECTS +Introduced in 7.7. See \fICURLOPT_MAXCONNECTS(3)\fP. +.IP CURLOPT_MAXFILESIZE +Introduced in 7.10.8. See \fICURLOPT_MAXFILESIZE(3)\fP. +.IP CURLOPT_MAXFILESIZE_LARGE +Introduced in 7.11.0. See \fICURLOPT_MAXFILESIZE_LARGE(3)\fP. +.IP CURLOPT_MAXLIFETIME_CONN +Introduced in 7.80.0. See \fICURLOPT_MAXLIFETIME_CONN(3)\fP. +.IP CURLOPT_MAXREDIRS +Introduced in 7.5. See \fICURLOPT_MAXREDIRS(3)\fP. +.IP CURLOPT_MIME_OPTIONS +Introduced in 7.81.0. See \fICURLOPT_MIME_OPTIONS(3)\fP. +.IP CURLOPT_MIMEPOST +Introduced in 7.56.0. See \fICURLOPT_MIMEPOST(3)\fP. +.IP CURLOPT_MUTE +Introduced in 7.1. Deprecated since 7.8. +.IP CURLOPT_NETRC +Introduced in 7.1. See \fICURLOPT_NETRC(3)\fP. +.IP CURLOPT_NETRC_FILE +Introduced in 7.11.0. See \fICURLOPT_NETRC_FILE(3)\fP. +.IP CURLOPT_NEW_DIRECTORY_PERMS +Introduced in 7.16.4. See \fICURLOPT_NEW_DIRECTORY_PERMS(3)\fP. +.IP CURLOPT_NEW_FILE_PERMS +Introduced in 7.16.4. See \fICURLOPT_NEW_FILE_PERMS(3)\fP. +.IP CURLOPT_NOBODY +Introduced in 7.1. See \fICURLOPT_NOBODY(3)\fP. +.IP CURLOPT_NOPROGRESS +Introduced in 7.1. See \fICURLOPT_NOPROGRESS(3)\fP. +.IP CURLOPT_NOPROXY +Introduced in 7.19.4. See \fICURLOPT_NOPROXY(3)\fP. +.IP CURLOPT_NOSIGNAL +Introduced in 7.10. See \fICURLOPT_NOSIGNAL(3)\fP. +.IP CURLOPT_NOTHING +Introduced in 7.1.1. Deprecated since 7.11.1. +.IP CURLOPT_OPENSOCKETDATA +Introduced in 7.17.1. See \fICURLOPT_OPENSOCKETDATA(3)\fP. +.IP CURLOPT_OPENSOCKETFUNCTION +Introduced in 7.17.1. See \fICURLOPT_OPENSOCKETFUNCTION(3)\fP. +.IP CURLOPT_PASSWDDATA +Introduced in 7.4.2. Deprecated since 7.11.1. +.IP CURLOPT_PASSWDFUNCTION +Introduced in 7.4.2. Deprecated since 7.11.1. +.IP CURLOPT_PASSWORD +Introduced in 7.19.1. See \fICURLOPT_PASSWORD(3)\fP. +.IP CURLOPT_PASV_HOST +Introduced in 7.12.1. Deprecated since 7.16.0. +.IP CURLOPT_PATH_AS_IS +Introduced in 7.42.0. See \fICURLOPT_PATH_AS_IS(3)\fP. +.IP CURLOPT_PINNEDPUBLICKEY +Introduced in 7.39.0. See \fICURLOPT_PINNEDPUBLICKEY(3)\fP. +.IP CURLOPT_PIPEWAIT +Introduced in 7.43.0. See \fICURLOPT_PIPEWAIT(3)\fP. +.IP CURLOPT_PORT +Introduced in 7.1. See \fICURLOPT_PORT(3)\fP. +.IP CURLOPT_POST +Introduced in 7.1. See \fICURLOPT_POST(3)\fP. +.IP CURLOPT_POST301 +Introduced in 7.17.1. Deprecated since 7.19.1. +.IP CURLOPT_POSTFIELDS +Introduced in 7.1. See \fICURLOPT_POSTFIELDS(3)\fP. +.IP CURLOPT_POSTFIELDSIZE +Introduced in 7.2. See \fICURLOPT_POSTFIELDSIZE(3)\fP. +.IP CURLOPT_POSTFIELDSIZE_LARGE +Introduced in 7.11.1. See \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP. +.IP CURLOPT_POSTQUOTE +Introduced in 7.1. See \fICURLOPT_POSTQUOTE(3)\fP. +.IP CURLOPT_POSTREDIR +Introduced in 7.19.1. See \fICURLOPT_POSTREDIR(3)\fP. +.IP CURLOPT_PRE_PROXY +Introduced in 7.52.0. See \fICURLOPT_PRE_PROXY(3)\fP. +.IP CURLOPT_PREQUOTE +Introduced in 7.9.5. See \fICURLOPT_PREQUOTE(3)\fP. +.IP CURLOPT_PREREQDATA +Introduced in 7.80.0. See \fICURLOPT_PREREQDATA(3)\fP. +.IP CURLOPT_PREREQFUNCTION +Introduced in 7.80.0. See \fICURLOPT_PREREQFUNCTION(3)\fP. +.IP CURLOPT_PRIVATE +Introduced in 7.10.3. See \fICURLOPT_PRIVATE(3)\fP. +.IP CURLOPT_PROGRESSDATA +Introduced in 7.1. See \fICURLOPT_PROGRESSDATA(3)\fP. +.IP CURLOPT_PROGRESSFUNCTION +Introduced in 7.1. Deprecated since 7.32.0. +.IP CURLOPT_PROTOCOLS +Introduced in 7.19.4. Deprecated since 7.85.0. +.IP CURLOPT_PROTOCOLS_STR +Introduced in 7.85.0. See \fICURLOPT_PROTOCOLS_STR(3)\fP. +.IP CURLOPT_PROXY +Introduced in 7.1. See \fICURLOPT_PROXY(3)\fP. +.IP CURLOPT_PROXY_CAINFO +Introduced in 7.52.0. See \fICURLOPT_PROXY_CAINFO(3)\fP. +.IP CURLOPT_PROXY_CAINFO_BLOB +Introduced in 7.77.0. See \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP. +.IP CURLOPT_PROXY_CAPATH +Introduced in 7.52.0. See \fICURLOPT_PROXY_CAPATH(3)\fP. +.IP CURLOPT_PROXY_CRLFILE +Introduced in 7.52.0. See \fICURLOPT_PROXY_CRLFILE(3)\fP. +.IP CURLOPT_PROXY_ISSUERCERT +Introduced in 7.71.0. See \fICURLOPT_PROXY_ISSUERCERT(3)\fP. +.IP CURLOPT_PROXY_ISSUERCERT_BLOB +Introduced in 7.71.0. See \fICURLOPT_PROXY_ISSUERCERT_BLOB(3)\fP. +.IP CURLOPT_PROXY_KEYPASSWD +Introduced in 7.52.0. See \fICURLOPT_PROXY_KEYPASSWD(3)\fP. +.IP CURLOPT_PROXY_PINNEDPUBLICKEY +Introduced in 7.52.0. See \fICURLOPT_PROXY_PINNEDPUBLICKEY(3)\fP. +.IP CURLOPT_PROXY_SERVICE_NAME +Introduced in 7.43.0. See \fICURLOPT_PROXY_SERVICE_NAME(3)\fP. +.IP CURLOPT_PROXY_SSL_CIPHER_LIST +Introduced in 7.52.0. See \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP. +.IP CURLOPT_PROXY_SSL_OPTIONS +Introduced in 7.52.0. See \fICURLOPT_PROXY_SSL_OPTIONS(3)\fP. +.IP CURLOPT_PROXY_SSL_VERIFYHOST +Introduced in 7.52.0. See \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP. +.IP CURLOPT_PROXY_SSL_VERIFYPEER +Introduced in 7.52.0. See \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP. +.IP CURLOPT_PROXY_SSLCERT +Introduced in 7.52.0. See \fICURLOPT_PROXY_SSLCERT(3)\fP. +.IP CURLOPT_PROXY_SSLCERT_BLOB +Introduced in 7.71.0. See \fICURLOPT_PROXY_SSLCERT_BLOB(3)\fP. +.IP CURLOPT_PROXY_SSLCERTTYPE +Introduced in 7.52.0. See \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP. +.IP CURLOPT_PROXY_SSLKEY +Introduced in 7.52.0. See \fICURLOPT_PROXY_SSLKEY(3)\fP. +.IP CURLOPT_PROXY_SSLKEY_BLOB +Introduced in 7.71.0. See \fICURLOPT_PROXY_SSLKEY_BLOB(3)\fP. +.IP CURLOPT_PROXY_SSLKEYTYPE +Introduced in 7.52.0. See \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP. +.IP CURLOPT_PROXY_SSLVERSION +Introduced in 7.52.0. See \fICURLOPT_PROXY_SSLVERSION(3)\fP. +.IP CURLOPT_PROXY_TLS13_CIPHERS +Introduced in 7.61.0. See \fICURLOPT_PROXY_TLS13_CIPHERS(3)\fP. +.IP CURLOPT_PROXY_TLSAUTH_PASSWORD +Introduced in 7.52.0. See \fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP. +.IP CURLOPT_PROXY_TLSAUTH_TYPE +Introduced in 7.52.0. See \fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP. +.IP CURLOPT_PROXY_TLSAUTH_USERNAME +Introduced in 7.52.0. See \fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP. +.IP CURLOPT_PROXY_TRANSFER_MODE +Introduced in 7.18.0. See \fICURLOPT_PROXY_TRANSFER_MODE(3)\fP. +.IP CURLOPT_PROXYAUTH +Introduced in 7.10.7. See \fICURLOPT_PROXYAUTH(3)\fP. +.IP CURLOPT_PROXYHEADER +Introduced in 7.37.0. See \fICURLOPT_PROXYHEADER(3)\fP. +.IP CURLOPT_PROXYPASSWORD +Introduced in 7.19.1. See \fICURLOPT_PROXYPASSWORD(3)\fP. +.IP CURLOPT_PROXYPORT +Introduced in 7.1. See \fICURLOPT_PROXYPORT(3)\fP. +.IP CURLOPT_PROXYTYPE +Introduced in 7.10. See \fICURLOPT_PROXYTYPE(3)\fP. +.IP CURLOPT_PROXYUSERNAME +Introduced in 7.19.1. See \fICURLOPT_PROXYUSERNAME(3)\fP. +.IP CURLOPT_PROXYUSERPWD +Introduced in 7.1. See \fICURLOPT_PROXYUSERPWD(3)\fP. +.IP CURLOPT_PUT +Introduced in 7.1. Deprecated since 7.12.1. +.IP CURLOPT_QUOTE +Introduced in 7.1. See \fICURLOPT_QUOTE(3)\fP. +.IP CURLOPT_RANDOM_FILE +Introduced in 7.7. Deprecated since 7.84.0. +.IP CURLOPT_RANGE +Introduced in 7.1. See \fICURLOPT_RANGE(3)\fP. +.IP CURLOPT_READDATA +Introduced in 7.9.7. See \fICURLOPT_READDATA(3)\fP. +.IP CURLOPT_READFUNCTION +Introduced in 7.1. See \fICURLOPT_READFUNCTION(3)\fP. +.IP CURLOPT_REDIR_PROTOCOLS +Introduced in 7.19.4. Deprecated since 7.85.0. +.IP CURLOPT_REDIR_PROTOCOLS_STR +Introduced in 7.85.0. See \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP. +.IP CURLOPT_REFERER +Introduced in 7.1. See \fICURLOPT_REFERER(3)\fP. +.IP CURLOPT_REQUEST_TARGET +Introduced in 7.55.0. See \fICURLOPT_REQUEST_TARGET(3)\fP. +.IP CURLOPT_RESOLVE +Introduced in 7.21.3. See \fICURLOPT_RESOLVE(3)\fP. +.IP CURLOPT_RESOLVER_START_DATA +Introduced in 7.59.0. See \fICURLOPT_RESOLVER_START_DATA(3)\fP. +.IP CURLOPT_RESOLVER_START_FUNCTION +Introduced in 7.59.0. See \fICURLOPT_RESOLVER_START_FUNCTION(3)\fP. +.IP CURLOPT_RESUME_FROM +Introduced in 7.1. See \fICURLOPT_RESUME_FROM(3)\fP. +.IP CURLOPT_RESUME_FROM_LARGE +Introduced in 7.11.0. See \fICURLOPT_RESUME_FROM_LARGE(3)\fP. +.IP CURLOPT_RTSP_CLIENT_CSEQ +Introduced in 7.20.0. See \fICURLOPT_RTSP_CLIENT_CSEQ(3)\fP. +.IP CURLOPT_RTSP_REQUEST +Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. +.IP CURLOPT_RTSP_SERVER_CSEQ +Introduced in 7.20.0. See \fICURLOPT_RTSP_SERVER_CSEQ(3)\fP. +.IP CURLOPT_RTSP_SESSION_ID +Introduced in 7.20.0. See \fICURLOPT_RTSP_SESSION_ID(3)\fP. +.IP CURLOPT_RTSP_STREAM_URI +Introduced in 7.20.0. See \fICURLOPT_RTSP_STREAM_URI(3)\fP. +.IP CURLOPT_RTSP_TRANSPORT +Introduced in 7.20.0. See \fICURLOPT_RTSP_TRANSPORT(3)\fP. +.IP CURLOPT_RTSPHEADER +Introduced in 7.20.0. See CURLOPT_HTTPHEADER. +.IP CURLOPT_SASL_AUTHZID +Introduced in 7.66.0. See \fICURLOPT_SASL_AUTHZID(3)\fP. +.IP CURLOPT_SASL_IR +Introduced in 7.31.0. See \fICURLOPT_SASL_IR(3)\fP. +.IP CURLOPT_SEEKDATA +Introduced in 7.18.0. See \fICURLOPT_SEEKDATA(3)\fP. +.IP CURLOPT_SEEKFUNCTION +Introduced in 7.18.0. See \fICURLOPT_SEEKFUNCTION(3)\fP. +.IP CURLOPT_SERVER_RESPONSE_TIMEOUT +Introduced in 7.20.0. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP. +.IP CURLOPT_SERVER_RESPONSE_TIMEOUT_MS +Introduced in 8.6.0. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP. +.IP CURLOPT_SERVICE_NAME +Introduced in 7.43.0. See \fICURLOPT_SERVICE_NAME(3)\fP. +.IP CURLOPT_SHARE +Introduced in 7.10. See \fICURLOPT_SHARE(3)\fP. +.IP CURLOPT_SOCKOPTDATA +Introduced in 7.16.0. See \fICURLOPT_SOCKOPTDATA(3)\fP. +.IP CURLOPT_SOCKOPTFUNCTION +Introduced in 7.16.0. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP. +.IP CURLOPT_SOCKS5_AUTH +Introduced in 7.55.0. See \fICURLOPT_SOCKS5_AUTH(3)\fP. +.IP CURLOPT_SOCKS5_GSSAPI_NEC +Introduced in 7.19.4. See \fICURLOPT_SOCKS5_GSSAPI_NEC(3)\fP. +.IP CURLOPT_SOCKS5_GSSAPI_SERVICE +Introduced in 7.19.4. Deprecated since 7.49.0. +.IP CURLOPT_SOURCE_HOST +Introduced in 7.12.1. Last used in 7.15.5. +.IP CURLOPT_SOURCE_PATH +Introduced in 7.12.1. Last used in 7.15.5. +.IP CURLOPT_SOURCE_PORT +Introduced in 7.12.1. Last used in 7.15.5. +.IP CURLOPT_SOURCE_POSTQUOTE +Introduced in 7.12.1. Last used in 7.15.5. +.IP CURLOPT_SOURCE_PREQUOTE +Introduced in 7.12.1. Last used in 7.15.5. +.IP CURLOPT_SOURCE_QUOTE +Introduced in 7.13.0. Last used in 7.15.5. +.IP CURLOPT_SOURCE_URL +Introduced in 7.13.0. Last used in 7.15.5. +.IP CURLOPT_SOURCE_USERPWD +Introduced in 7.12.1. Last used in 7.15.5. +.IP CURLOPT_SSH_AUTH_TYPES +Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. +.IP CURLOPT_SSH_COMPRESSION +Introduced in 7.56.0. See \fICURLOPT_SSH_COMPRESSION(3)\fP. +.IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 +Introduced in 7.17.1. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3)\fP. +.IP CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 +Introduced in 7.80.0. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP. +.IP CURLOPT_SSH_HOSTKEYDATA +Introduced in 7.84.0. See \fICURLOPT_SSH_HOSTKEYDATA(3)\fP. +.IP CURLOPT_SSH_HOSTKEYFUNCTION +Introduced in 7.84.0. See \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP. +.IP CURLOPT_SSH_KEYDATA +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYDATA(3)\fP. +.IP CURLOPT_SSH_KEYFUNCTION +Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.IP CURLOPT_SSH_KNOWNHOSTS +Introduced in 7.19.6. See \fICURLOPT_SSH_KNOWNHOSTS(3)\fP. +.IP CURLOPT_SSH_PRIVATE_KEYFILE +Introduced in 7.16.1. See \fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP. +.IP CURLOPT_SSH_PUBLIC_KEYFILE +Introduced in 7.16.1. See \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP. +.IP CURLOPT_SSL_CIPHER_LIST +Introduced in 7.9. See \fICURLOPT_SSL_CIPHER_LIST(3)\fP. +.IP CURLOPT_SSL_CTX_DATA +Introduced in 7.10.6. See \fICURLOPT_SSL_CTX_DATA(3)\fP. +.IP CURLOPT_SSL_CTX_FUNCTION +Introduced in 7.10.6. See \fICURLOPT_SSL_CTX_FUNCTION(3)\fP. +.IP CURLOPT_SSL_EC_CURVES +Introduced in 7.73.0. See \fICURLOPT_SSL_EC_CURVES(3)\fP. +.IP CURLOPT_SSL_ENABLE_ALPN +Introduced in 7.36.0. See \fICURLOPT_SSL_ENABLE_ALPN(3)\fP. +.IP CURLOPT_SSL_ENABLE_NPN +Introduced in 7.36.0. Deprecated since 7.86.0. +.IP CURLOPT_SSL_FALSESTART +Introduced in 7.42.0. See \fICURLOPT_SSL_FALSESTART(3)\fP. +.IP CURLOPT_SSL_OPTIONS +Introduced in 7.25.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. +.IP CURLOPT_SSL_SESSIONID_CACHE +Introduced in 7.16.0. See \fICURLOPT_SSL_SESSIONID_CACHE(3)\fP. +.IP CURLOPT_SSL_VERIFYHOST +Introduced in 7.8.1. See \fICURLOPT_SSL_VERIFYHOST(3)\fP. +.IP CURLOPT_SSL_VERIFYPEER +Introduced in 7.4.2. See \fICURLOPT_SSL_VERIFYPEER(3)\fP. +.IP CURLOPT_SSL_VERIFYSTATUS +Introduced in 7.41.0. See \fICURLOPT_SSL_VERIFYSTATUS(3)\fP. +.IP CURLOPT_SSLCERT +Introduced in 7.1. See \fICURLOPT_SSLCERT(3)\fP. +.IP CURLOPT_SSLCERT_BLOB +Introduced in 7.71.0. See \fICURLOPT_SSLCERT_BLOB(3)\fP. +.IP CURLOPT_SSLCERTPASSWD +Introduced in 7.1.1. Deprecated since 7.17.0. +.IP CURLOPT_SSLCERTTYPE +Introduced in 7.9.3. See \fICURLOPT_SSLCERTTYPE(3)\fP. +.IP CURLOPT_SSLENGINE +Introduced in 7.9.3. See \fICURLOPT_SSLENGINE(3)\fP. +.IP CURLOPT_SSLENGINE_DEFAULT +Introduced in 7.9.3. See \fICURLOPT_SSLENGINE_DEFAULT(3)\fP. +.IP CURLOPT_SSLKEY +Introduced in 7.9.3. See \fICURLOPT_SSLKEY(3)\fP. +.IP CURLOPT_SSLKEY_BLOB +Introduced in 7.71.0. See \fICURLOPT_SSLKEY_BLOB(3)\fP. +.IP CURLOPT_SSLKEYPASSWD +Introduced in 7.9.3. Deprecated since 7.17.0. +.IP CURLOPT_SSLKEYTYPE +Introduced in 7.9.3. See \fICURLOPT_SSLKEYTYPE(3)\fP. +.IP CURLOPT_SSLVERSION +Introduced in 7.1. See \fICURLOPT_SSLVERSION(3)\fP. +.IP CURLOPT_STDERR +Introduced in 7.1. See \fICURLOPT_STDERR(3)\fP. +.IP CURLOPT_STREAM_DEPENDS +Introduced in 7.46.0. See \fICURLOPT_STREAM_DEPENDS(3)\fP. +.IP CURLOPT_STREAM_DEPENDS_E +Introduced in 7.46.0. See \fICURLOPT_STREAM_DEPENDS_E(3)\fP. +.IP CURLOPT_STREAM_WEIGHT +Introduced in 7.46.0. See \fICURLOPT_STREAM_WEIGHT(3)\fP. +.IP CURLOPT_SUPPRESS_CONNECT_HEADERS +Introduced in 7.54.0. See \fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP. +.IP CURLOPT_TCP_FASTOPEN +Introduced in 7.49.0. See \fICURLOPT_TCP_FASTOPEN(3)\fP. +.IP CURLOPT_TCP_KEEPALIVE +Introduced in 7.25.0. See \fICURLOPT_TCP_KEEPALIVE(3)\fP. +.IP CURLOPT_TCP_KEEPIDLE +Introduced in 7.25.0. See \fICURLOPT_TCP_KEEPIDLE(3)\fP. +.IP CURLOPT_TCP_KEEPINTVL +Introduced in 7.25.0. See \fICURLOPT_TCP_KEEPINTVL(3)\fP. +.IP CURLOPT_TCP_KEEPCNT +Introduced in 8.9.0. See \fICURLOPT_TCP_KEEPCNT(3)\fP. +.IP CURLOPT_TCP_NODELAY +Introduced in 7.11.2. See \fICURLOPT_TCP_NODELAY(3)\fP. +.IP CURLOPT_TELNETOPTIONS +Introduced in 7.7. See \fICURLOPT_TELNETOPTIONS(3)\fP. +.IP CURLOPT_TFTP_BLKSIZE +Introduced in 7.19.4. See \fICURLOPT_TFTP_BLKSIZE(3)\fP. +.IP CURLOPT_TFTP_NO_OPTIONS +Introduced in 7.48.0. See \fICURLOPT_TFTP_NO_OPTIONS(3)\fP. +.IP CURLOPT_TIMECONDITION +Introduced in 7.1. See \fICURLOPT_TIMECONDITION(3)\fP. +.IP CURLOPT_TIMEOUT +Introduced in 7.1. See \fICURLOPT_TIMEOUT(3)\fP. +.IP CURLOPT_TIMEOUT_MS +Introduced in 7.16.2. See \fICURLOPT_TIMEOUT_MS(3)\fP. +.IP CURLOPT_TIMEVALUE +Introduced in 7.1. See \fICURLOPT_TIMEVALUE(3)\fP. +.IP CURLOPT_TIMEVALUE_LARGE +Introduced in 7.59.0. See \fICURLOPT_TIMEVALUE_LARGE(3)\fP. +.IP CURLOPT_TLS13_CIPHERS +Introduced in 7.61.0. See \fICURLOPT_TLS13_CIPHERS(3)\fP. +.IP CURLOPT_TLSAUTH_PASSWORD +Introduced in 7.21.4. See \fICURLOPT_TLSAUTH_PASSWORD(3)\fP. +.IP CURLOPT_TLSAUTH_TYPE +Introduced in 7.21.4. See \fICURLOPT_TLSAUTH_TYPE(3)\fP. +.IP CURLOPT_TLSAUTH_USERNAME +Introduced in 7.21.4. See \fICURLOPT_TLSAUTH_USERNAME(3)\fP. +.IP CURLOPT_TRAILERDATA +Introduced in 7.64.0. See \fICURLOPT_TRAILERDATA(3)\fP. +.IP CURLOPT_TRAILERFUNCTION +Introduced in 7.64.0. See \fICURLOPT_TRAILERFUNCTION(3)\fP. +.IP CURLOPT_TRANSFER_ENCODING +Introduced in 7.21.6. See \fICURLOPT_TRANSFER_ENCODING(3)\fP. +.IP CURLOPT_TRANSFERTEXT +Introduced in 7.1.1. See \fICURLOPT_TRANSFERTEXT(3)\fP. +.IP CURLOPT_UNIX_SOCKET_PATH +Introduced in 7.40.0. See \fICURLOPT_UNIX_SOCKET_PATH(3)\fP. +.IP CURLOPT_UNRESTRICTED_AUTH +Introduced in 7.10.4. See \fICURLOPT_UNRESTRICTED_AUTH(3)\fP. +.IP CURLOPT_UPKEEP_INTERVAL_MS +Introduced in 7.62.0. See \fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP. +.IP CURLOPT_UPLOAD +Introduced in 7.1. See \fICURLOPT_UPLOAD(3)\fP. +.IP CURLOPT_UPLOAD_BUFFERSIZE +Introduced in 7.62.0. See \fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP. +.IP CURLOPT_URL +Introduced in 7.1. See \fICURLOPT_URL(3)\fP. +.IP CURLOPT_USE_SSL +Introduced in 7.17.0. See \fICURLOPT_USE_SSL(3)\fP. +.IP CURLOPT_USERAGENT +Introduced in 7.1. See \fICURLOPT_USERAGENT(3)\fP. +.IP CURLOPT_USERNAME +Introduced in 7.19.1. See \fICURLOPT_USERNAME(3)\fP. +.IP CURLOPT_USERPWD +Introduced in 7.1. See \fICURLOPT_USERPWD(3)\fP. +.IP CURLOPT_VERBOSE +Introduced in 7.1. See \fICURLOPT_VERBOSE(3)\fP. +.IP CURLOPT_WILDCARDMATCH +Introduced in 7.21.0. See \fICURLOPT_WILDCARDMATCH(3)\fP. +.IP CURLOPT_WRITEDATA +Introduced in 7.9.7. See \fICURLOPT_WRITEDATA(3)\fP. +.IP CURLOPT_WRITEFUNCTION +Introduced in 7.1. See \fICURLOPT_WRITEFUNCTION(3)\fP. +.IP CURLOPT_WRITEHEADER +Introduced in 7.1. See CURLOPT_HEADERDATA. +.IP CURLOPT_WRITEINFO +Introduced in 7.1. +.IP CURLOPT_WS_OPTIONS +Introduced in 7.86.0. See \fICURLOPT_WS_OPTIONS(3)\fP. +.IP CURLOPT_XFERINFODATA +Introduced in 7.32.0. See \fICURLOPT_XFERINFODATA(3)\fP. +.IP CURLOPT_XFERINFOFUNCTION +Introduced in 7.32.0. See \fICURLOPT_XFERINFOFUNCTION(3)\fP. +.IP CURLOPT_XOAUTH2_BEARER +Introduced in 7.33.0. See \fICURLOPT_XOAUTH2_BEARER(3)\fP. +.IP CURLOPTDEPRECATED +Introduced in 7.87.0. +.IP CURLOPTTYPE_BLOB +Introduced in 7.71.0. +.IP CURLOPTTYPE_CBPOINT +Introduced in 7.73.0. +.IP CURLOPTTYPE_FUNCTIONPOINT +Introduced in 7.1. +.IP CURLOPTTYPE_LONG +Introduced in 7.1. +.IP CURLOPTTYPE_OBJECTPOINT +Introduced in 7.1. +.IP CURLOPTTYPE_OFF_T +Introduced in 7.11.0. +.IP CURLOPTTYPE_SLISTPOINT +Introduced in 7.65.2. +.IP CURLOPTTYPE_STRINGPOINT +Introduced in 7.46.0. +.IP CURLOPTTYPE_VALUES +Introduced in 7.73.0. +.IP CURLOT_BLOB +Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. +.IP CURLOT_CBPTR +Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. +.IP CURLOT_FLAG_ALIAS +Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. +.IP CURLOT_FUNCTION +Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. +.IP CURLOT_LONG +Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. +.IP CURLOT_OBJECT +Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. +.IP CURLOT_OFF_T +Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. +.IP CURLOT_SLIST +Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. +.IP CURLOT_STRING +Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. +.IP CURLOT_VALUES +Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. +.IP CURLPAUSE_ALL +Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. +.IP CURLPAUSE_CONT +Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. +.IP CURLPAUSE_RECV +Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. +.IP CURLPAUSE_RECV_CONT +Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. +.IP CURLPAUSE_SEND +Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. +.IP CURLPAUSE_SEND_CONT +Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. +.IP CURLPIPE_HTTP1 +Introduced in 7.43.0. See \fICURLMOPT_PIPELINING(3)\fP. +.IP CURLPIPE_MULTIPLEX +Introduced in 7.43.0. See \fICURLMOPT_PIPELINING(3)\fP. +.IP CURLPIPE_NOTHING +Introduced in 7.43.0. See \fICURLMOPT_PIPELINING(3)\fP. +.IP CURLPROTO_ALL +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_DICT +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_FILE +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_FTP +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_FTPS +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_GOPHER +Introduced in 7.21.2. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_GOPHERS +Introduced in 7.75.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_HTTP +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_HTTPS +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_IMAP +Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_IMAPS +Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_LDAP +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_LDAPS +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_MQTT +Introduced in 7.71.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_POP3 +Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_POP3S +Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_RTMP +Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_RTMPE +Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_RTMPS +Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_RTMPT +Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_RTMPTE +Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_RTMPTS +Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_RTSP +Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_SCP +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_SFTP +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_SMB +Introduced in 7.40.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_SMBS +Introduced in 7.40.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_SMTP +Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_SMTPS +Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_TELNET +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROTO_TFTP +Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. +.IP CURLPROXY_HTTP +Introduced in 7.10. See \fICURLOPT_PROXYTYPE(3)\fP. +.IP CURLPROXY_HTTP_1_0 +Introduced in 7.19.4. See \fICURLOPT_PROXYTYPE(3)\fP. +.IP CURLPROXY_HTTPS +Introduced in 7.52.0. See \fICURLOPT_PROXYTYPE(3)\fP. +.IP CURLPROXY_HTTPS2 +Introduced in 8.1.0. See \fICURLOPT_PROXYTYPE(3)\fP. +.IP CURLPROXY_SOCKS4 +Introduced in 7.10. See \fICURLOPT_PROXYTYPE(3)\fP. +.IP CURLPROXY_SOCKS4A +Introduced in 7.18.0. See \fICURLOPT_PROXYTYPE(3)\fP. +.IP CURLPROXY_SOCKS5 +Introduced in 7.10. See \fICURLOPT_PROXYTYPE(3)\fP. +.IP CURLPROXY_SOCKS5_HOSTNAME +Introduced in 7.18.0. See \fICURLOPT_PROXYTYPE(3)\fP. +.IP CURLPX_BAD_ADDRESS_TYPE +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_BAD_VERSION +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_CLOSED +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_GSSAPI +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_GSSAPI_PERMSG +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_GSSAPI_PROTECTION +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_IDENTD +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_IDENTD_DIFFER +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_LONG_HOSTNAME +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_LONG_PASSWD +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_LONG_USER +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_NO_AUTH +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_OK +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_RECV_ADDRESS +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_RECV_AUTH +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_RECV_CONNECT +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_RECV_REQACK +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_REPLY_ADDRESS_TYPE_NOT_SUPPORTED +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_REPLY_COMMAND_NOT_SUPPORTED +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_REPLY_CONNECTION_REFUSED +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_REPLY_GENERAL_SERVER_FAILURE +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_REPLY_HOST_UNREACHABLE +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_REPLY_NETWORK_UNREACHABLE +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_REPLY_NOT_ALLOWED +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_REPLY_TTL_EXPIRED +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_REPLY_UNASSIGNED +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_REQUEST_FAILED +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_RESOLVE_HOST +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_SEND_AUTH +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_SEND_CONNECT +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_SEND_REQUEST +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_UNKNOWN_FAIL +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_UNKNOWN_MODE +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLPX_USER_REJECTED +Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. +.IP CURLSHE_BAD_OPTION +Introduced in 7.10.3. See \fIlibcurl\-errors(3)\fP. +.IP CURLSHE_IN_USE +Introduced in 7.10.3. See \fIlibcurl\-errors(3)\fP. +.IP CURLSHE_INVALID +Introduced in 7.10.3. See \fIlibcurl\-errors(3)\fP. +.IP CURLSHE_NOMEM +Introduced in 7.12.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLSHE_NOT_BUILT_IN +Introduced in 7.23.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLSHE_OK +Introduced in 7.10.3. See \fIlibcurl\-errors(3)\fP. +.IP CURLSHOPT_LOCKFUNC +Introduced in 7.10.3. See \fICURLSHOPT_LOCKFUNC(3)\fP. +.IP CURLSHOPT_NONE +Introduced in 7.10.3. See \fIcurl_share_setopt(3)\fP. +.IP CURLSHOPT_SHARE +Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. +.IP CURLSHOPT_UNLOCKFUNC +Introduced in 7.10.3. See \fICURLSHOPT_UNLOCKFUNC(3)\fP. +.IP CURLSHOPT_UNSHARE +Introduced in 7.10.3. See \fICURLSHOPT_UNSHARE(3)\fP. +.IP CURLSHOPT_USERDATA +Introduced in 7.10.3. See \fICURLSHOPT_USERDATA(3)\fP. +.IP CURLSOCKTYPE_ACCEPT +Introduced in 7.28.0. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP. +.IP CURLSOCKTYPE_IPCXN +Introduced in 7.16.0. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP. +.IP CURLSSH_AUTH_AGENT +Introduced in 7.28.0. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. +.IP CURLSSH_AUTH_ANY +Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. +.IP CURLSSH_AUTH_DEFAULT +Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. +.IP CURLSSH_AUTH_GSSAPI +Introduced in 7.58.0. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. +.IP CURLSSH_AUTH_HOST +Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. +.IP CURLSSH_AUTH_KEYBOARD +Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. +.IP CURLSSH_AUTH_NONE +Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. +.IP CURLSSH_AUTH_PASSWORD +Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. +.IP CURLSSH_AUTH_PUBLICKEY +Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. +.IP CURLSSLBACKEND_AWSLC +Introduced in 8.1.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_AXTLS +Introduced in 7.38.0. Deprecated since 7.61.0. +.IP CURLSSLBACKEND_BEARSSL +Introduced in 7.68.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_BORINGSSL +Introduced in 7.49.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_CYASSL +Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_DARWINSSL +Introduced in 7.34.0. Deprecated since 7.64.1. +.IP CURLSSLBACKEND_GNUTLS +Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_GSKIT +Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_LIBRESSL +Introduced in 7.49.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_MBEDTLS +Introduced in 7.46.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_MESALINK +Introduced in 7.62.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_NONE +Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_NSS +Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_OPENSSL +Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_POLARSSL +Introduced in 7.34.0. Deprecated since 7.69.0. +.IP CURLSSLBACKEND_QSOSSL +Introduced in 7.34.0. Last used in 7.38.0. +.IP CURLSSLBACKEND_RUSTLS +Introduced in 7.76.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_SCHANNEL +Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_SECURETRANSPORT +Introduced in 7.64.1. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLBACKEND_WOLFSSL +Introduced in 7.49.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLOPT_ALLOW_BEAST +Introduced in 7.25.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. +.IP CURLSSLOPT_AUTO_CLIENT_CERT +Introduced in 7.77.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. +.IP CURLSSLOPT_NATIVE_CA +Introduced in 7.71.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. +.IP CURLSSLOPT_NO_PARTIALCHAIN +Introduced in 7.68.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. +.IP CURLSSLOPT_NO_REVOKE +Introduced in 7.44.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. +.IP CURLSSLOPT_REVOKE_BEST_EFFORT +Introduced in 7.70.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. +.IP CURLSSLSET_NO_BACKENDS +Introduced in 7.56.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLSET_OK +Introduced in 7.56.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLSET_TOO_LATE +Introduced in 7.56.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSSLSET_UNKNOWN_BACKEND +Introduced in 7.56.0. See \fIcurl_global_sslset(3)\fP. +.IP CURLSTS_DONE +Introduced in 7.74.0. See \fICURLOPT_HSTSREADFUNCTION(3)\fP. +.IP CURLSTS_FAIL +Introduced in 7.74.0. See \fICURLOPT_HSTSREADFUNCTION(3)\fP. +.IP CURLSTS_OK +Introduced in 7.74.0. See \fICURLOPT_HSTSREADFUNCTION(3)\fP. +.IP CURLU_ALLOW_SPACE +Introduced in 7.78.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_APPENDQUERY +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_DEFAULT_PORT +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_DEFAULT_SCHEME +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_DISALLOW_USER +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_GET_EMPTY +Introduced in 8.8.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_GUESS_SCHEME +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_NO_AUTHORITY +Introduced in 7.67.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_NO_DEFAULT_PORT +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_NO_GUESS_SCHEME +Introduced in 8.9.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_NON_SUPPORT_SCHEME +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_PATH_AS_IS +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_PUNY2IDN +Introduced in 8.3.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_PUNYCODE +Introduced in 7.88.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_URLDECODE +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLU_URLENCODE +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLUE_BAD_FILE_URL +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_FRAGMENT +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_HANDLE +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_HOSTNAME +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_IPV6 +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_LOGIN +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_PARTPOINTER +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_PASSWORD +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_PATH +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_PORT_NUMBER +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_QUERY +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_SCHEME +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_SLASHES +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_BAD_USER +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_LACKS_IDN +Introduced in 7.88.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_MALFORMED_INPUT +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_NO_FRAGMENT +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_NO_HOST +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_NO_OPTIONS +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_NO_PASSWORD +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_NO_PORT +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_NO_QUERY +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_NO_SCHEME +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_NO_USER +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_NO_ZONEID +Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_OK +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_OUT_OF_MEMORY +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_TOO_LARGE +Introduced in 8.6.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_UNKNOWN_PART +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_UNSUPPORTED_SCHEME +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_URLDECODE +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUE_USER_NOT_ALLOWED +Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. +.IP CURLUPART_FRAGMENT +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLUPART_HOST +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLUPART_OPTIONS +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLUPART_PASSWORD +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLUPART_PATH +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLUPART_PORT +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLUPART_QUERY +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLUPART_SCHEME +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLUPART_URL +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLUPART_USER +Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. +.IP CURLUPART_ZONEID +Introduced in 7.65.0. See \fIcurl_url_get(3)\fP. +.IP CURLUSESSL_ALL +Introduced in 7.17.0. See \fICURLOPT_USE_SSL(3)\fP. +.IP CURLUSESSL_CONTROL +Introduced in 7.17.0. See \fICURLOPT_USE_SSL(3)\fP. +.IP CURLUSESSL_NONE +Introduced in 7.17.0. See \fICURLOPT_USE_SSL(3)\fP. +.IP CURLUSESSL_TRY +Introduced in 7.17.0. See \fICURLOPT_USE_SSL(3)\fP. +.IP CURLVERSION_EIGHTH +Introduced in 7.72.0. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_ELEVENTH +Introduced in 7.87.0. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_FIFTH +Introduced in 7.57.0. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_FIRST +Introduced in 7.10. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_FOURTH +Introduced in 7.16.1. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_NINTH +Introduced in 7.75.0. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_NOW +Introduced in 7.10. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_SECOND +Introduced in 7.11.1. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_SEVENTH +Introduced in 7.70.0. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_SIXTH +Introduced in 7.66.0. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_TENTH +Introduced in 7.77.0. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_THIRD +Introduced in 7.12.0. See \fIcurl_version_info(3)\fP. +.IP CURLVERSION_TWELFTH +Introduced in 8.8.0. See \fIcurl_version_info(3)\fP. +.IP CURLWARNING +Introduced in 7.66.0. +.IP CURLWS_BINARY +Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. +.IP CURLWS_CLOSE +Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. +.IP CURLWS_CONT +Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. +.IP CURLWS_OFFSET +Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. +.IP CURLWS_PING +Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. +.IP CURLWS_PONG +Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. +.IP CURLWS_RAW_MODE +Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. +.IP CURLWS_TEXT +Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. +.SH SEE ALSO +.BR libcurl (3), +.BR libcurl-easy (3), +.BR libcurl-multi (3), +.BR libcurl-security (3), +.BR libcurl-thread (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-thread.3 b/3rdparty/curl/share/man/man3/libcurl-thread.3 new file mode 100644 index 0000000..aec0ab9 --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-thread.3 @@ -0,0 +1,90 @@ +.\" generated by cd2nroff 0.1 from libcurl-thread.md +.TH libcurl-thread 3 "2024-10-11" libcurl +.SH NAME +libcurl\-thread \- libcurl thread safety +.SH Multi-threading with libcurl +libcurl is thread safe but has no internal thread synchronization. You may have +to provide your own locking should you meet any of the thread safety exceptions +below. +.SH Handles +You must \fBnever\fP share the same handle in multiple threads. You can pass the +handles around among threads, but you must never use a single handle from more +than one thread at any given time. +.SH Shared objects +You can share certain data between multiple handles by using the share +interface but you must provide your own locking and set +\fIcurl_share_setopt(3)\fP CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC. + +Note that some items are specifically documented as not thread\-safe in the +share API (the connection pool and HSTS cache for example). +.SH TLS +All current TLS libraries libcurl supports are thread\-safe. +.IP OpenSSL +OpenSSL 1.1.0+ can be safely used in multi\-threaded applications provided that +support for the underlying OS threading API is built\-in. For older versions of +OpenSSL, the user must set mutex callbacks. + +libcurl may not be able to fully clean up after multi\-threaded OpenSSL +depending on how OpenSSL was built and loaded as a library. It is possible in +some rare circumstances a memory leak could occur unless you implement your own +OpenSSL thread cleanup. + +For example, on Windows if both libcurl and OpenSSL are linked statically to a +DLL or application then OpenSSL may leak memory unless the DLL or application +calls OPENSSL_thread_stop() before each thread terminates. If OpenSSL is built +as a DLL then it does this cleanup automatically and there is no leak. If +libcurl is built as a DLL and OpenSSL is linked statically to it then libcurl +does this cleanup automatically and there is no leak (added in libcurl 8.8.0). + +Please review the OpenSSL documentation for a full list of circumstances: +https://docs.openssl.org/3.0/man3/OPENSSL_init_crypto/#notes +.SH Signals +Signals are used for timing out name resolves (during DNS lookup) \- when built +without using either the c\-ares or threaded resolver backends. On systems that +have a signal concept. + +When using multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP +option to 1L for all handles. Everything works fine except that timeouts +cannot be honored during DNS lookups \- which you can work around by building +libcurl with c\-ares or threaded\-resolver support. c\-ares is a library that +provides asynchronous name resolves. On some platforms, libcurl simply cannot +function properly multi\-threaded unless the \fICURLOPT_NOSIGNAL(3)\fP option +is set. + +When \fICURLOPT_NOSIGNAL(3)\fP is set to 1L, your application needs to deal +with the risk of a SIGPIPE (that at least the OpenSSL backend can +trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L does not work in a +threaded situation as there is a race condition where libcurl risks restoring +the former signal handler while another thread should still ignore it. +.SH Name resolving +The \fBgethostbyname\fP or \fBgetaddrinfo\fP and other name resolving system +calls used by libcurl are provided by your operating system and must be thread +safe. It is important that libcurl can find and use thread safe versions of +these and other system calls, as otherwise it cannot function fully thread +safe. Some operating systems are known to have faulty thread +implementations. We have previously received problem reports on *BSD (at least +in the past, they may be working fine these days). Some operating systems that +are known to have solid and working thread support are Linux, Solaris and +Windows. +.SH curl_global_* functions +These functions are thread\-safe since libcurl 7.84.0 if +\fIcurl_version_info(3)\fP has the \fBCURL_VERSION_THREADSAFE\fP feature bit +set (most platforms). + +If these functions are not thread\-safe and you are using libcurl with multiple +threads it is especially important that before use you call +\fIcurl_global_init(3)\fP or \fIcurl_global_init_mem(3)\fP to explicitly +initialize the library and its dependents, rather than rely on the "lazy" +fail\-safe initialization that takes place the first time +\fIcurl_easy_init(3)\fP is called. For an in\-depth explanation refer to +\fIlibcurl(3)\fP section \fBGLOBAL CONSTANTS\fP. +.SH Memory functions +These functions, provided either by your operating system or your own +replacements, must be thread safe. You can use \fIcurl_global_init_mem(3)\fP +to set your own replacement memory functions. +.SH Non-safe functions +\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread\-safe. + +\fIcurl_version_info(3)\fP is not thread\-safe before libcurl initialization. +.SH SEE ALSO +.BR libcurl-security (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-tutorial.3 b/3rdparty/curl/share/man/man3/libcurl-tutorial.3 new file mode 100644 index 0000000..7667c6d --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-tutorial.3 @@ -0,0 +1,1347 @@ +.\" generated by cd2nroff 0.1 from libcurl-tutorial.md +.TH libcurl-tutorial 3 "2024-10-11" libcurl +.SH NAME +libcurl\-tutorial \- libcurl programming tutorial +.SH Objective +This document attempts to describe the general principles and some basic +approaches to consider when programming with libcurl. The text focuses on the +C interface but should apply fairly well on other language bindings as well as +they usually follow the C API pretty closely. + +This document refers to \(aqthe user\(aq as the person writing the source code that +uses libcurl. That would probably be you or someone in your position. What is +generally referred to as \(aqthe program\(aq is the collected source code that you +write that is using libcurl for transfers. The program is outside libcurl and +libcurl is outside of the program. + +To get more details on all options and functions described herein, please +refer to their respective man pages. +.SH Building +There are many different ways to build C programs. This chapter assumes a Unix +style build process. If you use a different build system, you can still read +this to get general information that may apply to your environment as well. +.IP "Compiling the Program" +Your compiler needs to know where the libcurl headers are located. Therefore +you must set your compiler\(aqs include path to point to the directory where you +installed them. The \(aqcurl\-config\(aq[3] tool can be used to get this information: +.nf + $ curl-config --cflags +.fi +.IP "Linking the Program with libcurl" +When having compiled the program, you need to link your object files to create +a single executable. For that to succeed, you need to link with libcurl and +possibly also with other libraries that libcurl itself depends on. Like the +OpenSSL libraries, but even some standard OS libraries may be needed on the +command line. To figure out which flags to use, once again the \(aqcurl\-config\(aq +tool comes to the rescue: +.nf + $ curl-config --libs +.fi +.IP "SSL or Not" +libcurl can be built and customized in many ways. One of the things that +varies from different libraries and builds is the support for SSL\-based +transfers, like HTTPS and FTPS. If a supported SSL library was detected +properly at build\-time, libcurl is built with SSL support. To figure out if an +installed libcurl has been built with SSL support enabled, use \fIcurl\-config\fP +like this: + +.nf + $ curl-config --feature +.fi + +If SSL is supported, the keyword \fISSL\fP is written to stdout, possibly together +with a other features that could be either on or off on for different +libcurls. + +See also the "Features libcurl Provides" further down. +.IP "autoconf macro" +When you write your configure script to detect libcurl and setup variables +accordingly, we offer a macro that probably does everything you need in this +area. See docs/libcurl/libcurl.m4 file \- it includes docs on how to use it. +.SH Portable Code in a Portable World +The people behind libcurl have put a considerable effort to make libcurl work +on a large amount of different operating systems and environments. + +You program libcurl the same way on all platforms that libcurl runs on. There +are only a few minor details that differ. If you just make sure to write your +code portable enough, you can create a portable program. libcurl should not +stop you from that. +.SH Global Preparation +The program must initialize some of the libcurl functionality globally. That +means it should be done exactly once, no matter how many times you intend to +use the library. Once for your program\(aqs entire life time. This is done using +.nf + curl_global_init() +.fi +and it takes one parameter which is a bit pattern that tells libcurl what to +initialize. Using \fICURL_GLOBAL_ALL\fP makes it initialize all known internal +sub modules, and might be a good default option. The current two bits that are +specified are: +.IP CURL_GLOBAL_WIN32 +which only does anything on Windows machines. When used on a Windows machine, +it makes libcurl initialize the Win32 socket stuff. Without having that +initialized properly, your program cannot use sockets properly. You should +only do this once for each application, so if your program already does this +or of another library in use does it, you should not tell libcurl to do this +as well. +.IP CURL_GLOBAL_SSL +which only does anything on libcurls compiled and built SSL\-enabled. On these +systems, this makes libcurl initialize the SSL library properly for this +application. This only needs to be done once for each application so if your +program or another library already does this, this bit should not be needed. + +libcurl has a default protection mechanism that detects if +\fIcurl_global_init(3)\fP has not been called by the time +\fIcurl_easy_perform(3)\fP is called and if that is the case, libcurl runs the +function itself with a guessed bit pattern. Please note that depending solely +on this is not considered nice nor good. + +When the program no longer uses libcurl, it should call +\fIcurl_global_cleanup(3)\fP, which is the opposite of the init call. It +performs the reversed operations to cleanup the resources the +\fIcurl_global_init(3)\fP call initialized. + +Repeated calls to \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP +should be avoided. They should only be called once each. +.SH Features libcurl Provides +It is considered best\-practice to determine libcurl features at runtime rather +than at build\-time (if possible of course). By calling +\fIcurl_version_info(3)\fP and checking out the details of the returned +struct, your program can figure out exactly what the currently running libcurl +supports. +.SH Two Interfaces +libcurl first introduced the so called easy interface. All operations in the +easy interface are prefixed with \(aqcurl_easy\(aq. The easy interface lets you do +single transfers with a synchronous and blocking function call. + +libcurl also offers another interface that allows multiple simultaneous +transfers in a single thread, the so called multi interface. More about that +interface is detailed in a separate chapter further down. You still need to +understand the easy interface first, so please continue reading for better +understanding. +.SH Handle the Easy libcurl +To use the easy interface, you must first create yourself an easy handle. You +need one handle for each easy session you want to perform. Basically, you +should use one handle for every thread you plan to use for transferring. You +must never share the same handle in multiple threads. + +Get an easy handle with +.nf + handle = curl_easy_init(); +.fi +It returns an easy handle. Using that you proceed to the next step: setting +up your preferred actions. A handle is just a logic entity for the upcoming +transfer or series of transfers. + +You set properties and options for this handle using +\fIcurl_easy_setopt(3)\fP. They control how the subsequent transfer or +transfers using this handle are made. Options remain set in the handle until +set again to something different. They are sticky. Multiple requests using the +same handle use the same options. + +If you at any point would like to blank all previously set options for a +single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also +make a clone of an easy handle (with all its set options) using +\fIcurl_easy_duphandle(3)\fP. + +Many of the options you set in libcurl are "strings", pointers to data +terminated with a zero byte. When you set strings with +\fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they do not need +to be kept around in your application after being set[4]. + +One of the most basic properties to set in the handle is the URL. You set your +preferred URL to transfer with \fICURLOPT_URL(3)\fP in a manner similar to: + +.nf + curl_easy_setopt(handle, CURLOPT_URL, "http://domain.com/"); +.fi + +Let\(aqs assume for a while that you want to receive data as the URL identifies a +remote resource you want to get here. Since you write a sort of application +that needs this transfer, I assume that you would like to get the data passed +to you directly instead of simply getting it passed to stdout. So, you write +your own function that matches this prototype: +.nf + size_t write_data(void *buffer, size_t size, size_t nmemb, void *userp); +.fi +You tell libcurl to pass all data to this function by issuing a function +similar to this: +.nf + curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, write_data); +.fi +You can control what data your callback function gets in the fourth argument +by setting another property: +.nf + curl_easy_setopt(handle, CURLOPT_WRITEDATA, &internal_struct); +.fi +Using that property, you can easily pass local data between your application +and the function that gets invoked by libcurl. libcurl itself does not touch +the data you pass with \fICURLOPT_WRITEDATA(3)\fP. + +libcurl offers its own default internal callback that takes care of the data +if you do not set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It simply +outputs the received data to stdout. You can have the default callback write +the data to a different file handle by passing a \(aqFILE *\(aq to a file opened for +writing with the \fICURLOPT_WRITEDATA(3)\fP option. + +Now, we need to take a step back and take a deep breath. Here is one of those +rare platform\-dependent nitpicks. Did you spot it? On some platforms[2], +libcurl is not able to operate on file handles opened by the +program. Therefore, if you use the default callback and pass in an open file +handle with \fICURLOPT_WRITEDATA(3)\fP, libcurl crashes. You should avoid this +to make your program run fine virtually everywhere. + +(\fICURLOPT_WRITEDATA(3)\fP was formerly known as \fICURLOPT_FILE\fP. Both names still +work and do the same thing). + +If you are using libcurl as a Windows DLL, you MUST use the +\fICURLOPT_WRITEFUNCTION(3)\fP if you set \fICURLOPT_WRITEDATA(3)\fP \- or experience +crashes. + +There are of course many more options you can set, and we get back to a few of +them later. Let\(aqs instead continue to the actual transfer: + +.nf + success = curl_easy_perform(handle); +.fi + +\fIcurl_easy_perform(3)\fP connects to the remote site, does the necessary commands +and performs the transfer. Whenever it receives data, it calls the callback +function we previously set. The function may get one byte at a time, or it may +get many kilobytes at once. libcurl delivers as much as possible as often as +possible. Your callback function should return the number of bytes it "took +care of". If that is not the same amount of bytes that was passed to it, +libcurl aborts the operation and returns with an error code. + +When the transfer is complete, the function returns a return code that informs +you if it succeeded in its mission or not. If a return code is not enough for +you, you can use the \fICURLOPT_ERRORBUFFER(3)\fP to point libcurl to a buffer of +yours where it stores a human readable error message as well. + +If you then want to transfer another file, the handle is ready to be used +again. It is even preferred and encouraged that you reuse an existing handle +if you intend to make another transfer. libcurl then attempts to reuse a +previous connection. + +For some protocols, downloading a file can involve a complicated process of +logging in, setting the transfer mode, changing the current directory and +finally transferring the file data. libcurl takes care of all that +complication for you. Given simply the URL to a file, libcurl takes care of +all the details needed to get the file moved from one machine to another. +.SH Multi-threading Issues +libcurl is thread safe but there are a few exceptions. Refer to +\fIlibcurl\-thread(3)\fP for more information. +.SH When It does not Work +There are times when the transfer fails for some reason. You might have set +the wrong libcurl option or misunderstood what the libcurl option actually +does, or the remote server might return non\-standard replies that confuse the +library which then confuses your program. + +There is one golden rule when these things occur: set the +\fICURLOPT_VERBOSE(3)\fP option to 1. it causes the library to spew out the +entire protocol details it sends, some internal info and some received +protocol data as well (especially when using FTP). If you are using HTTP, +adding the headers in the received output to study is also a clever way to get +a better understanding why the server behaves the way it does. Include headers +in the normal body output with \fICURLOPT_HEADER(3)\fP set 1. + +Of course, there are bugs left. We need to know about them to be able to fix +them, so we are quite dependent on your bug reports. When you do report +suspected bugs in libcurl, please include as many details as you possibly can: +a protocol dump that \fICURLOPT_VERBOSE(3)\fP produces, library version, as +much as possible of your code that uses libcurl, operating system name and +version, compiler name and version etc. + +If \fICURLOPT_VERBOSE(3)\fP is not enough, you increase the level of debug +data your application receive by using the \fICURLOPT_DEBUGFUNCTION(3)\fP. + +Getting some in\-depth knowledge about the protocols involved is never wrong, +and if you are trying to do funny things, you might understand libcurl and how +to use it better if you study the appropriate RFC documents at least briefly. +.SH Upload Data to a Remote Site +libcurl tries to keep a protocol independent approach to most transfers, thus +uploading to a remote FTP site is similar to uploading data to an HTTP server +with a PUT request. + +Of course, first you either create an easy handle or you reuse one existing +one. Then you set the URL to operate on just like before. This is the remote +URL, that we now upload. + +Since we write an application, we most likely want libcurl to get the upload +data by asking us for it. To make it do that, we set the read callback and the +custom pointer libcurl passes to our read callback. The read callback should +have a prototype similar to: +.nf + size_t function(char *bufptr, size_t size, size_t nitems, void *userp); +.fi +Where \fIbufptr\fP is the pointer to a buffer we fill in with data to upload +and \fIsize\fPnitems* is the size of the buffer and therefore also the maximum +amount of data we can return to libcurl in this call. The \fIuserp\fP pointer +is the custom pointer we set to point to a struct of ours to pass private data +between the application and the callback. +.nf + curl_easy_setopt(handle, CURLOPT_READFUNCTION, read_function); + + curl_easy_setopt(handle, CURLOPT_READDATA, &filedata); +.fi +Tell libcurl that we want to upload: +.nf + curl_easy_setopt(handle, CURLOPT_UPLOAD, 1L); +.fi +A few protocols do not behave properly when uploads are done without any prior +knowledge of the expected file size. So, set the upload file size using the +\fICURLOPT_INFILESIZE_LARGE(3)\fP for all known file sizes like this[1]: + +.nf + /* in this example, file_size must be an curl_off_t variable */ + curl_easy_setopt(handle, CURLOPT_INFILESIZE_LARGE, file_size); +.fi + +When you call \fIcurl_easy_perform(3)\fP this time, it performs all the +necessary operations and when it has invoked the upload it calls your supplied +callback to get the data to upload. The program should return as much data as +possible in every invoke, as that is likely to make the upload perform as fast +as possible. The callback should return the number of bytes it wrote in the +buffer. Returning 0 signals the end of the upload. +.SH Passwords +Many protocols use or even require that username and password are provided +to be able to download or upload the data of your choice. libcurl offers +several ways to specify them. + +Most protocols support that you specify the name and password in the URL +itself. libcurl detects this and use them accordingly. This is written like +this: +.nf + protocol://user:password@example.com/path/ +.fi +If you need any odd letters in your username or password, you should enter +them URL encoded, as %XX where XX is a two\-digit hexadecimal number. + +libcurl also provides options to set various passwords. The username and +password as shown embedded in the URL can instead get set with the +\fICURLOPT_USERPWD(3)\fP option. The argument passed to libcurl should be a +char * to a string in the format "user:password". In a manner like this: + +.nf + curl_easy_setopt(handle, CURLOPT_USERPWD, "myname:thesecret"); +.fi + +Another case where name and password might be needed at times, is for those +users who need to authenticate themselves to a proxy they use. libcurl offers +another option for this, the \fICURLOPT_PROXYUSERPWD(3)\fP. It is used quite similar +to the \fICURLOPT_USERPWD(3)\fP option like this: + +.nf + curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); +.fi + +There is a long time Unix "standard" way of storing FTP usernames and +passwords, namely in the $HOME/.netrc file (on Windows, libcurl also checks +the \fI%USERPROFILE% environment\fP variable if \fI%HOME%\fP is unset, and tries +\&"_netrc" as name). The file should be made private so that only the user may +read it (see also the "Security Considerations" chapter), as it might contain +the password in plain text. libcurl has the ability to use this file to figure +out what set of username and password to use for a particular host. As an +extension to the normal functionality, libcurl also supports this file for +non\-FTP protocols such as HTTP. To make curl use this file, use the +\fICURLOPT_NETRC(3)\fP option: + +.nf + curl_easy_setopt(handle, CURLOPT_NETRC, 1L); +.fi + +A basic example of how such a .netrc file may look like: + +.nf + machine myhost.mydomain.com + login userlogin + password secretword +.fi + +All these examples have been cases where the password has been optional, or +at least you could leave it out and have libcurl attempt to do its job +without it. There are times when the password is not optional, like when +you are using an SSL private key for secure transfers. + +To pass the known private key password to libcurl: +.nf + curl_easy_setopt(handle, CURLOPT_KEYPASSWD, "keypassword"); +.fi +.SH HTTP Authentication +The previous chapter showed how to set username and password for getting URLs +that require authentication. When using the HTTP protocol, there are many +different ways a client can provide those credentials to the server and you +can control which way libcurl uses them. The default HTTP authentication +method is called \(aqBasic\(aq, which is sending the name and password in clear\-text +in the HTTP request, base64\-encoded. This is insecure. + +At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM, +Negotiate (SPNEGO). You can tell libcurl which one to use with +\fICURLOPT_HTTPAUTH(3)\fP as in: + +.nf + curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST); + +.fi + +When you send authentication to a proxy, you can also set authentication type +the same way but instead with \fICURLOPT_PROXYAUTH(3)\fP: + +.nf + curl_easy_setopt(handle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM); +.fi + +Both these options allow you to set multiple types (by ORing them together), +to make libcurl pick the most secure one out of the types the server/proxy +claims to support. This method does however add a round\-trip since libcurl +must first ask the server what it supports: + +.nf + curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST|CURLAUTH_BASIC); +.fi + +For convenience, you can use the \fICURLAUTH_ANY\fP define (instead of a list with +specific types) which allows libcurl to use whatever method it wants. + +When asking for multiple types, libcurl picks the available one it considers +\&"best" in its own internal order of preference. +.SH HTTP POSTing +We get many questions regarding how to issue HTTP POSTs with libcurl the +proper way. This chapter thus includes examples using both different versions +of HTTP POST that libcurl supports. + +The first version is the simple POST, the most common version, that most HTML +pages using the
tag uses. We provide a pointer to the data and tell +libcurl to post it all to the remote site: + +.nf + char *data="name=daniel&project=curl"; + curl_easy_setopt(handle, CURLOPT_POSTFIELDS, data); + curl_easy_setopt(handle, CURLOPT_URL, "http://posthere.com/"); + + curl_easy_perform(handle); /* post away! */ +.fi + +Simple enough, huh? Since you set the POST options with the +\fICURLOPT_POSTFIELDS(3)\fP, this automatically switches the handle to use +POST in the upcoming request. + +What if you want to post binary data that also requires you to set the +Content\-Type: header of the post? Well, binary posts prevent libcurl from being +able to do strlen() on the data to figure out the size, so therefore we must +tell libcurl the size of the post data. Setting headers in libcurl requests are +done in a generic way, by building a list of our own headers and then passing +that list to libcurl. + +.nf + struct curl_slist *headers=NULL; + headers = curl_slist_append(headers, "Content-Type: text/xml"); + + /* post binary data */ + curl_easy_setopt(handle, CURLOPT_POSTFIELDS, binaryptr); + + /* set the size of the postfields data */ + curl_easy_setopt(handle, CURLOPT_POSTFIELDSIZE, 23L); + + /* pass our list of custom made headers */ + curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); + + curl_easy_perform(handle); /* post away! */ + + curl_slist_free_all(headers); /* free the header list */ +.fi + +While the simple examples above cover the majority of all cases where HTTP +POST operations are required, they do not do multi\-part formposts. Multi\-part +formposts were introduced as a better way to post (possibly large) binary data +and were first documented in the RFC 1867 (updated in RFC 2388). They are +called multi\-part because they are built by a chain of parts, each part being +a single unit of data. Each part has its own name and contents. You can in +fact create and post a multi\-part formpost with the regular libcurl POST +support described above, but that would require that you build a formpost +yourself and provide to libcurl. + +To make that easier, libcurl provides a MIME API consisting in several +functions: using those, you can create and fill a multi\-part form. Function +\fIcurl_mime_init(3)\fP creates a multi\-part body; you can then append new parts +to a multi\-part body using \fIcurl_mime_addpart(3)\fP. + +There are three possible data sources for a part: memory using +\fIcurl_mime_data(3)\fP, file using \fIcurl_mime_filedata(3)\fP and user\-defined data +read callback using \fIcurl_mime_data_cb(3)\fP. \fIcurl_mime_name(3)\fP sets a part\(aqs +(i.e.: form field) name, while \fIcurl_mime_filename(3)\fP fills in the remote +filename. With \fIcurl_mime_type(3)\fP, you can tell the MIME type of a part, +\fIcurl_mime_headers(3)\fP allows defining the part\(aqs headers. When a multi\-part +body is no longer needed, you can destroy it using \fIcurl_mime_free(3)\fP. + +The following example sets two simple text parts with plain textual contents, +and then a file with binary contents and uploads the whole thing. + +.nf + curl_mime *multipart = curl_mime_init(handle); + curl_mimepart *part = curl_mime_addpart(multipart); + curl_mime_name(part, "name"); + curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); + part = curl_mime_addpart(multipart); + curl_mime_name(part, "project"); + curl_mime_data(part, "curl", CURL_ZERO_TERMINATED); + part = curl_mime_addpart(multipart); + curl_mime_name(part, "logotype-image"); + curl_mime_filedata(part, "curl.png"); + + /* Set the form info */ + curl_easy_setopt(handle, CURLOPT_MIMEPOST, multipart); + + curl_easy_perform(handle); /* post away! */ + + /* free the post data again */ + curl_mime_free(multipart); +.fi + +To post multiple files for a single form field, you must supply each file in +a separate part, all with the same field name. Although function +\fIcurl_mime_subparts(3)\fP implements nested multi\-parts, this way of +multiple files posting is deprecated by RFC 7578, chapter 4.3. + +To set the data source from an already opened FILE pointer, use: + +.nf + curl_mime_data_cb(part, filesize, (curl_read_callback) fread, + (curl_seek_callback) fseek, NULL, filepointer); +.fi + +A deprecated \fIcurl_formadd(3)\fP function is still supported in libcurl. +It should however not be used anymore for new designs and programs using it +ought to be converted to the MIME API. It is however described here as an +aid to conversion. + +Using \fIcurl_formadd\fP, you add parts to the form. When you are done adding +parts, you post the whole form. + +The MIME API example above is expressed as follows using this function: + +.nf + struct curl_httppost *post=NULL; + struct curl_httppost *last=NULL; + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "name", + CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END); + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "project", + CURLFORM_COPYCONTENTS, "curl", CURLFORM_END); + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "logotype-image", + CURLFORM_FILECONTENT, "curl.png", CURLFORM_END); + + /* Set the form info */ + curl_easy_setopt(handle, CURLOPT_HTTPPOST, post); + + curl_easy_perform(handle); /* post away! */ + + /* free the post data again */ + curl_formfree(post); +.fi + +Multipart formposts are chains of parts using MIME\-style separators and +headers. It means that each one of these separate parts get a few headers set +that describe the individual content\-type, size etc. To enable your +application to handicraft this formpost even more, libcurl allows you to +supply your own set of custom headers to such an individual form part. You can +of course supply headers to as many parts as you like, but this little example +shows how you set headers to one specific part when you add that to the post +handle: + +.nf + struct curl_slist *headers=NULL; + headers = curl_slist_append(headers, "Content-Type: text/xml"); + + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "logotype-image", + CURLFORM_FILECONTENT, "curl.xml", + CURLFORM_CONTENTHEADER, headers, + CURLFORM_END); + + curl_easy_perform(handle); /* post away! */ + + curl_formfree(post); /* free post */ + curl_slist_free_all(headers); /* free custom header list */ +.fi + +Since all options on an easy handle are "sticky", they remain the same until +changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell +curl to go back to a plain GET request if you intend to do one as your next +request. You force an easy handle to go back to GET by using the +\fICURLOPT_HTTPGET(3)\fP option: +.nf + curl_easy_setopt(handle, CURLOPT_HTTPGET, 1L); +.fi +Just setting \fICURLOPT_POSTFIELDS(3)\fP to "" or NULL does \fInot\fP stop libcurl +from doing a POST. It just makes it POST without any data to send! +.SH Converting from deprecated form API to MIME API +Four rules have to be respected in building the multi\-part: + +- The easy handle must be created before building the multi\-part. + +- The multi\-part is always created by a call to curl_mime_init(handle). + +- Each part is created by a call to curl_mime_addpart(multipart). + +- When complete, the multi\-part must be bound to the easy handle using +\fICURLOPT_MIMEPOST(3)\fP instead of \fICURLOPT_HTTPPOST(3)\fP. + +Here are some example of \fIcurl_formadd\fP calls to MIME API sequences: + +.nf + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "id", + CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END); + CURLFORM_CONTENTHEADER, headers, + CURLFORM_END); +.fi + +becomes: +.nf + part = curl_mime_addpart(multipart); + curl_mime_name(part, "id"); + curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); + curl_mime_headers(part, headers, FALSE); +.fi + +Setting the last \fIcurl_mime_headers(3)\fP argument to TRUE would have caused +the headers to be automatically released upon destroyed the multi\-part, thus +saving a clean\-up call to \fIcurl_slist_free_all(3)\fP. + +.nf + curl_formadd(&post, &last, + CURLFORM_PTRNAME, "logotype-image", + CURLFORM_FILECONTENT, "-", + CURLFORM_END); +.fi + +becomes: +.nf + part = curl_mime_addpart(multipart); + curl_mime_name(part, "logotype-image"); + curl_mime_data_cb(part, (curl_off_t) -1, fread, fseek, NULL, stdin); +.fi + +\fIcurl_mime_name(3)\fP always copies the field name. The special filename "\-" is +not supported by \fIcurl_mime_filename(3)\fP: to read an open file, use a callback +source using fread(). The transfer is be chunk\-encoded since the data size is +unknown. + +.nf + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "datafile[]", + CURLFORM_FILE, "file1", + CURLFORM_FILE, "file2", + CURLFORM_END); +.fi + +becomes: +.nf + part = curl_mime_addpart(multipart); + curl_mime_name(part, "datafile[]"); + curl_mime_filedata(part, "file1"); + part = curl_mime_addpart(multipart); + curl_mime_name(part, "datafile[]"); + curl_mime_filedata(part, "file2"); +.fi + +The deprecated multipart/mixed implementation of multiple files field is +translated to two distinct parts with the same name. + +.nf + curl_easy_setopt(handle, CURLOPT_READFUNCTION, myreadfunc); + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "stream", + CURLFORM_STREAM, arg, + CURLFORM_CONTENTLEN, (curl_off_t) datasize, + CURLFORM_FILENAME, "archive.zip", + CURLFORM_CONTENTTYPE, "application/zip", + CURLFORM_END); +.fi + +becomes: +.nf + part = curl_mime_addpart(multipart); + curl_mime_name(part, "stream"); + curl_mime_data_cb(part, (curl_off_t) datasize, + myreadfunc, NULL, NULL, arg); + curl_mime_filename(part, "archive.zip"); + curl_mime_type(part, "application/zip"); +.fi + +\fICURLOPT_READFUNCTION(3)\fP callback is not used: it is replace by directly +setting the part source data from the callback read function. + +.nf + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "memfile", + CURLFORM_BUFFER, "memfile.bin", + CURLFORM_BUFFERPTR, databuffer, + CURLFORM_BUFFERLENGTH, (long) sizeof databuffer, + CURLFORM_END); +.fi + +becomes: +.nf + part = curl_mime_addpart(multipart); + curl_mime_name(part, "memfile"); + curl_mime_data(part, databuffer, (curl_off_t) sizeof databuffer); + curl_mime_filename(part, "memfile.bin"); +.fi + +\fIcurl_mime_data(3)\fP always copies the initial data: data buffer is thus +free for immediate reuse. + +.nf + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "message", + CURLFORM_FILECONTENT, "msg.txt", + CURLFORM_END); +.fi + +becomes: +.nf + part = curl_mime_addpart(multipart); + curl_mime_name(part, "message"); + curl_mime_filedata(part, "msg.txt"); + curl_mime_filename(part, NULL); +.fi + +Use of \fIcurl_mime_filedata(3)\fP sets the remote filename as a side effect: it is +therefore necessary to clear it for \fICURLFORM_FILECONTENT\fP emulation. +.SH Showing Progress +For historical and traditional reasons, libcurl has a built\-in progress meter +that can be switched on and then makes it present a progress meter in your +terminal. + +Switch on the progress meter by, oddly enough, setting +\fICURLOPT_NOPROGRESS(3)\fP to zero. This option is set to 1 by default. + +For most applications however, the built\-in progress meter is useless and what +instead is interesting is the ability to specify a progress callback. The +function pointer you pass to libcurl is then called on irregular intervals +with information about the current transfer. + +Set the progress callback by using \fICURLOPT_PROGRESSFUNCTION(3)\fP. Pass a pointer +to a function that matches this prototype: + +.nf + int progress_callback(void *clientp, + double dltotal, + double dlnow, + double ultotal, + double ulnow); +.fi + +If any of the input arguments is unknown, a 0 is provided. The first argument, +the \(aqclientp\(aq is the pointer you pass to libcurl with +\fICURLOPT_PROGRESSDATA(3)\fP. libcurl does not touch it. +.SH libcurl with C++ +There is basically only one thing to keep in mind when using C++ instead of C +when interfacing libcurl: + +The callbacks CANNOT be non\-static class member functions + +Example C++ code: + +.nf +class AClass { + static size_t write_data(void *ptr, size_t size, size_t nmemb, + void *ourpointer) + { + /* do what you want with the data */ + } + } +.fi +.SH Proxies +What "proxy" means according to Merriam\-Webster: "a person authorized to act +for another" but also "the agency, function, or office of a deputy who acts as +a substitute for another". + +Proxies are exceedingly common these days. Companies often only offer Internet +access to employees through their proxies. Network clients or user\-agents ask +the proxy for documents, the proxy does the actual request and then it returns +them. + +libcurl supports SOCKS and HTTP proxies. When a given URL is wanted, libcurl +asks the proxy for it instead of trying to connect to the actual remote host +identified in the URL. + +If you are using a SOCKS proxy, you may find that libcurl does not quite support +all operations through it. + +For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain +restrictions on what can actually happen. A requested URL that might not be a +HTTP URL is passed to the HTTP proxy to deliver back to libcurl. This happens +transparently, and an application may not need to know. I say "may", because +at times it is important to understand that all operations over an HTTP proxy +use the HTTP protocol. For example, you cannot invoke your own custom FTP +commands or even proper FTP directory listings. +.IP "Proxy Options" +To tell libcurl to use a proxy at a given port number: +.nf + curl_easy_setopt(handle, CURLOPT_PROXY, "proxy-host.com:8080"); +.fi +Some proxies require user authentication before allowing a request, and you +pass that information similar to this: +.nf + curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "user:password"); +.fi +If you want to, you can specify the hostname only in the +\fICURLOPT_PROXY(3)\fP option, and set the port number separately with +\fICURLOPT_PROXYPORT(3)\fP. + +Tell libcurl what kind of proxy it is with \fICURLOPT_PROXYTYPE(3)\fP (if not, +it defaults to assuming an HTTP proxy): +.nf + curl_easy_setopt(handle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4); +.fi +.IP "Environment Variables" +libcurl automatically checks and uses a set of environment variables to know +what proxies to use for certain protocols. The names of the variables are +following an old tradition and are built up as "[protocol]_proxy" (note the +lower casing). Which makes the variable \(aqhttp_proxy\(aq checked for a name of a +proxy to use when the input URL is HTTP. Following the same rule, the variable +named \(aqftp_proxy\(aq is checked for FTP URLs. Again, the proxies are always HTTP +proxies, the different names of the variables simply allows different HTTP +proxies to be used. + +The proxy environment variable contents should be in the format +\&"[protocol://][user:password@]machine[:port]". Where the protocol:// part +specifies which type of proxy it is, and the optional port number specifies on +which port the proxy operates. If not specified, the internal default port +number is used and that is most likely not the one you would like it to be. + +There are two special environment variables. \(aqall_proxy\(aq is what sets proxy +for any URL in case the protocol specific variable was not set, and \(aqno_proxy\(aq +defines a list of hosts that should not use a proxy even though a variable may +say so. If \(aqno_proxy\(aq is a plain asterisk ("*") it matches all hosts. + +To explicitly disable libcurl\(aqs checking for and using the proxy environment +variables, set the proxy name to "" \- an empty string \- with +\fICURLOPT_PROXY(3)\fP. +.IP "SSL and Proxies" +SSL is for secure point\-to\-point connections. This involves strong encryption +and similar things, which effectively makes it impossible for a proxy to +operate as a "man in between" which the proxy\(aqs task is, as previously +discussed. Instead, the only way to have SSL work over an HTTP proxy is to ask +the proxy to tunnel everything through without being able to check or fiddle +with the traffic. + +Opening an SSL connection over an HTTP proxy is therefore a matter of asking the +proxy for a straight connection to the target host on a specified port. This +is made with the HTTP request CONNECT. ("please dear proxy, connect me to that +remote host"). + +Because of the nature of this operation, where the proxy has no idea what kind +of data that is passed in and out through this tunnel, this breaks some of the +few advantages that come from using a proxy, such as caching. Many +organizations prevent this kind of tunneling to other destination port numbers +than 443 (which is the default HTTPS port number). +.IP "Tunneling Through Proxy" +As explained above, tunneling is required for SSL to work and often even +restricted to the operation intended for SSL; HTTPS. + +This is however not the only time proxy\-tunneling might offer benefits to +you or your application. + +As tunneling opens a direct connection from your application to the remote +machine, it suddenly also re\-introduces the ability to do non\-HTTP +operations over an HTTP proxy. You can in fact use things such as FTP +upload or FTP custom commands this way. + +Again, this is often prevented by the administrators of proxies and is +rarely allowed. + +Tell libcurl to use proxy tunneling like this: +.nf + curl_easy_setopt(handle, CURLOPT_HTTPPROXYTUNNEL, 1L); +.fi +In fact, there might even be times when you want to do plain HTTP operations +using a tunnel like this, as it then enables you to operate on the remote +server instead of asking the proxy to do so. libcurl does not stand in the way +for such innovative actions either! +.IP "Proxy Auto-Config" +Netscape first came up with this. It is basically a webpage (usually using a +\&.pac extension) with a JavaScript that when executed by the browser with the +requested URL as input, returns information to the browser on how to connect +to the URL. The returned information might be "DIRECT" (which means no proxy +should be used), "PROXY host:port" (to tell the browser where the proxy for +this particular URL is) or "SOCKS host:port" (to direct the browser to a SOCKS +proxy). + +libcurl has no means to interpret or evaluate JavaScript and thus it does not +support this. If you get yourself in a position where you face this nasty +invention, the following advice have been mentioned and used in the past: + +- Depending on the JavaScript complexity, write up a script that translates it +to another language and execute that. + +- Read the JavaScript code and rewrite the same logic in another language. + +- Implement a JavaScript interpreter; people have successfully used the +Mozilla JavaScript engine in the past. + +- Ask your admins to stop this, for a static proxy setup or similar. +.SH Persistence Is The Way to Happiness +Re\-cycling the same easy handle several times when doing multiple requests is +the way to go. + +After each single \fIcurl_easy_perform(3)\fP operation, libcurl keeps the +connection alive and open. A subsequent request using the same easy handle to +the same host might just be able to use the already open connection! This +reduces network impact a lot. + +Even if the connection is dropped, all connections involving SSL to the same +host again, benefit from libcurl\(aqs session ID cache that drastically reduces +re\-connection time. + +FTP connections that are kept alive save a lot of time, as the command\- +response round\-trips are skipped, and also you do not risk getting blocked +without permission to login again like on many FTP servers only allowing N +persons to be logged in at the same time. + +libcurl caches DNS name resolving results, to make lookups of a previously +looked up name a lot faster. + +Other interesting details that improve performance for subsequent requests +may also be added in the future. + +Each easy handle attempts to keep the last few connections alive for a while +in case they are to be used again. You can set the size of this "cache" with +the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is rarely any +point in changing this value, and if you think of changing this it is often +just a matter of thinking again. + +To force your upcoming request to not use an already existing connection, you +can do that by setting \fICURLOPT_FRESH_CONNECT(3)\fP to 1. In a similar +spirit, you can also forbid the upcoming request to be "lying" around and +possibly get reused after the request by setting +\fICURLOPT_FORBID_REUSE(3)\fP to 1. +.SH HTTP Headers Used by libcurl +When you use libcurl to do HTTP requests, it passes along a series of headers +automatically. It might be good for you to know and understand these. You can +replace or remove them by using the \fICURLOPT_HTTPHEADER(3)\fP option. +.IP Host +This header is required by HTTP 1.1 and even many 1.0 servers and should be +the name of the server we want to talk to. This includes the port number if +anything but default. +.IP Accept +\&"\fI/\fP" +.IP Expect +When doing POST requests, libcurl sets this header to "100\-continue" to ask +the server for an "OK" message before it proceeds with sending the data part +of the post. If the posted data amount is deemed "small", libcurl does not use +this header. +.SH Customizing Operations +There is an ongoing development today where more and more protocols are built +upon HTTP for transport. This has obvious benefits as HTTP is a tested and +reliable protocol that is widely deployed and has excellent proxy\-support. + +When you use one of these protocols, and even when doing other kinds of +programming you may need to change the traditional HTTP (or FTP or...) +manners. You may need to change words, headers or various data. + +libcurl is your friend here too. +.IP CURLOPT_CUSTOMREQUEST +If just changing the actual HTTP request keyword is what you want, like when +GET, HEAD or POST is not good enough for you, \fICURLOPT_CUSTOMREQUEST(3)\fP +is there for you. It is simple to use: + +.nf +curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST"); +.fi + +When using the custom request, you change the request keyword of the actual +request you are performing. Thus, by default you make a GET request but you +can also make a POST operation (as described before) and then replace the POST +keyword if you want to. You are the boss. +.IP "Modify Headers" +HTTP\-like protocols pass a series of headers to the server when doing the +request, and you are free to pass any amount of extra headers that you +think fit. Adding headers is this easy: + +.nf +struct curl_slist *headers=NULL; /* init to NULL is important */ + +headers = curl_slist_append(headers, "Hey-server-hey: how are you?"); +headers = curl_slist_append(headers, "X-silly-content: yes"); + +/* pass our list of custom made headers */ +curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); + +curl_easy_perform(handle); /* transfer http */ + +curl_slist_free_all(headers); /* free the header list */ +.fi + +\&... and if you think some of the internally generated headers, such as Accept: +or Host: do not contain the data you want them to contain, you can replace +them by simply setting them too: + +.nf +headers = curl_slist_append(headers, "Accept: Agent-007"); +headers = curl_slist_append(headers, "Host: munged.host.line"); +.fi +.IP "Delete Headers" +If you replace an existing header with one with no contents, you prevent the +header from being sent. For instance, if you want to completely prevent the +\&"Accept:" header from being sent, you can disable it with code similar to +this: + + headers = curl_slist_append(headers, "Accept:"); + +Both replacing and canceling internal headers should be done with careful +consideration and you should be aware that you may violate the HTTP protocol +when doing so. +.IP "Enforcing chunked transfer-encoding" +By making sure a request uses the custom header "Transfer\-Encoding: chunked" +when doing a non\-GET HTTP operation, libcurl switches over to "chunked" +upload, even though the size of the data to upload might be known. By default, +libcurl usually switches over to chunked upload automatically if the upload +data size is unknown. +.IP "HTTP Version" +All HTTP requests includes the version number to tell the server which version +we support. libcurl speaks HTTP 1.1 by default. Some old servers do not like +getting 1.1\-requests and when dealing with stubborn old things like that, you +can tell libcurl to use 1.0 instead by doing something like this: + + curl_easy_setopt(handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0); +.IP "FTP Custom Commands" +Not all protocols are HTTP\-like, and thus the above may not help you when +you want to make, for example, your FTP transfers to behave differently. + +Sending custom commands to an FTP server means that you need to send the +commands exactly as the FTP server expects them (RFC 959 is a good guide +here), and you can only use commands that work on the control\-connection +alone. All kinds of commands that require data interchange and thus need a +data\-connection must be left to libcurl\(aqs own judgment. Also be aware that +libcurl does its best to change directory to the target directory before doing +any transfer, so if you change directory (with CWD or similar) you might +confuse libcurl and then it might not attempt to transfer the file in the +correct remote directory. + +A little example that deletes a given file before an operation: + +.nf + headers = curl_slist_append(headers, "DELE file-to-remove"); + + /* pass the list of custom commands to the handle */ + curl_easy_setopt(handle, CURLOPT_QUOTE, headers); + + curl_easy_perform(handle); /* transfer ftp data! */ + + curl_slist_free_all(headers); /* free the header list */ +.fi + +If you would instead want this operation (or chain of operations) to happen +_after_ the data transfer took place the option to \fIcurl_easy_setopt(3)\fP +would instead be called \fICURLOPT_POSTQUOTE(3)\fP and used the exact same +way. + +The custom FTP commands are issued to the server in the same order they are +added to the list, and if a command gets an error code returned back from the +server, no more commands are issued and libcurl bails out with an error code +(CURLE_QUOTE_ERROR). Note that if you use \fICURLOPT_QUOTE(3)\fP to send +commands before a transfer, no transfer actually takes place when a quote +command has failed. + +If you set the \fICURLOPT_HEADER(3)\fP to 1, you tell libcurl to get +information about the target file and output "headers" about it. The headers +are in "HTTP\-style", looking like they do in HTTP. + +The option to enable headers or to run custom FTP commands may be useful to +combine with \fICURLOPT_NOBODY(3)\fP. If this option is set, no actual file +content transfer is performed. +.IP "FTP Custom CURLOPT_CUSTOMREQUEST" +If you do want to list the contents of an FTP directory using your own defined +FTP command, \fICURLOPT_CUSTOMREQUEST(3)\fP does just that. "NLST" is the default +one for listing directories but you are free to pass in your idea of a good +alternative. +.SH Cookies Without Chocolate Chips +In the HTTP sense, a cookie is a name with an associated value. A server sends +the name and value to the client, and expects it to get sent back on every +subsequent request to the server that matches the particular conditions set. +The conditions include that the domain name and path match and that the cookie +has not become too old. + +In real\-world cases, servers send new cookies to replace existing ones to +update them. Server use cookies to "track" users and to keep "sessions". + +Cookies are sent from server to clients with the header Set\-Cookie: and +they are sent from clients to servers with the Cookie: header. + +To just send whatever cookie you want to a server, you can use +\fICURLOPT_COOKIE(3)\fP to set a cookie string like this: + +.nf + curl_easy_setopt(handle, CURLOPT_COOKIE, "name1=var1; name2=var2;"); +.fi + +In many cases, that is not enough. You might want to dynamically save whatever +cookies the remote server passes to you, and make sure those cookies are then +used accordingly on later requests. + +One way to do this, is to save all headers you receive in a plain file and +when you make a request, you tell libcurl to read the previous headers to +figure out which cookies to use. Set the header file to read cookies from with +\fICURLOPT_COOKIEFILE(3)\fP. + +The \fICURLOPT_COOKIEFILE(3)\fP option also automatically enables the cookie +parser in libcurl. Until the cookie parser is enabled, libcurl does not parse +or understand incoming cookies and they are just be ignored. However, when the +parser is enabled the cookies are understood and the cookies are kept in +memory and used properly in subsequent requests when the same handle is +used. Many times this is enough, and you may not have to save the cookies to +disk at all. Note that the file you specify to \fICURLOPT_COOKIEFILE(3)\fP +does not have to exist to enable the parser, so a common way to just enable +the parser and not read any cookies is to use the name of a file you know does +not exist. + +If you would rather use existing cookies that you have previously received +with your Netscape or Mozilla browsers, you can make libcurl use that cookie +file as input. The \fICURLOPT_COOKIEFILE(3)\fP is used for that too, as +libcurl automatically finds out what kind of file it is and acts accordingly. + +Perhaps the most advanced cookie operation libcurl offers, is saving the +entire internal cookie state back into a Netscape/Mozilla formatted cookie +file. We call that the cookie\-jar. When you set a filename with +\fICURLOPT_COOKIEJAR(3)\fP, that filename is created and all received cookies get +stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enables cookies to get +passed on properly between multiple handles without any information getting +lost. +.SH FTP Peculiarities We Need +FTP transfers use a second TCP/IP connection for the data transfer. This is +usually a fact you can forget and ignore but at times this detail comes back +to haunt you. libcurl offers several different ways to customize how the +second connection is being made. + +libcurl can either connect to the server a second time or tell the server to +connect back to it. The first option is the default and it is also what works +best for all the people behind firewalls, NATs or IP\-masquerading setups. +libcurl then tells the server to open up a new port and wait for a second +connection. This is by default attempted with EPSV first, and if that does not +work it tries PASV instead. (EPSV is an extension to the original FTP spec +and does not exist nor work on all FTP servers.) + +You can prevent libcurl from first trying the EPSV command by setting +\fICURLOPT_FTP_USE_EPSV(3)\fP to zero. + +In some cases, you want to have the server connect back to you for the second +connection. This might be when the server is perhaps behind a firewall or +something and only allows connections on a single port. libcurl then informs +the remote server which IP address and port number to connect to. This is made +with the \fICURLOPT_FTPPORT(3)\fP option. If you set it to "\-", libcurl uses your +system\(aqs "default IP address". If you want to use a particular IP, you can set +the full IP address, a hostname to resolve to an IP address or even a local +network interface name that libcurl gets the IP address from. + +When doing the "PORT" approach, libcurl attempts to use the EPRT and the LPRT +before trying PORT, as they work with more protocols. You can disable this +behavior by setting \fICURLOPT_FTP_USE_EPRT(3)\fP to zero. +.SH MIME API revisited for SMTP and IMAP +In addition to support HTTP multi\-part form fields, the MIME API can be used +to build structured email messages and send them via SMTP or append such +messages to IMAP directories. + +A structured email message may contain several parts: some are displayed +inline by the MUA, some are attachments. Parts can also be structured as +multi\-part, for example to include another email message or to offer several +text formats alternatives. This can be nested to any level. + +To build such a message, you prepare the nth\-level multi\-part and then include +it as a source to the parent multi\-part using function +\fIcurl_mime_subparts(3)\fP. Once it has been +bound to its parent multi\-part, a nth\-level multi\-part belongs to it and +should not be freed explicitly. + +Email messages data is not supposed to be non\-ASCII and line length is +limited: fortunately, some transfer encodings are defined by the standards to +support the transmission of such incompatible data. Function +\fIcurl_mime_encoder(3)\fP tells a part that its source data must be encoded +before being sent. It also generates the corresponding header for that part. +If the part data you want to send is already encoded in such a scheme, do not +use this function (this would over\-encode it), but explicitly set the +corresponding part header. + +Upon sending such a message, libcurl prepends it with the header list +set with \fICURLOPT_HTTPHEADER(3)\fP, as zero level mime part headers. + +Here is an example building an email message with an inline plain/html text +alternative and a file attachment encoded in base64: + +.nf + curl_mime *message = curl_mime_init(handle); + + /* The inline part is an alternative proposing the html and the text + versions of the email. */ + curl_mime *alt = curl_mime_init(handle); + + /* HTML message. */ + curl_mimepart *part = curl_mime_addpart(alt); + curl_mime_data(part, "

This is HTML

", + CURL_ZERO_TERMINATED); + curl_mime_type(part, "text/html"); + + /* Text message. */ + part = curl_mime_addpart(alt); + curl_mime_data(part, "This is plain text message", + CURL_ZERO_TERMINATED); + + /* Create the inline part. */ + part = curl_mime_addpart(message); + curl_mime_subparts(part, alt); + curl_mime_type(part, "multipart/alternative"); + struct curl_slist *headers = curl_slist_append(NULL, + "Content-Disposition: inline"); + curl_mime_headers(part, headers, TRUE); + + /* Add the attachment. */ + part = curl_mime_addpart(message); + curl_mime_filedata(part, "manual.pdf"); + curl_mime_encoder(part, "base64"); + + /* Build the mail headers. */ + headers = curl_slist_append(NULL, "From: me@example.com"); + headers = curl_slist_append(headers, "To: you@example.com"); + + /* Set these into the easy handle. */ + curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); + curl_easy_setopt(handle, CURLOPT_MIMEPOST, mime); +.fi + +It should be noted that appending a message to an IMAP directory requires +the message size to be known prior upload. It is therefore not possible to +include parts with unknown data size in this context. +.SH Headers Equal Fun +Some protocols provide "headers", meta\-data separated from the normal +data. These headers are by default not included in the normal data stream, but +you can make them appear in the data stream by setting \fICURLOPT_HEADER(3)\fP +to 1. + +What might be even more useful, is libcurl\(aqs ability to separate the headers +from the data and thus make the callbacks differ. You can for example set a +different pointer to pass to the ordinary write callback by setting +\fICURLOPT_HEADERDATA(3)\fP. + +Or, you can set an entirely separate function to receive the headers, by using +\fICURLOPT_HEADERFUNCTION(3)\fP. + +The headers are passed to the callback function one by one, and you can +depend on that fact. It makes it easier for you to add custom header parsers +etc. + +\&"Headers" for FTP transfers equal all the FTP server responses. They are not +actually true headers, but in this case we pretend they are! ;\-) +.SH Post Transfer Information +See \fIcurl_easy_getinfo(3)\fP. +.SH The multi Interface +The easy interface as described in detail in this document is a synchronous +interface that transfers one file at a time and does not return until it is +done. + +The multi interface, on the other hand, allows your program to transfer +multiple files in both directions at the same time, without forcing you to use +multiple threads. The name might make it seem that the multi interface is for +multi\-threaded programs, but the truth is almost the reverse. The multi +interface allows a single\-threaded application to perform the same kinds of +multiple, simultaneous transfers that multi\-threaded programs can perform. It +allows many of the benefits of multi\-threaded transfers without the complexity +of managing and synchronizing many threads. + +To complicate matters somewhat more, there are even two versions of the multi +interface. The event based one, also called multi_socket and the "normal one" +designed for using with select(). See the libcurl\-multi.3 man page for details +on the multi_socket event based API, this description here is for the select() +oriented one. + +To use this interface, you are better off if you first understand the basics +of how to use the easy interface. The multi interface is simply a way to make +multiple transfers at the same time by adding up multiple easy handles into +a "multi stack". + +You create the easy handles you want, one for each concurrent transfer, and +you set all the options just like you learned above, and then you create a +multi handle with \fIcurl_multi_init(3)\fP and add all those easy handles to +that multi handle with \fIcurl_multi_add_handle(3)\fP. + +When you have added the handles you have for the moment (you can still add new +ones at any time), you start the transfers by calling +\fIcurl_multi_perform(3)\fP. + +\fIcurl_multi_perform(3)\fP is asynchronous. It only performs what can be done +now and then return control to your program. It is designed to never +block. You need to keep calling the function until all transfers are +completed. + +The best usage of this interface is when you do a select() on all possible +file descriptors or sockets to know when to call libcurl again. This also +makes it easy for you to wait and respond to actions on your own application\(aqs +sockets/handles. You figure out what to select() for by using +\fIcurl_multi_fdset(3)\fP, that fills in a set of \fIfd_set\fP variables for +you with the particular file descriptors libcurl uses for the moment. + +When you then call select(), it returns when one of the file handles signal +action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do +what it wants to do. Take note that libcurl does also feature some time\-out +code so we advise you to never use long timeouts on select() before you call +\fIcurl_multi_perform(3)\fP again. \fIcurl_multi_timeout(3)\fP is provided to +help you get a suitable timeout period. + +Another precaution you should use: always call \fIcurl_multi_fdset(3)\fP +immediately before the select() call since the current set of file descriptors +may change in any curl function invoke. + +If you want to stop the transfer of one of the easy handles in the stack, you +can use \fIcurl_multi_remove_handle(3)\fP to remove individual easy +handles. Remember that easy handles should be \fIcurl_easy_cleanup(3)\fPed. + +When a transfer within the multi stack has finished, the counter of running +transfers (as filled in by \fIcurl_multi_perform(3)\fP) decreases. When the +number reaches zero, all transfers are done. + +\fIcurl_multi_info_read(3)\fP can be used to get information about completed +transfers. It then returns the CURLcode for each easy transfer, to allow you +to figure out success on each individual transfer. +.SH SSL, Certificates and Other Tricks + [ seeding, passwords, keys, certificates, ENGINE, ca certs ] +.SH Sharing Data Between Easy Handles +You can share some data between easy handles when the easy interface is used, +and some data is share automatically when you use the multi interface. + +When you add easy handles to a multi handle, these easy handles automatically +share a lot of the data that otherwise would be kept on a per\-easy handle +basis when the easy interface is used. + +The DNS cache is shared between handles within a multi handle, making +subsequent name resolving faster, and the connection pool that is kept to +better allow persistent connections and connection reuse is also shared. If +you are using the easy interface, you can still share these between specific +easy handles by using the share interface, see \fIlibcurl\-share(3)\fP. + +Some things are never shared automatically, not within multi handles, like for +example cookies so the only way to share that is with the share interface. +.SH Footnotes +.IP [1] +libcurl 7.10.3 and later have the ability to switch over to chunked +Transfer\-Encoding in cases where HTTP uploads are done with data of an unknown +size. +.IP [2] +This happens on Windows machines when libcurl is built and used as a +DLL. However, you can still do this on Windows if you link with a static +library. +.IP [3] +The curl\-config tool is generated at build\-time (on Unix\-like systems) and +should be installed with the \(aqmake install\(aq or similar instruction that +installs the library, header files, man pages etc. +.IP [4] +This behavior was different in versions before 7.17.0, where strings had to +remain valid past the end of the \fIcurl_easy_setopt(3)\fP call. +.SH SEE ALSO +.BR libcurl-easy (3), +.BR libcurl-errors (3), +.BR libcurl-multi (3), +.BR libcurl-url (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-url.3 b/3rdparty/curl/share/man/man3/libcurl-url.3 new file mode 100644 index 0000000..b5ac671 --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-url.3 @@ -0,0 +1,129 @@ +.\" generated by cd2nroff 0.1 from libcurl-url.md +.TH libcurl-url 3 "2024-10-11" libcurl +.SH NAME +libcurl\-url \- URL interface overview +.SH DESCRIPTION +The URL interface provides functions for parsing and generating URLs. +.SH INCLUDE +You still only include in your code. +.SH CREATE +Create a handle that holds URL info and resources with \fIcurl_url(3)\fP: +.nf + CURLU *h = curl_url(); +.fi +.SH CLEANUP +When done with it, clean it up with \fIcurl_url_cleanup(3)\fP +.nf + curl_url_cleanup(h); +.fi +.SH DUPLICATE +When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP: +.nf + CURLU *nh = curl_url_dup(h); +.fi +.SH PARSING +By setting a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed +and stored in the handle. If the URL is not syntactically correct it returns +an error instead. +.nf + rc = curl_url_set(h, CURLUPART_URL, + "https://example.com:449/foo/bar?name=moo", 0); +.fi + +The zero in the fourth argument is a bitmask for changing specific features. + +If successful, this stores the URL in its individual parts within the handle. +.SH REDIRECT +When a handle already contains info about a URL, setting a relative URL makes +it "redirect" to that. +.nf + rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0); +.fi +.SH GET URL +The \fBCURLU\fP handle represents a URL and you can easily extract that with +\fIcurl_url_get(3)\fP: +.nf + char *url; + rc = curl_url_get(h, CURLUPART_URL, &url, 0); + curl_free(url); +.fi +The zero in the fourth argument is a bitmask for changing specific features. +.SH GET PARTS +When a URL has been parsed or parts have been set, you can extract those +pieces from the handle at any time. + +.nf + rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0); + rc = curl_url_get(h, CURLUPART_HOST, &host, 0); + rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0); + rc = curl_url_get(h, CURLUPART_PATH, &path, 0); + rc = curl_url_get(h, CURLUPART_PORT, &port, 0); + rc = curl_url_get(h, CURLUPART_QUERY, &query, 0); + rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0); + rc = curl_url_get(h, CURLUPART_USER, &user, 0); + rc = curl_url_get(h, CURLUPART_ZONEID, &zoneid, 0); +.fi + +Extracted parts are not URL decoded unless the user also asks for it with the +\fICURLU_URLDECODE\fP flag set in the fourth bitmask argument. + +Remember to free the returned string with \fIcurl_free(3)\fP when you are done +with it! +.SH SET PARTS +A user set individual URL parts, either after having parsed a full URL or +instead of parsing such. + +.nf + rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0); + rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0); + rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0); + rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0); + rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0); + rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0); + rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0); + rc = curl_url_set(urlp, CURLUPART_USER, "john", 0); + rc = curl_url_set(urlp, CURLUPART_ZONEID, "eth0", 0); +.fi + +Set parts are not URL encoded unless the user asks for it with the +\fICURLU_URLENCODE\fP flag. +.SH CURLU_APPENDQUERY +An application can append a string to the right end of the query part with the +\fICURLU_APPENDQUERY\fP flag to \fIcurl_url_set(3)\fP. + +Imagine a handle that holds the URL "https://example.com/?shoes=2". An +application can then add the string "hat=1" to the query part like this: + +.nf + rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY); +.fi + +It notices the lack of an ampersand (&) separator and injects one, and the +handle\(aqs full URL then equals "https://example.com/?shoes=2&hat=1". + +The appended string can of course also get URL encoded on add, and if asked to +URL encode, the encoding process skips the \(aq=\(aq character. For example, append +\&"candy=N&N" to what we already have, and URL encode it to deal with the +ampersand in the data: + +.nf + rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N", + CURLU_APPENDQUERY | CURLU_URLENCODE); +.fi + +Now the URL looks like + +.nf + https://example.com/?shoes=2&hat=1&candy=N%26N +.fi +.SH NOTES +A URL with a literal IPv6 address can be parsed even when IPv6 support is not +enabled. +.SH SEE ALSO +.BR CURLOPT_URL (3), +.BR curl_url (3), +.BR curl_url_cleanup (3), +.BR curl_url_dup (3), +.BR curl_url_get (3), +.BR curl_url_set (3), +.BR curl_url_strerror (3) diff --git a/3rdparty/curl/share/man/man3/libcurl-ws.3 b/3rdparty/curl/share/man/man3/libcurl-ws.3 new file mode 100644 index 0000000..6c5c8a2 --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl-ws.3 @@ -0,0 +1,96 @@ +.\" generated by cd2nroff 0.1 from libcurl-ws.md +.TH libcurl-ws 3 "2024-10-11" libcurl +.SH NAME +libcurl\-ws \- WebSocket interface overview +.SH DESCRIPTION +The WebSocket interface provides functions for receiving and sending WebSocket +data. +.SH INCLUDE +You still only include in your code. +.SH SETUP +WebSocket is also often known as \fIWebSockets\fP, in plural. It is done by +upgrading a regular HTTP(S) GET request to a WebSocket connection. + +WebSocket is a TCP\-like message\-based communication protocol done over HTTP, +specified in RFC 6455. + +To initiate a WebSocket session with libcurl, setup an easy handle to use a +URL with a "WS://" or "WSS://" scheme. "WS" is for cleartext communication +over HTTP and "WSS" is for doing WebSocket securely over HTTPS. + +A WebSocket request is done as an HTTP/1 GET request with an "Upgrade +WebSocket" request header field. When the upgrade is accepted by the server, +it responds with a 101 Switching and then the client can speak WebSocket with +the server. The communication can happen in both directions at the same time. +.SH MESSAGES +WebSocket communication is message based. That means that both ends send and +receive entire messages, not streams like TCP. A WebSocket message is sent +over the wire in one or more frames. Each frame in a message can have a size +up to 2^63 bytes. + +libcurl delivers WebSocket data as frame fragments. It might send a whole +frame, but it might also deliver them in pieces depending on size and network +patterns. It makes sure to provide the API user about the exact specifics +about the fragment: type, offset, size and how much data there is pending to +arrive for the same frame. + +A message has an unknown size until the last frame header for the message has +been received since only frames have set sizes. +.SH Raw mode +libcurl can be told to speak WebSocket in "raw mode" by setting the +\fBCURLWS_RAW_MODE\fP bit to the \fICURLOPT_WS_OPTIONS(3)\fP option. + +Raw WebSocket means that libcurl passes on the data from the network without +parsing it leaving that entirely to the application. This mode assumes that +the user of this knows WebSocket and can parse and figure out the data all by +itself. + +This mode is intended for applications that already have a WebSocket +parser/engine that want to switch over to use libcurl for enabling WebSocket, +and keep parts of the existing software architecture. +.SH PING +WebSocket is designed to allow long\-lived sessions and in order to keep the +connections alive, both ends can send PING messages for the other end to +respond with a PONG. + +libcurl automatically responds to server PING messages with a PONG. It does +not send any PING messages automatically. +.SH MODELS +Because of the many different ways WebSocket can be used, which is much more +flexible than limited to plain downloads or uploads, libcurl offers two +different API models to use it: + +1. Using a write callback with \fICURLOPT_WRITEFUNCTION(3)\fP much like other +downloads for when the traffic is download oriented. + +2. Using \fICURLOPT_CONNECT_ONLY(3)\fP and use the WebSocket recv/send +functions. +.SH Callback model +When a write callback is set and a WebSocket transfer is performed, the +callback is called to deliver all WebSocket data that arrives. + +The callback can then call \fIcurl_ws_meta(3)\fP to learn about the details of +the incoming data fragment. +.SH CONNECT_ONLY model +By setting \fICURLOPT_CONNECT_ONLY(3)\fP to \fB2L\fP, the transfer only +establishes and setups the WebSocket communication and then returns control +back to the application. + +Once such a setup has been successfully performed, the application can proceed +and use \fIcurl_ws_recv(3)\fP and \fIcurl_ws_send(3)\fP freely to exchange +WebSocket messages with the server. +.SH EXPERIMENTAL +The WebSocket API was introduced as experimental in 7.86.0 and is still +experimental today. + +It is only built\-in if explicitly opted in at build time. We discourage use of +the WebSocket API in production because of its experimental state. We might +change API, ABI and behavior before this "goes live". +.SH SEE ALSO +.BR CURLOPT_CONNECT_ONLY (3), +.BR CURLOPT_WRITEFUNCTION (3), +.BR CURLOPT_WS_OPTIONS (3), +.BR curl_easy_init (3), +.BR curl_ws_meta (3), +.BR curl_ws_recv (3), +.BR curl_ws_send (3) diff --git a/3rdparty/curl/share/man/man3/libcurl.3 b/3rdparty/curl/share/man/man3/libcurl.3 new file mode 100644 index 0000000..e005174 --- /dev/null +++ b/3rdparty/curl/share/man/man3/libcurl.3 @@ -0,0 +1,206 @@ +.\" generated by cd2nroff 0.1 from libcurl.md +.TH libcurl 3 "2024-10-11" libcurl +.SH NAME +libcurl \- client\-side URL transfers +.SH DESCRIPTION +This is a short overview on how to use libcurl in your C programs. There are +specific man pages for each function mentioned in here. See +\fIlibcurl\-easy(3)\fP, \fIlibcurl\-multi(3)\fP, \fIlibcurl\-share(3)\fP, +\fIlibcurl\-url(3)\fP, \fIlibcurl\-ws(3)\fP and \fIlibcurl\-tutorial(3)\fP for +in\-depth understanding on how to program with libcurl. + +There are many bindings available that bring libcurl access to your favorite +language. Look elsewhere for documentation on those. +.SH TRANSFERS +To transfer files, you create an "easy handle" using \fIcurl_easy_init(3)\fP +for a single individual transfer (in either direction). You then set your +desired set of options in that handle with \fIcurl_easy_setopt(3)\fP. Options +you set with \fIcurl_easy_setopt(3)\fP stick. They are then used for every +repeated use of this handle until you either change the option, or you reset +them all with \fIcurl_easy_reset(3)\fP. + +To actually transfer data you have the option of using the "easy" interface, +or the "multi" interface. + +The easy interface is a synchronous interface with which you call +\fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is +completed, the function returns and you can continue. More details are found in +the \fIlibcurl\-easy(3)\fP man page. + +The multi interface on the other hand is an asynchronous interface, that you +call and that performs only a little piece of the transfer on each invoke. It +is perfect if you want to do things while the transfer is in progress, or +similar. The multi interface allows you to select() on libcurl action, and +even to easily download multiple files simultaneously using a single +thread. See further details in the \fIlibcurl\-multi(3)\fP man page. +.SH SUPPORT INTERFACES +There is also a series of other helpful functions and interface families to +use, including these: +.IP curl_version_info() +gets detailed libcurl (and other used libraries) version info. See +\fIcurl_version_info(3)\fP +.IP curl_getdate() +converts a date string to time_t. See \fIcurl_getdate(3)\fP +.IP curl_easy_getinfo() +get information about a performed transfer. See \fIcurl_easy_getinfo(3)\fP +.IP curl_mime_addpart() +helps building an HTTP form POST. See \fIcurl_mime_addpart(3)\fP +.IP curl_slist_append() +builds a linked list. See \fIcurl_slist_append(3)\fP +.IP "Sharing data between transfers" +You can have multiple easy handles share certain data, even if they are used +in different threads. This magic is setup using the share interface, as +described in the \fIlibcurl\-share(3)\fP man page. +.IP "URL Parsing" +URL parsing and manipulations. See \fIlibcurl\-url(3)\fP +.IP "WebSocket communication" +See \fIlibcurl\-ws(3)\fP +.SH LINKING WITH LIBCURL +On Unix\-like machines, there is a tool named curl\-config that gets installed +with the rest of the curl stuff when \(aqmake install\(aq is performed. + +curl\-config is added to make it easier for applications to link with libcurl +and developers to learn about libcurl and how to use it. + +Run \(aqcurl\-config \--libs\(aq to get the (additional) linker options you need to +link with the particular version of libcurl you have installed. See the +\fIcurl\-config(1)\fP man page for further details. + +Unix\-like operating system that ship libcurl as part of their distributions +often do not provide the curl\-config tool, but simply install the library and +headers in the common path for this purpose. + +Many Linux and similar systems use pkg\-config to provide build and link +options about libraries and libcurl supports that as well. +.SH LIBCURL SYMBOL NAMES +All public functions in the libcurl interface are prefixed with \(aqcurl_\(aq (with +a lowercase c). You can find other functions in the library source code, but +other prefixes indicate that the functions are private and may change without +further notice in the next release. + +Only use documented functions and functionality! +.SH PORTABILITY +libcurl works +\fBexactly\fP +the same, on any of the platforms it compiles and builds on. +.SH THREADS +libcurl is thread safe but there are a few exceptions. Refer to +\fIlibcurl\-thread(3)\fP for more information. +.SH PERSISTENT CONNECTIONS +Persistent connections means that libcurl can reuse the same connection for +several transfers, if the conditions are right. + +libcurl always attempts to use persistent connections. Whenever you use +\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl +attempts to use an existing connection to do the transfer, and if none exists +it opens a new one that is subject for reuse on a possible following call to +\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. + +To allow libcurl to take full advantage of persistent connections, you should +do as many of your file transfers as possible using the same handle. + +If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all +the possibly open connections held by libcurl are closed and forgotten. + +When you have created a multi handle and are using the multi interface, the +connection pool is instead kept in the multi handle so closing and creating +new easy handles to do transfers do not affect them. Instead all added easy +handles can take advantage of the single shared pool. +.SH GLOBAL CONSTANTS +There are a variety of constants that libcurl uses, mainly through its +internal use of other libraries, which are too complicated for the +library loader to set up. Therefore, a program must call a library +function after the program is loaded and running to finish setting up +the library code. For example, when libcurl is built for SSL +capability via the GNU TLS library, there is an elaborate tree inside +that library that describes the SSL protocol. + +\fIcurl_global_init(3)\fP is the function that you must call. This may +allocate resources (e.g. the memory for the GNU TLS tree mentioned above), so +the companion function \fIcurl_global_cleanup(3)\fP releases them. + +If libcurl was compiled with support for multiple SSL backends, the function +\fIcurl_global_sslset(3)\fP can be called before \fIcurl_global_init(3)\fP +to select the active SSL backend. + +The global constant functions are thread\-safe since libcurl 7.84.0 if +\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set +(most platforms). Read \fIlibcurl\-thread(3)\fP for thread safety guidelines. + +If the global constant functions are \fInot thread safe\fP, then you must +not call them when any other thread in the program is running. It +is not good enough that no other thread is using libcurl at the time, +because these functions internally call similar functions of other +libraries, and those functions are similarly thread\-unsafe. You cannot +generally know what these libraries are, or whether other threads are +using them. + +If the global constant functions are \fInot thread safe\fP, then the basic rule +for constructing a program that uses libcurl is this: Call +\fIcurl_global_init(3)\fP, with a \fICURL_GLOBAL_ALL\fP argument, immediately +after the program starts, while it is still only one thread and before it uses +libcurl at all. Call \fIcurl_global_cleanup(3)\fP immediately before the +program exits, when the program is again only one thread and after its last +use of libcurl. + +It is not actually required that the functions be called at the beginning +and end of the program \-- that is just usually the easiest way to do it. + +You can call both of these multiple times, as long as all calls meet +these requirements and the number of calls to each is the same. + +The global constant situation merits special consideration when the code you +are writing to use libcurl is not the main program, but rather a modular piece +of a program, e.g. another library. As a module, your code does not know about +other parts of the program \-- it does not know whether they use libcurl or +not. Its code does not necessarily run at the start and end of the whole +program. + +A module like this must have global constant functions of its own, just like +\fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus +has control at the beginning and end of the program and has a place to call +the libcurl functions. If multiple modules in the program use libcurl, they +all separately call the libcurl functions, and that is OK because only the +first \fIcurl_global_init(3)\fP and the last \fIcurl_global_cleanup(3)\fP in a +program change anything. (libcurl uses a reference count in static memory). + +In a C++ module, it is common to deal with the global constant situation by +defining a special class that represents the global constant environment of +the module. A program always has exactly one object of the class, in static +storage. That way, the program automatically calls the constructor of the +object as the program starts up and the destructor as it terminates. As the +author of this libcurl\-using module, you can make the constructor call +\fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP +and satisfy libcurl\(aqs requirements without your user having to think about it. +(Caveat: If you are initializing libcurl from a Windows DLL you should not +initialize it from \fIDllMain\fP or a static initializer because Windows holds +the loader lock during that time and it could cause a deadlock.) + +\fIcurl_global_init(3)\fP has an argument that tells what particular parts of +the global constant environment to set up. In order to successfully use any +value except \fICURL_GLOBAL_ALL\fP (which says to set up the whole thing), you +must have specific knowledge of internal workings of libcurl and all other +parts of the program of which it is part. + +A special part of the global constant environment is the identity of the +memory allocator. \fIcurl_global_init(3)\fP selects the system default memory +allocator, but you can use \fIcurl_global_init_mem(3)\fP to supply one of your +own. However, there is no way to use \fIcurl_global_init_mem(3)\fP in a +modular program \-- all modules in the program that might use libcurl would +have to agree on one allocator. + +There is a failsafe in libcurl that makes it usable in simple situations +without you having to worry about the global constant environment at all: +\fIcurl_easy_init(3)\fP sets up the environment itself if it has not been done +yet. The resources it acquires to do so get released by the operating system +automatically when the program exits. + +This failsafe feature exists mainly for backward compatibility because there +was a time when the global functions did not exist. Because it is sufficient +only in the simplest of programs, it is not recommended for any program to +rely on it. +.SH SEE ALSO +.BR libcurl-easy (3), +.BR libcurl-multi (3), +.BR libcurl-security (3), +.BR libcurl-thread (3) diff --git a/3rdparty/libgit2/bin/git2.exe b/3rdparty/libgit2/bin/git2.exe new file mode 100644 index 0000000..a2b22f3 Binary files /dev/null and b/3rdparty/libgit2/bin/git2.exe differ diff --git a/3rdparty/libgit2/include/git2.h b/3rdparty/libgit2/include/git2.h index 3457e5f..3ebe5df 100644 --- a/3rdparty/libgit2/include/git2.h +++ b/3rdparty/libgit2/include/git2.h @@ -1,74 +1,74 @@ -/* - * 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_git_h__ -#define INCLUDE_git_git_h__ - -#include "git2/annotated_commit.h" -#include "git2/apply.h" -#include "git2/attr.h" -#include "git2/blob.h" -#include "git2/blame.h" -#include "git2/branch.h" -#include "git2/buffer.h" -#include "git2/cert.h" -#include "git2/checkout.h" -#include "git2/cherrypick.h" -#include "git2/clone.h" -#include "git2/commit.h" -#include "git2/common.h" -#include "git2/config.h" -#include "git2/credential.h" -#include "git2/deprecated.h" -#include "git2/describe.h" -#include "git2/diff.h" -#include "git2/email.h" -#include "git2/errors.h" -#include "git2/experimental.h" -#include "git2/filter.h" -#include "git2/global.h" -#include "git2/graph.h" -#include "git2/ignore.h" -#include "git2/index.h" -#include "git2/indexer.h" -#include "git2/mailmap.h" -#include "git2/merge.h" -#include "git2/message.h" -#include "git2/net.h" -#include "git2/notes.h" -#include "git2/object.h" -#include "git2/odb.h" -#include "git2/odb_backend.h" -#include "git2/oid.h" -#include "git2/pack.h" -#include "git2/patch.h" -#include "git2/pathspec.h" -#include "git2/proxy.h" -#include "git2/rebase.h" -#include "git2/refdb.h" -#include "git2/reflog.h" -#include "git2/refs.h" -#include "git2/refspec.h" -#include "git2/remote.h" -#include "git2/repository.h" -#include "git2/reset.h" -#include "git2/revert.h" -#include "git2/revparse.h" -#include "git2/revwalk.h" -#include "git2/signature.h" -#include "git2/stash.h" -#include "git2/status.h" -#include "git2/submodule.h" -#include "git2/tag.h" -#include "git2/transport.h" -#include "git2/transaction.h" -#include "git2/tree.h" -#include "git2/types.h" -#include "git2/version.h" -#include "git2/worktree.h" - -#endif +/* + * 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_git_h__ +#define INCLUDE_git_git_h__ + +#include "git2/annotated_commit.h" +#include "git2/apply.h" +#include "git2/attr.h" +#include "git2/blob.h" +#include "git2/blame.h" +#include "git2/branch.h" +#include "git2/buffer.h" +#include "git2/cert.h" +#include "git2/checkout.h" +#include "git2/cherrypick.h" +#include "git2/clone.h" +#include "git2/commit.h" +#include "git2/common.h" +#include "git2/config.h" +#include "git2/credential.h" +#include "git2/deprecated.h" +#include "git2/describe.h" +#include "git2/diff.h" +#include "git2/email.h" +#include "git2/errors.h" +#include "git2/experimental.h" +#include "git2/filter.h" +#include "git2/global.h" +#include "git2/graph.h" +#include "git2/ignore.h" +#include "git2/index.h" +#include "git2/indexer.h" +#include "git2/mailmap.h" +#include "git2/merge.h" +#include "git2/message.h" +#include "git2/net.h" +#include "git2/notes.h" +#include "git2/object.h" +#include "git2/odb.h" +#include "git2/odb_backend.h" +#include "git2/oid.h" +#include "git2/pack.h" +#include "git2/patch.h" +#include "git2/pathspec.h" +#include "git2/proxy.h" +#include "git2/rebase.h" +#include "git2/refdb.h" +#include "git2/reflog.h" +#include "git2/refs.h" +#include "git2/refspec.h" +#include "git2/remote.h" +#include "git2/repository.h" +#include "git2/reset.h" +#include "git2/revert.h" +#include "git2/revparse.h" +#include "git2/revwalk.h" +#include "git2/signature.h" +#include "git2/stash.h" +#include "git2/status.h" +#include "git2/submodule.h" +#include "git2/tag.h" +#include "git2/transport.h" +#include "git2/transaction.h" +#include "git2/tree.h" +#include "git2/types.h" +#include "git2/version.h" +#include "git2/worktree.h" + +#endif diff --git a/3rdparty/libgit2/include/git2/annotated_commit.h b/3rdparty/libgit2/include/git2/annotated_commit.h index 3b7103f..3b87d39 100644 --- a/3rdparty/libgit2/include/git2/annotated_commit.h +++ b/3rdparty/libgit2/include/git2/annotated_commit.h @@ -1,125 +1,125 @@ -/* - * 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_annotated_commit_h__ -#define INCLUDE_git_annotated_commit_h__ - -#include "common.h" -#include "repository.h" -#include "types.h" - -/** - * @file git2/annotated_commit.h - * @brief Git annotated commit routines - * @defgroup git_annotated_commit Git annotated commit routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Creates a `git_annotated_commit` from the given reference. - * The resulting git_annotated_commit must be freed with - * `git_annotated_commit_free`. - * - * @param out pointer to store the git_annotated_commit result in - * @param repo repository that contains the given reference - * @param ref reference to use to lookup the git_annotated_commit - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_annotated_commit_from_ref( - git_annotated_commit **out, - git_repository *repo, - const git_reference *ref); - -/** - * Creates a `git_annotated_commit` from the given fetch head data. - * The resulting git_annotated_commit must be freed with - * `git_annotated_commit_free`. - * - * @param out pointer to store the git_annotated_commit result in - * @param repo repository that contains the given commit - * @param branch_name name of the (remote) branch - * @param remote_url url of the remote - * @param id the commit object id of the remote branch - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_annotated_commit_from_fetchhead( - git_annotated_commit **out, - git_repository *repo, - const char *branch_name, - const char *remote_url, - const git_oid *id); - -/** - * Creates a `git_annotated_commit` from the given commit id. - * The resulting git_annotated_commit must be freed with - * `git_annotated_commit_free`. - * - * An annotated commit contains information about how it was - * looked up, which may be useful for functions like merge or - * rebase to provide context to the operation. For example, - * conflict files will include the name of the source or target - * branches being merged. It is therefore preferable to use the - * most specific function (eg `git_annotated_commit_from_ref`) - * instead of this one when that data is known. - * - * @param out pointer to store the git_annotated_commit result in - * @param repo repository that contains the given commit - * @param id the commit object id to lookup - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_annotated_commit_lookup( - git_annotated_commit **out, - git_repository *repo, - const git_oid *id); - -/** - * Creates a `git_annotated_commit` from a revision string. - * - * See `man gitrevisions`, or - * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for - * information on the syntax accepted. - * - * @param out pointer to store the git_annotated_commit result in - * @param repo repository that contains the given commit - * @param revspec the extended sha syntax string to use to lookup the commit - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_annotated_commit_from_revspec( - git_annotated_commit **out, - git_repository *repo, - const char *revspec); - -/** - * Gets the commit ID that the given `git_annotated_commit` refers to. - * - * @param commit the given annotated commit - * @return commit id - */ -GIT_EXTERN(const git_oid *) git_annotated_commit_id( - const git_annotated_commit *commit); - -/** - * Get the refname that the given `git_annotated_commit` refers to. - * - * @param commit the given annotated commit - * @return ref name. - */ -GIT_EXTERN(const char *) git_annotated_commit_ref( - const git_annotated_commit *commit); - -/** - * Frees a `git_annotated_commit`. - * - * @param commit annotated commit to free - */ -GIT_EXTERN(void) git_annotated_commit_free( - git_annotated_commit *commit); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_annotated_commit_h__ +#define INCLUDE_git_annotated_commit_h__ + +#include "common.h" +#include "repository.h" +#include "types.h" + +/** + * @file git2/annotated_commit.h + * @brief Git annotated commit routines + * @defgroup git_annotated_commit Git annotated commit routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Creates a `git_annotated_commit` from the given reference. + * The resulting git_annotated_commit must be freed with + * `git_annotated_commit_free`. + * + * @param out pointer to store the git_annotated_commit result in + * @param repo repository that contains the given reference + * @param ref reference to use to lookup the git_annotated_commit + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_annotated_commit_from_ref( + git_annotated_commit **out, + git_repository *repo, + const git_reference *ref); + +/** + * Creates a `git_annotated_commit` from the given fetch head data. + * The resulting git_annotated_commit must be freed with + * `git_annotated_commit_free`. + * + * @param out pointer to store the git_annotated_commit result in + * @param repo repository that contains the given commit + * @param branch_name name of the (remote) branch + * @param remote_url url of the remote + * @param id the commit object id of the remote branch + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_annotated_commit_from_fetchhead( + git_annotated_commit **out, + git_repository *repo, + const char *branch_name, + const char *remote_url, + const git_oid *id); + +/** + * Creates a `git_annotated_commit` from the given commit id. + * The resulting git_annotated_commit must be freed with + * `git_annotated_commit_free`. + * + * An annotated commit contains information about how it was + * looked up, which may be useful for functions like merge or + * rebase to provide context to the operation. For example, + * conflict files will include the name of the source or target + * branches being merged. It is therefore preferable to use the + * most specific function (eg `git_annotated_commit_from_ref`) + * instead of this one when that data is known. + * + * @param out pointer to store the git_annotated_commit result in + * @param repo repository that contains the given commit + * @param id the commit object id to lookup + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_annotated_commit_lookup( + git_annotated_commit **out, + git_repository *repo, + const git_oid *id); + +/** + * Creates a `git_annotated_commit` from a revision string. + * + * See `man gitrevisions`, or + * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for + * information on the syntax accepted. + * + * @param out pointer to store the git_annotated_commit result in + * @param repo repository that contains the given commit + * @param revspec the extended sha syntax string to use to lookup the commit + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_annotated_commit_from_revspec( + git_annotated_commit **out, + git_repository *repo, + const char *revspec); + +/** + * Gets the commit ID that the given `git_annotated_commit` refers to. + * + * @param commit the given annotated commit + * @return commit id + */ +GIT_EXTERN(const git_oid *) git_annotated_commit_id( + const git_annotated_commit *commit); + +/** + * Get the refname that the given `git_annotated_commit` refers to. + * + * @param commit the given annotated commit + * @return ref name. + */ +GIT_EXTERN(const char *) git_annotated_commit_ref( + const git_annotated_commit *commit); + +/** + * Frees a `git_annotated_commit`. + * + * @param commit annotated commit to free + */ +GIT_EXTERN(void) git_annotated_commit_free( + git_annotated_commit *commit); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/apply.h b/3rdparty/libgit2/include/git2/apply.h index db652bd..04648be 100644 --- a/3rdparty/libgit2/include/git2/apply.h +++ b/3rdparty/libgit2/include/git2/apply.h @@ -1,165 +1,165 @@ -/* - * 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_apply_h__ -#define INCLUDE_git_apply_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "diff.h" - -/** - * @file git2/apply.h - * @brief Git patch application routines - * @defgroup git_apply Git patch application routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * When applying a patch, callback that will be made per delta (file). - * - * When the callback: - * - returns < 0, the apply process will be aborted. - * - returns > 0, the delta will not be applied, but the apply process - * continues - * - returns 0, the delta is applied, and the apply process continues. - * - * @param delta The delta to be applied - * @param payload User-specified payload - * @return 0 if the delta is applied, < 0 if the apply process will be aborted - * or > 0 if the delta will not be applied. - */ -typedef int GIT_CALLBACK(git_apply_delta_cb)( - const git_diff_delta *delta, - void *payload); - -/** - * When applying a patch, callback that will be made per hunk. - * - * When the callback: - * - returns < 0, the apply process will be aborted. - * - returns > 0, the hunk will not be applied, but the apply process - * continues - * - returns 0, the hunk is applied, and the apply process continues. - * - * @param hunk The hunk to be applied - * @param payload User-specified payload - * @return 0 if the hunk is applied, < 0 if the apply process will be aborted - * or > 0 if the hunk will not be applied. - */ -typedef int GIT_CALLBACK(git_apply_hunk_cb)( - const git_diff_hunk *hunk, - void *payload); - -/** Flags controlling the behavior of git_apply */ -typedef enum { - /** - * Don't actually make changes, just test that the patch applies. - * This is the equivalent of `git apply --check`. - */ - GIT_APPLY_CHECK = (1 << 0) -} git_apply_flags_t; - -/** - * Apply options structure - * - * Initialize with `GIT_APPLY_OPTIONS_INIT`. Alternatively, you can - * use `git_apply_options_init`. - * - * @see git_apply_to_tree, git_apply - */ -typedef struct { - unsigned int version; /**< The version */ - - /** When applying a patch, callback that will be made per delta (file). */ - git_apply_delta_cb delta_cb; - - /** When applying a patch, callback that will be made per hunk. */ - git_apply_hunk_cb hunk_cb; - - /** Payload passed to both delta_cb & hunk_cb. */ - void *payload; - - /** Bitmask of git_apply_flags_t */ - unsigned int flags; -} git_apply_options; - -#define GIT_APPLY_OPTIONS_VERSION 1 -#define GIT_APPLY_OPTIONS_INIT {GIT_APPLY_OPTIONS_VERSION} - -/** - * Initialize git_apply_options structure - * - * Initialize a `git_apply_options` with default values. Equivalent to creating - * an instance with GIT_APPLY_OPTIONS_INIT. - * - * @param opts The `git_apply_options` struct to initialize. - * @param version The struct version; pass `GIT_APPLY_OPTIONS_VERSION` - * @return 0 on success or -1 on failure. - */ -GIT_EXTERN(int) git_apply_options_init(git_apply_options *opts, unsigned int version); - -/** - * Apply a `git_diff` to a `git_tree`, and return the resulting image - * as an index. - * - * @param out the postimage of the application - * @param repo the repository to apply - * @param preimage the tree to apply the diff to - * @param diff the diff to apply - * @param options the options for the apply (or null for defaults) - * @return 0 or an error code - */ -GIT_EXTERN(int) git_apply_to_tree( - git_index **out, - git_repository *repo, - git_tree *preimage, - git_diff *diff, - const git_apply_options *options); - -/** Possible application locations for git_apply */ -typedef enum { - /** - * Apply the patch to the workdir, leaving the index untouched. - * This is the equivalent of `git apply` with no location argument. - */ - GIT_APPLY_LOCATION_WORKDIR = 0, - - /** - * Apply the patch to the index, leaving the working directory - * untouched. This is the equivalent of `git apply --cached`. - */ - GIT_APPLY_LOCATION_INDEX = 1, - - /** - * Apply the patch to both the working directory and the index. - * This is the equivalent of `git apply --index`. - */ - GIT_APPLY_LOCATION_BOTH = 2 -} git_apply_location_t; - -/** - * Apply a `git_diff` to the given repository, making changes directly - * in the working directory, the index, or both. - * - * @param repo the repository to apply to - * @param diff the diff to apply - * @param location the location to apply (workdir, index or both) - * @param options the options for the apply (or null for defaults) - * @return 0 or an error code - */ -GIT_EXTERN(int) git_apply( - git_repository *repo, - git_diff *diff, - git_apply_location_t location, - const git_apply_options *options); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_apply_h__ +#define INCLUDE_git_apply_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "diff.h" + +/** + * @file git2/apply.h + * @brief Git patch application routines + * @defgroup git_apply Git patch application routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * When applying a patch, callback that will be made per delta (file). + * + * When the callback: + * - returns < 0, the apply process will be aborted. + * - returns > 0, the delta will not be applied, but the apply process + * continues + * - returns 0, the delta is applied, and the apply process continues. + * + * @param delta The delta to be applied + * @param payload User-specified payload + * @return 0 if the delta is applied, < 0 if the apply process will be aborted + * or > 0 if the delta will not be applied. + */ +typedef int GIT_CALLBACK(git_apply_delta_cb)( + const git_diff_delta *delta, + void *payload); + +/** + * When applying a patch, callback that will be made per hunk. + * + * When the callback: + * - returns < 0, the apply process will be aborted. + * - returns > 0, the hunk will not be applied, but the apply process + * continues + * - returns 0, the hunk is applied, and the apply process continues. + * + * @param hunk The hunk to be applied + * @param payload User-specified payload + * @return 0 if the hunk is applied, < 0 if the apply process will be aborted + * or > 0 if the hunk will not be applied. + */ +typedef int GIT_CALLBACK(git_apply_hunk_cb)( + const git_diff_hunk *hunk, + void *payload); + +/** Flags controlling the behavior of git_apply */ +typedef enum { + /** + * Don't actually make changes, just test that the patch applies. + * This is the equivalent of `git apply --check`. + */ + GIT_APPLY_CHECK = (1 << 0) +} git_apply_flags_t; + +/** + * Apply options structure + * + * Initialize with `GIT_APPLY_OPTIONS_INIT`. Alternatively, you can + * use `git_apply_options_init`. + * + * @see git_apply_to_tree, git_apply + */ +typedef struct { + unsigned int version; /**< The version */ + + /** When applying a patch, callback that will be made per delta (file). */ + git_apply_delta_cb delta_cb; + + /** When applying a patch, callback that will be made per hunk. */ + git_apply_hunk_cb hunk_cb; + + /** Payload passed to both delta_cb & hunk_cb. */ + void *payload; + + /** Bitmask of git_apply_flags_t */ + unsigned int flags; +} git_apply_options; + +#define GIT_APPLY_OPTIONS_VERSION 1 +#define GIT_APPLY_OPTIONS_INIT {GIT_APPLY_OPTIONS_VERSION} + +/** + * Initialize git_apply_options structure + * + * Initialize a `git_apply_options` with default values. Equivalent to creating + * an instance with GIT_APPLY_OPTIONS_INIT. + * + * @param opts The `git_apply_options` struct to initialize. + * @param version The struct version; pass `GIT_APPLY_OPTIONS_VERSION` + * @return 0 on success or -1 on failure. + */ +GIT_EXTERN(int) git_apply_options_init(git_apply_options *opts, unsigned int version); + +/** + * Apply a `git_diff` to a `git_tree`, and return the resulting image + * as an index. + * + * @param out the postimage of the application + * @param repo the repository to apply + * @param preimage the tree to apply the diff to + * @param diff the diff to apply + * @param options the options for the apply (or null for defaults) + * @return 0 or an error code + */ +GIT_EXTERN(int) git_apply_to_tree( + git_index **out, + git_repository *repo, + git_tree *preimage, + git_diff *diff, + const git_apply_options *options); + +/** Possible application locations for git_apply */ +typedef enum { + /** + * Apply the patch to the workdir, leaving the index untouched. + * This is the equivalent of `git apply` with no location argument. + */ + GIT_APPLY_LOCATION_WORKDIR = 0, + + /** + * Apply the patch to the index, leaving the working directory + * untouched. This is the equivalent of `git apply --cached`. + */ + GIT_APPLY_LOCATION_INDEX = 1, + + /** + * Apply the patch to both the working directory and the index. + * This is the equivalent of `git apply --index`. + */ + GIT_APPLY_LOCATION_BOTH = 2 +} git_apply_location_t; + +/** + * Apply a `git_diff` to the given repository, making changes directly + * in the working directory, the index, or both. + * + * @param repo the repository to apply to + * @param diff the diff to apply + * @param location the location to apply (workdir, index or both) + * @param options the options for the apply (or null for defaults) + * @return 0 or an error code + */ +GIT_EXTERN(int) git_apply( + git_repository *repo, + git_diff *diff, + git_apply_location_t location, + const git_apply_options *options); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/attr.h b/3rdparty/libgit2/include/git2/attr.h index 69929b3..948a075 100644 --- a/3rdparty/libgit2/include/git2/attr.h +++ b/3rdparty/libgit2/include/git2/attr.h @@ -1,368 +1,368 @@ -/* - * 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_attr_h__ -#define INCLUDE_git_attr_h__ - -#include "common.h" -#include "types.h" - -/** - * @file git2/attr.h - * @brief Git attribute management routines - * @defgroup git_attr Git attribute management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * GIT_ATTR_TRUE checks if an attribute is set on. In core git - * parlance, this the value for "Set" attributes. - * - * For example, if the attribute file contains: - * - * *.c foo - * - * Then for file `xyz.c` looking up attribute "foo" gives a value for - * which `GIT_ATTR_TRUE(value)` is true. - */ -#define GIT_ATTR_IS_TRUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_TRUE) - -/** - * GIT_ATTR_FALSE checks if an attribute is set off. In core git - * parlance, this is the value for attributes that are "Unset" (not to - * be confused with values that a "Unspecified"). - * - * For example, if the attribute file contains: - * - * *.h -foo - * - * Then for file `zyx.h` looking up attribute "foo" gives a value for - * which `GIT_ATTR_FALSE(value)` is true. - */ -#define GIT_ATTR_IS_FALSE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_FALSE) - -/** - * GIT_ATTR_UNSPECIFIED checks if an attribute is unspecified. This - * may be due to the attribute not being mentioned at all or because - * the attribute was explicitly set unspecified via the `!` operator. - * - * For example, if the attribute file contains: - * - * *.c foo - * *.h -foo - * onefile.c !foo - * - * Then for `onefile.c` looking up attribute "foo" yields a value with - * `GIT_ATTR_UNSPECIFIED(value)` of true. Also, looking up "foo" on - * file `onefile.rb` or looking up "bar" on any file will all give - * `GIT_ATTR_UNSPECIFIED(value)` of true. - */ -#define GIT_ATTR_IS_UNSPECIFIED(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_UNSPECIFIED) - -/** - * GIT_ATTR_HAS_VALUE checks if an attribute is set to a value (as - * opposed to TRUE, FALSE or UNSPECIFIED). This would be the case if - * for a file with something like: - * - * *.txt eol=lf - * - * Given this, looking up "eol" for `onefile.txt` will give back the - * string "lf" and `GIT_ATTR_SET_TO_VALUE(attr)` will return true. - */ -#define GIT_ATTR_HAS_VALUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_STRING) - -/** - * Possible states for an attribute - */ -typedef enum { - GIT_ATTR_VALUE_UNSPECIFIED = 0, /**< The attribute has been left unspecified */ - GIT_ATTR_VALUE_TRUE, /**< The attribute has been set */ - GIT_ATTR_VALUE_FALSE, /**< The attribute has been unset */ - GIT_ATTR_VALUE_STRING /**< This attribute has a value */ -} git_attr_value_t; - -/** - * Return the value type for a given attribute. - * - * This can be either `TRUE`, `FALSE`, `UNSPECIFIED` (if the attribute - * was not set at all), or `VALUE`, if the attribute was set to an - * actual string. - * - * If the attribute has a `VALUE` string, it can be accessed normally - * as a NULL-terminated C string. - * - * @param attr The attribute - * @return the value type for the attribute - */ -GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr); - -/** - * Check attribute flags: Reading values from index and working directory. - * - * When checking attributes, it is possible to check attribute files - * in both the working directory (if there is one) and the index (if - * there is one). You can explicitly choose where to check and in - * which order using the following flags. - * - * Core git usually checks the working directory then the index, - * except during a checkout when it checks the index first. It will - * use index only for creating archives or for a bare repo (if an - * index has been specified for the bare repo). - */ -#define GIT_ATTR_CHECK_FILE_THEN_INDEX 0 -#define GIT_ATTR_CHECK_INDEX_THEN_FILE 1 -#define GIT_ATTR_CHECK_INDEX_ONLY 2 - -/** - * Check attribute flags: controlling extended attribute behavior. - * - * Normally, attribute checks include looking in the /etc (or system - * equivalent) directory for a `gitattributes` file. Passing the - * `GIT_ATTR_CHECK_NO_SYSTEM` flag will cause attribute checks to - * ignore that file. - * - * Passing the `GIT_ATTR_CHECK_INCLUDE_HEAD` flag will use attributes - * from a `.gitattributes` file in the repository at the HEAD revision. - * - * Passing the `GIT_ATTR_CHECK_INCLUDE_COMMIT` flag will use attributes - * from a `.gitattributes` file in a specific commit. - */ -#define GIT_ATTR_CHECK_NO_SYSTEM (1 << 2) -#define GIT_ATTR_CHECK_INCLUDE_HEAD (1 << 3) -#define GIT_ATTR_CHECK_INCLUDE_COMMIT (1 << 4) - -/** -* An options structure for querying attributes. -*/ -typedef struct { - unsigned int version; - - /** A combination of GIT_ATTR_CHECK flags */ - unsigned int flags; - -#ifdef GIT_DEPRECATE_HARD - void *reserved; -#else - git_oid *commit_id; -#endif - - /** - * The commit to load attributes from, when - * `GIT_ATTR_CHECK_INCLUDE_COMMIT` is specified. - */ - git_oid attr_commit_id; -} git_attr_options; - -#define GIT_ATTR_OPTIONS_VERSION 1 -#define GIT_ATTR_OPTIONS_INIT {GIT_ATTR_OPTIONS_VERSION} - -/** - * Look up the value of one git attribute for path. - * - * @param value_out Output of the value of the attribute. Use the GIT_ATTR_... - * macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just - * use the string value for attributes set to a value. You - * should NOT modify or free this value. - * @param repo The repository containing the path. - * @param flags A combination of GIT_ATTR_CHECK... flags. - * @param path The path to check for attributes. Relative paths are - * interpreted relative to the repo root. The file does - * not have to exist, but if it does not, then it will be - * treated as a plain file (not a directory). - * @param name The name of the attribute to look up. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_attr_get( - const char **value_out, - git_repository *repo, - uint32_t flags, - const char *path, - const char *name); - -/** - * Look up the value of one git attribute for path with extended options. - * - * @param value_out Output of the value of the attribute. Use the GIT_ATTR_... - * macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just - * use the string value for attributes set to a value. You - * should NOT modify or free this value. - * @param repo The repository containing the path. - * @param opts The `git_attr_options` to use when querying these attributes. - * @param path The path to check for attributes. Relative paths are - * interpreted relative to the repo root. The file does - * not have to exist, but if it does not, then it will be - * treated as a plain file (not a directory). - * @param name The name of the attribute to look up. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_attr_get_ext( - const char **value_out, - git_repository *repo, - git_attr_options *opts, - const char *path, - const char *name); - -/** - * Look up a list of git attributes for path. - * - * Use this if you have a known list of attributes that you want to - * look up in a single call. This is somewhat more efficient than - * calling `git_attr_get()` multiple times. - * - * For example, you might write: - * - * const char *attrs[] = { "crlf", "diff", "foo" }; - * const char **values[3]; - * git_attr_get_many(values, repo, 0, "my/fun/file.c", 3, attrs); - * - * Then you could loop through the 3 values to get the settings for - * the three attributes you asked about. - * - * @param values_out An array of num_attr entries that will have string - * pointers written into it for the values of the attributes. - * You should not modify or free the values that are written - * into this array (although of course, you should free the - * array itself if you allocated it). - * @param repo The repository containing the path. - * @param flags A combination of GIT_ATTR_CHECK... flags. - * @param path The path inside the repo to check attributes. This - * does not have to exist, but if it does not, then - * it will be treated as a plain file (i.e. not a directory). - * @param num_attr The number of attributes being looked up - * @param names An array of num_attr strings containing attribute names. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_attr_get_many( - const char **values_out, - git_repository *repo, - uint32_t flags, - const char *path, - size_t num_attr, - const char **names); - -/** - * Look up a list of git attributes for path with extended options. - * - * @param values_out An array of num_attr entries that will have string - * pointers written into it for the values of the attributes. - * You should not modify or free the values that are written - * into this array (although of course, you should free the - * array itself if you allocated it). - * @param repo The repository containing the path. - * @param opts The `git_attr_options` to use when querying these attributes. - * @param path The path inside the repo to check attributes. This - * does not have to exist, but if it does not, then - * it will be treated as a plain file (i.e. not a directory). - * @param num_attr The number of attributes being looked up - * @param names An array of num_attr strings containing attribute names. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_attr_get_many_ext( - const char **values_out, - git_repository *repo, - git_attr_options *opts, - const char *path, - size_t num_attr, - const char **names); - -/** - * The callback used with git_attr_foreach. - * - * This callback will be invoked only once per attribute name, even if there - * are multiple rules for a given file. The highest priority rule will be - * used. - * - * @see git_attr_foreach. - * - * @param name The attribute name. - * @param value The attribute value. May be NULL if the attribute is explicitly - * set to UNSPECIFIED using the '!' sign. - * @param payload A user-specified pointer. - * @return 0 to continue looping, non-zero to stop. This value will be returned - * from git_attr_foreach. - */ -typedef int GIT_CALLBACK(git_attr_foreach_cb)(const char *name, const char *value, void *payload); - -/** - * Loop over all the git attributes for a path. - * - * @param repo The repository containing the path. - * @param flags A combination of GIT_ATTR_CHECK... flags. - * @param path Path inside the repo to check attributes. This does not have - * to exist, but if it does not, then it will be treated as a - * plain file (i.e. not a directory). - * @param callback Function to invoke on each attribute name and value. - * See git_attr_foreach_cb. - * @param payload Passed on as extra parameter to callback function. - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_attr_foreach( - git_repository *repo, - uint32_t flags, - const char *path, - git_attr_foreach_cb callback, - void *payload); - -/** - * Loop over all the git attributes for a path with extended options. - * - * @param repo The repository containing the path. - * @param opts The `git_attr_options` to use when querying these attributes. - * @param path Path inside the repo to check attributes. This does not have - * to exist, but if it does not, then it will be treated as a - * plain file (i.e. not a directory). - * @param callback Function to invoke on each attribute name and value. - * See git_attr_foreach_cb. - * @param payload Passed on as extra parameter to callback function. - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_attr_foreach_ext( - git_repository *repo, - git_attr_options *opts, - const char *path, - git_attr_foreach_cb callback, - void *payload); - -/** - * Flush the gitattributes cache. - * - * Call this if you have reason to believe that the attributes files on - * disk no longer match the cached contents of memory. This will cause - * the attributes files to be reloaded the next time that an attribute - * access function is called. - * - * @param repo The repository containing the gitattributes cache - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_attr_cache_flush( - git_repository *repo); - -/** - * Add a macro definition. - * - * Macros will automatically be loaded from the top level `.gitattributes` - * file of the repository (plus the built-in "binary" macro). This - * function allows you to add others. For example, to add the default - * macro, you would call: - * - * git_attr_add_macro(repo, "binary", "-diff -crlf"); - * - * @param repo The repository to add the macro in. - * @param name The name of the macro. - * @param values The value for the macro. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_attr_add_macro( - git_repository *repo, - const char *name, - const char *values); - -/** @} */ -GIT_END_DECL -#endif - +/* + * 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_attr_h__ +#define INCLUDE_git_attr_h__ + +#include "common.h" +#include "types.h" + +/** + * @file git2/attr.h + * @brief Git attribute management routines + * @defgroup git_attr Git attribute management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * GIT_ATTR_TRUE checks if an attribute is set on. In core git + * parlance, this the value for "Set" attributes. + * + * For example, if the attribute file contains: + * + * *.c foo + * + * Then for file `xyz.c` looking up attribute "foo" gives a value for + * which `GIT_ATTR_TRUE(value)` is true. + */ +#define GIT_ATTR_IS_TRUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_TRUE) + +/** + * GIT_ATTR_FALSE checks if an attribute is set off. In core git + * parlance, this is the value for attributes that are "Unset" (not to + * be confused with values that a "Unspecified"). + * + * For example, if the attribute file contains: + * + * *.h -foo + * + * Then for file `zyx.h` looking up attribute "foo" gives a value for + * which `GIT_ATTR_FALSE(value)` is true. + */ +#define GIT_ATTR_IS_FALSE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_FALSE) + +/** + * GIT_ATTR_UNSPECIFIED checks if an attribute is unspecified. This + * may be due to the attribute not being mentioned at all or because + * the attribute was explicitly set unspecified via the `!` operator. + * + * For example, if the attribute file contains: + * + * *.c foo + * *.h -foo + * onefile.c !foo + * + * Then for `onefile.c` looking up attribute "foo" yields a value with + * `GIT_ATTR_UNSPECIFIED(value)` of true. Also, looking up "foo" on + * file `onefile.rb` or looking up "bar" on any file will all give + * `GIT_ATTR_UNSPECIFIED(value)` of true. + */ +#define GIT_ATTR_IS_UNSPECIFIED(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_UNSPECIFIED) + +/** + * GIT_ATTR_HAS_VALUE checks if an attribute is set to a value (as + * opposed to TRUE, FALSE or UNSPECIFIED). This would be the case if + * for a file with something like: + * + * *.txt eol=lf + * + * Given this, looking up "eol" for `onefile.txt` will give back the + * string "lf" and `GIT_ATTR_SET_TO_VALUE(attr)` will return true. + */ +#define GIT_ATTR_HAS_VALUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_STRING) + +/** + * Possible states for an attribute + */ +typedef enum { + GIT_ATTR_VALUE_UNSPECIFIED = 0, /**< The attribute has been left unspecified */ + GIT_ATTR_VALUE_TRUE, /**< The attribute has been set */ + GIT_ATTR_VALUE_FALSE, /**< The attribute has been unset */ + GIT_ATTR_VALUE_STRING /**< This attribute has a value */ +} git_attr_value_t; + +/** + * Return the value type for a given attribute. + * + * This can be either `TRUE`, `FALSE`, `UNSPECIFIED` (if the attribute + * was not set at all), or `VALUE`, if the attribute was set to an + * actual string. + * + * If the attribute has a `VALUE` string, it can be accessed normally + * as a NULL-terminated C string. + * + * @param attr The attribute + * @return the value type for the attribute + */ +GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr); + +/** + * Check attribute flags: Reading values from index and working directory. + * + * When checking attributes, it is possible to check attribute files + * in both the working directory (if there is one) and the index (if + * there is one). You can explicitly choose where to check and in + * which order using the following flags. + * + * Core git usually checks the working directory then the index, + * except during a checkout when it checks the index first. It will + * use index only for creating archives or for a bare repo (if an + * index has been specified for the bare repo). + */ +#define GIT_ATTR_CHECK_FILE_THEN_INDEX 0 +#define GIT_ATTR_CHECK_INDEX_THEN_FILE 1 +#define GIT_ATTR_CHECK_INDEX_ONLY 2 + +/** + * Check attribute flags: controlling extended attribute behavior. + * + * Normally, attribute checks include looking in the /etc (or system + * equivalent) directory for a `gitattributes` file. Passing the + * `GIT_ATTR_CHECK_NO_SYSTEM` flag will cause attribute checks to + * ignore that file. + * + * Passing the `GIT_ATTR_CHECK_INCLUDE_HEAD` flag will use attributes + * from a `.gitattributes` file in the repository at the HEAD revision. + * + * Passing the `GIT_ATTR_CHECK_INCLUDE_COMMIT` flag will use attributes + * from a `.gitattributes` file in a specific commit. + */ +#define GIT_ATTR_CHECK_NO_SYSTEM (1 << 2) +#define GIT_ATTR_CHECK_INCLUDE_HEAD (1 << 3) +#define GIT_ATTR_CHECK_INCLUDE_COMMIT (1 << 4) + +/** +* An options structure for querying attributes. +*/ +typedef struct { + unsigned int version; + + /** A combination of GIT_ATTR_CHECK flags */ + unsigned int flags; + +#ifdef GIT_DEPRECATE_HARD + void *reserved; +#else + git_oid *commit_id; +#endif + + /** + * The commit to load attributes from, when + * `GIT_ATTR_CHECK_INCLUDE_COMMIT` is specified. + */ + git_oid attr_commit_id; +} git_attr_options; + +#define GIT_ATTR_OPTIONS_VERSION 1 +#define GIT_ATTR_OPTIONS_INIT {GIT_ATTR_OPTIONS_VERSION} + +/** + * Look up the value of one git attribute for path. + * + * @param value_out Output of the value of the attribute. Use the GIT_ATTR_... + * macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just + * use the string value for attributes set to a value. You + * should NOT modify or free this value. + * @param repo The repository containing the path. + * @param flags A combination of GIT_ATTR_CHECK... flags. + * @param path The path to check for attributes. Relative paths are + * interpreted relative to the repo root. The file does + * not have to exist, but if it does not, then it will be + * treated as a plain file (not a directory). + * @param name The name of the attribute to look up. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_attr_get( + const char **value_out, + git_repository *repo, + uint32_t flags, + const char *path, + const char *name); + +/** + * Look up the value of one git attribute for path with extended options. + * + * @param value_out Output of the value of the attribute. Use the GIT_ATTR_... + * macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just + * use the string value for attributes set to a value. You + * should NOT modify or free this value. + * @param repo The repository containing the path. + * @param opts The `git_attr_options` to use when querying these attributes. + * @param path The path to check for attributes. Relative paths are + * interpreted relative to the repo root. The file does + * not have to exist, but if it does not, then it will be + * treated as a plain file (not a directory). + * @param name The name of the attribute to look up. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_attr_get_ext( + const char **value_out, + git_repository *repo, + git_attr_options *opts, + const char *path, + const char *name); + +/** + * Look up a list of git attributes for path. + * + * Use this if you have a known list of attributes that you want to + * look up in a single call. This is somewhat more efficient than + * calling `git_attr_get()` multiple times. + * + * For example, you might write: + * + * const char *attrs[] = { "crlf", "diff", "foo" }; + * const char **values[3]; + * git_attr_get_many(values, repo, 0, "my/fun/file.c", 3, attrs); + * + * Then you could loop through the 3 values to get the settings for + * the three attributes you asked about. + * + * @param values_out An array of num_attr entries that will have string + * pointers written into it for the values of the attributes. + * You should not modify or free the values that are written + * into this array (although of course, you should free the + * array itself if you allocated it). + * @param repo The repository containing the path. + * @param flags A combination of GIT_ATTR_CHECK... flags. + * @param path The path inside the repo to check attributes. This + * does not have to exist, but if it does not, then + * it will be treated as a plain file (i.e. not a directory). + * @param num_attr The number of attributes being looked up + * @param names An array of num_attr strings containing attribute names. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_attr_get_many( + const char **values_out, + git_repository *repo, + uint32_t flags, + const char *path, + size_t num_attr, + const char **names); + +/** + * Look up a list of git attributes for path with extended options. + * + * @param values_out An array of num_attr entries that will have string + * pointers written into it for the values of the attributes. + * You should not modify or free the values that are written + * into this array (although of course, you should free the + * array itself if you allocated it). + * @param repo The repository containing the path. + * @param opts The `git_attr_options` to use when querying these attributes. + * @param path The path inside the repo to check attributes. This + * does not have to exist, but if it does not, then + * it will be treated as a plain file (i.e. not a directory). + * @param num_attr The number of attributes being looked up + * @param names An array of num_attr strings containing attribute names. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_attr_get_many_ext( + const char **values_out, + git_repository *repo, + git_attr_options *opts, + const char *path, + size_t num_attr, + const char **names); + +/** + * The callback used with git_attr_foreach. + * + * This callback will be invoked only once per attribute name, even if there + * are multiple rules for a given file. The highest priority rule will be + * used. + * + * @see git_attr_foreach. + * + * @param name The attribute name. + * @param value The attribute value. May be NULL if the attribute is explicitly + * set to UNSPECIFIED using the '!' sign. + * @param payload A user-specified pointer. + * @return 0 to continue looping, non-zero to stop. This value will be returned + * from git_attr_foreach. + */ +typedef int GIT_CALLBACK(git_attr_foreach_cb)(const char *name, const char *value, void *payload); + +/** + * Loop over all the git attributes for a path. + * + * @param repo The repository containing the path. + * @param flags A combination of GIT_ATTR_CHECK... flags. + * @param path Path inside the repo to check attributes. This does not have + * to exist, but if it does not, then it will be treated as a + * plain file (i.e. not a directory). + * @param callback Function to invoke on each attribute name and value. + * See git_attr_foreach_cb. + * @param payload Passed on as extra parameter to callback function. + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_attr_foreach( + git_repository *repo, + uint32_t flags, + const char *path, + git_attr_foreach_cb callback, + void *payload); + +/** + * Loop over all the git attributes for a path with extended options. + * + * @param repo The repository containing the path. + * @param opts The `git_attr_options` to use when querying these attributes. + * @param path Path inside the repo to check attributes. This does not have + * to exist, but if it does not, then it will be treated as a + * plain file (i.e. not a directory). + * @param callback Function to invoke on each attribute name and value. + * See git_attr_foreach_cb. + * @param payload Passed on as extra parameter to callback function. + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_attr_foreach_ext( + git_repository *repo, + git_attr_options *opts, + const char *path, + git_attr_foreach_cb callback, + void *payload); + +/** + * Flush the gitattributes cache. + * + * Call this if you have reason to believe that the attributes files on + * disk no longer match the cached contents of memory. This will cause + * the attributes files to be reloaded the next time that an attribute + * access function is called. + * + * @param repo The repository containing the gitattributes cache + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_attr_cache_flush( + git_repository *repo); + +/** + * Add a macro definition. + * + * Macros will automatically be loaded from the top level `.gitattributes` + * file of the repository (plus the built-in "binary" macro). This + * function allows you to add others. For example, to add the default + * macro, you would call: + * + * git_attr_add_macro(repo, "binary", "-diff -crlf"); + * + * @param repo The repository to add the macro in. + * @param name The name of the macro. + * @param values The value for the macro. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_attr_add_macro( + git_repository *repo, + const char *name, + const char *values); + +/** @} */ +GIT_END_DECL +#endif + diff --git a/3rdparty/libgit2/include/git2/blame.h b/3rdparty/libgit2/include/git2/blame.h index cb961a5..63e9bba 100644 --- a/3rdparty/libgit2/include/git2/blame.h +++ b/3rdparty/libgit2/include/git2/blame.h @@ -1,285 +1,285 @@ -/* - * 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_blame_h__ -#define INCLUDE_git_blame_h__ - -#include "common.h" -#include "oid.h" - -/** - * @file git2/blame.h - * @brief Git blame routines - * @defgroup git_blame Git blame routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Flags for indicating option behavior for git_blame APIs. - */ -typedef enum { - /** Normal blame, the default */ - GIT_BLAME_NORMAL = 0, - - /** - * Track lines that have moved within a file (like `git blame -M`). - * - * This is not yet implemented and reserved for future use. - */ - GIT_BLAME_TRACK_COPIES_SAME_FILE = (1<<0), - - /** - * Track lines that have moved across files in the same commit - * (like `git blame -C`). - * - * This is not yet implemented and reserved for future use. - */ - GIT_BLAME_TRACK_COPIES_SAME_COMMIT_MOVES = (1<<1), - - /** - * Track lines that have been copied from another file that exists - * in the same commit (like `git blame -CC`). Implies SAME_FILE. - * - * This is not yet implemented and reserved for future use. - */ - GIT_BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = (1<<2), - - /** - * Track lines that have been copied from another file that exists in - * *any* commit (like `git blame -CCC`). Implies SAME_COMMIT_COPIES. - * - * This is not yet implemented and reserved for future use. - */ - GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = (1<<3), - - /** - * Restrict the search of commits to those reachable following only - * the first parents. - */ - GIT_BLAME_FIRST_PARENT = (1<<4), - - /** - * Use mailmap file to map author and committer names and email - * addresses to canonical real names and email addresses. The - * mailmap will be read from the working directory, or HEAD in a - * bare repository. - */ - GIT_BLAME_USE_MAILMAP = (1<<5), - - /** Ignore whitespace differences */ - GIT_BLAME_IGNORE_WHITESPACE = (1<<6) -} git_blame_flag_t; - -/** - * Blame options structure - * - * Initialize with `GIT_BLAME_OPTIONS_INIT`. Alternatively, you can - * use `git_blame_options_init`. - * - */ -typedef struct git_blame_options { - unsigned int version; - - /** A combination of `git_blame_flag_t` */ - uint32_t flags; - - /** - * The lower bound on the number of alphanumeric characters that - * must be detected as moving/copying within a file for it to - * associate those lines with the parent commit. The default value - * is 20. - * - * This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*` - * flags are specified. - */ - uint16_t min_match_characters; - - /** The id of the newest commit to consider. The default is HEAD. */ - git_oid newest_commit; - - /** - * The id of the oldest commit to consider. - * The default is the first commit encountered with a NULL parent. - */ - git_oid oldest_commit; - - /** - * The first line in the file to blame. - * The default is 1 (line numbers start with 1). - */ - size_t min_line; - - /** - * The last line in the file to blame. - * The default is the last line of the file. - */ - size_t max_line; -} git_blame_options; - -#define GIT_BLAME_OPTIONS_VERSION 1 -#define GIT_BLAME_OPTIONS_INIT {GIT_BLAME_OPTIONS_VERSION} - -/** - * Initialize git_blame_options structure - * - * Initializes a `git_blame_options` with default values. Equivalent to creating - * an instance with GIT_BLAME_OPTIONS_INIT. - * - * @param opts The `git_blame_options` struct to initialize. - * @param version The struct version; pass `GIT_BLAME_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_blame_options_init( - git_blame_options *opts, - unsigned int version); - -/** - * Structure that represents a blame hunk. - */ -typedef struct git_blame_hunk { - /** - * The number of lines in this hunk. - */ - size_t lines_in_hunk; - - /** - * The OID of the commit where this line was last changed. - */ - git_oid final_commit_id; - - /** - * The 1-based line number where this hunk begins, in the final version - * of the file. - */ - size_t final_start_line_number; - - /** - * The author of `final_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been - * specified, it will contain the canonical real name and email address. - */ - git_signature *final_signature; - - /** - * The OID of the commit where this hunk was found. - * This will usually be the same as `final_commit_id`, except when - * `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified. - */ - git_oid orig_commit_id; - - /** - * The path to the file where this hunk originated, as of the commit - * specified by `orig_commit_id`. - */ - const char *orig_path; - - /** - * The 1-based line number where this hunk begins in the file named by - * `orig_path` in the commit specified by `orig_commit_id`. - */ - size_t orig_start_line_number; - - /** - * The author of `orig_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been - * specified, it will contain the canonical real name and email address. - */ - git_signature *orig_signature; - - /** - * The 1 iff the hunk has been tracked to a boundary commit (the root, - * or the commit specified in git_blame_options.oldest_commit) - */ - char boundary; -} git_blame_hunk; - - -/** Opaque structure to hold blame results */ -typedef struct git_blame git_blame; - -/** - * Gets the number of hunks that exist in the blame structure. - * - * @param blame The blame structure to query. - * @return The number of hunks. - */ -GIT_EXTERN(uint32_t) git_blame_get_hunk_count(git_blame *blame); - -/** - * Gets the blame hunk at the given index. - * - * @param blame the blame structure to query - * @param index index of the hunk to retrieve - * @return the hunk at the given index, or NULL on error - */ -GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byindex( - git_blame *blame, - uint32_t index); - -/** - * Gets the hunk that relates to the given line number in the newest commit. - * - * @param blame the blame structure to query - * @param lineno the (1-based) line number to find a hunk for - * @return the hunk that contains the given line, or NULL on error - */ -GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byline( - git_blame *blame, - size_t lineno); - -/** - * Get the blame for a single file. - * - * @param out pointer that will receive the blame object - * @param repo repository whose history is to be walked - * @param path path to file to consider - * @param options options for the blame operation. If NULL, this is treated as - * though GIT_BLAME_OPTIONS_INIT were passed. - * @return 0 on success, or an error code. (use git_error_last for information - * about the error.) - */ -GIT_EXTERN(int) git_blame_file( - git_blame **out, - git_repository *repo, - const char *path, - git_blame_options *options); - - -/** - * Get blame data for a file that has been modified in memory. The `reference` - * parameter is a pre-calculated blame for the in-odb history of the file. This - * means that once a file blame is completed (which can be expensive), updating - * the buffer blame is very fast. - * - * Lines that differ between the buffer and the committed version are marked as - * having a zero OID for their final_commit_id. - * - * @param out pointer that will receive the resulting blame data - * @param reference cached blame from the history of the file (usually the output - * from git_blame_file) - * @param buffer the (possibly) modified contents of the file - * @param buffer_len number of valid bytes in the buffer - * @return 0 on success, or an error code. (use git_error_last for information - * about the error) - */ -GIT_EXTERN(int) git_blame_buffer( - git_blame **out, - git_blame *reference, - const char *buffer, - size_t buffer_len); - -/** - * Free memory allocated by git_blame_file or git_blame_buffer. - * - * @param blame the blame structure to free - */ -GIT_EXTERN(void) git_blame_free(git_blame *blame); - -/** @} */ -GIT_END_DECL -#endif - +/* + * 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_blame_h__ +#define INCLUDE_git_blame_h__ + +#include "common.h" +#include "oid.h" + +/** + * @file git2/blame.h + * @brief Git blame routines + * @defgroup git_blame Git blame routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Flags for indicating option behavior for git_blame APIs. + */ +typedef enum { + /** Normal blame, the default */ + GIT_BLAME_NORMAL = 0, + + /** + * Track lines that have moved within a file (like `git blame -M`). + * + * This is not yet implemented and reserved for future use. + */ + GIT_BLAME_TRACK_COPIES_SAME_FILE = (1<<0), + + /** + * Track lines that have moved across files in the same commit + * (like `git blame -C`). + * + * This is not yet implemented and reserved for future use. + */ + GIT_BLAME_TRACK_COPIES_SAME_COMMIT_MOVES = (1<<1), + + /** + * Track lines that have been copied from another file that exists + * in the same commit (like `git blame -CC`). Implies SAME_FILE. + * + * This is not yet implemented and reserved for future use. + */ + GIT_BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = (1<<2), + + /** + * Track lines that have been copied from another file that exists in + * *any* commit (like `git blame -CCC`). Implies SAME_COMMIT_COPIES. + * + * This is not yet implemented and reserved for future use. + */ + GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = (1<<3), + + /** + * Restrict the search of commits to those reachable following only + * the first parents. + */ + GIT_BLAME_FIRST_PARENT = (1<<4), + + /** + * Use mailmap file to map author and committer names and email + * addresses to canonical real names and email addresses. The + * mailmap will be read from the working directory, or HEAD in a + * bare repository. + */ + GIT_BLAME_USE_MAILMAP = (1<<5), + + /** Ignore whitespace differences */ + GIT_BLAME_IGNORE_WHITESPACE = (1<<6) +} git_blame_flag_t; + +/** + * Blame options structure + * + * Initialize with `GIT_BLAME_OPTIONS_INIT`. Alternatively, you can + * use `git_blame_options_init`. + * + */ +typedef struct git_blame_options { + unsigned int version; + + /** A combination of `git_blame_flag_t` */ + uint32_t flags; + + /** + * The lower bound on the number of alphanumeric characters that + * must be detected as moving/copying within a file for it to + * associate those lines with the parent commit. The default value + * is 20. + * + * This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*` + * flags are specified. + */ + uint16_t min_match_characters; + + /** The id of the newest commit to consider. The default is HEAD. */ + git_oid newest_commit; + + /** + * The id of the oldest commit to consider. + * The default is the first commit encountered with a NULL parent. + */ + git_oid oldest_commit; + + /** + * The first line in the file to blame. + * The default is 1 (line numbers start with 1). + */ + size_t min_line; + + /** + * The last line in the file to blame. + * The default is the last line of the file. + */ + size_t max_line; +} git_blame_options; + +#define GIT_BLAME_OPTIONS_VERSION 1 +#define GIT_BLAME_OPTIONS_INIT {GIT_BLAME_OPTIONS_VERSION} + +/** + * Initialize git_blame_options structure + * + * Initializes a `git_blame_options` with default values. Equivalent to creating + * an instance with GIT_BLAME_OPTIONS_INIT. + * + * @param opts The `git_blame_options` struct to initialize. + * @param version The struct version; pass `GIT_BLAME_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_blame_options_init( + git_blame_options *opts, + unsigned int version); + +/** + * Structure that represents a blame hunk. + */ +typedef struct git_blame_hunk { + /** + * The number of lines in this hunk. + */ + size_t lines_in_hunk; + + /** + * The OID of the commit where this line was last changed. + */ + git_oid final_commit_id; + + /** + * The 1-based line number where this hunk begins, in the final version + * of the file. + */ + size_t final_start_line_number; + + /** + * The author of `final_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been + * specified, it will contain the canonical real name and email address. + */ + git_signature *final_signature; + + /** + * The OID of the commit where this hunk was found. + * This will usually be the same as `final_commit_id`, except when + * `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified. + */ + git_oid orig_commit_id; + + /** + * The path to the file where this hunk originated, as of the commit + * specified by `orig_commit_id`. + */ + const char *orig_path; + + /** + * The 1-based line number where this hunk begins in the file named by + * `orig_path` in the commit specified by `orig_commit_id`. + */ + size_t orig_start_line_number; + + /** + * The author of `orig_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been + * specified, it will contain the canonical real name and email address. + */ + git_signature *orig_signature; + + /** + * The 1 iff the hunk has been tracked to a boundary commit (the root, + * or the commit specified in git_blame_options.oldest_commit) + */ + char boundary; +} git_blame_hunk; + + +/** Opaque structure to hold blame results */ +typedef struct git_blame git_blame; + +/** + * Gets the number of hunks that exist in the blame structure. + * + * @param blame The blame structure to query. + * @return The number of hunks. + */ +GIT_EXTERN(uint32_t) git_blame_get_hunk_count(git_blame *blame); + +/** + * Gets the blame hunk at the given index. + * + * @param blame the blame structure to query + * @param index index of the hunk to retrieve + * @return the hunk at the given index, or NULL on error + */ +GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byindex( + git_blame *blame, + uint32_t index); + +/** + * Gets the hunk that relates to the given line number in the newest commit. + * + * @param blame the blame structure to query + * @param lineno the (1-based) line number to find a hunk for + * @return the hunk that contains the given line, or NULL on error + */ +GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byline( + git_blame *blame, + size_t lineno); + +/** + * Get the blame for a single file. + * + * @param out pointer that will receive the blame object + * @param repo repository whose history is to be walked + * @param path path to file to consider + * @param options options for the blame operation. If NULL, this is treated as + * though GIT_BLAME_OPTIONS_INIT were passed. + * @return 0 on success, or an error code. (use git_error_last for information + * about the error.) + */ +GIT_EXTERN(int) git_blame_file( + git_blame **out, + git_repository *repo, + const char *path, + git_blame_options *options); + + +/** + * Get blame data for a file that has been modified in memory. The `reference` + * parameter is a pre-calculated blame for the in-odb history of the file. This + * means that once a file blame is completed (which can be expensive), updating + * the buffer blame is very fast. + * + * Lines that differ between the buffer and the committed version are marked as + * having a zero OID for their final_commit_id. + * + * @param out pointer that will receive the resulting blame data + * @param reference cached blame from the history of the file (usually the output + * from git_blame_file) + * @param buffer the (possibly) modified contents of the file + * @param buffer_len number of valid bytes in the buffer + * @return 0 on success, or an error code. (use git_error_last for information + * about the error) + */ +GIT_EXTERN(int) git_blame_buffer( + git_blame **out, + git_blame *reference, + const char *buffer, + size_t buffer_len); + +/** + * Free memory allocated by git_blame_file or git_blame_buffer. + * + * @param blame the blame structure to free + */ +GIT_EXTERN(void) git_blame_free(git_blame *blame); + +/** @} */ +GIT_END_DECL +#endif + diff --git a/3rdparty/libgit2/include/git2/blob.h b/3rdparty/libgit2/include/git2/blob.h index 6db85f3..2e85990 100644 --- a/3rdparty/libgit2/include/git2/blob.h +++ b/3rdparty/libgit2/include/git2/blob.h @@ -1,311 +1,311 @@ -/* - * 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_blob_h__ -#define INCLUDE_git_blob_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "object.h" -#include "buffer.h" - -/** - * @file git2/blob.h - * @brief Git blob load and write routines - * @defgroup git_blob Git blob load and write routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Lookup a blob object from a repository. - * - * @param blob pointer to the looked up blob - * @param repo the repo to use when locating the blob. - * @param id identity of the blob to locate. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_blob_lookup(git_blob **blob, git_repository *repo, const git_oid *id); - -/** - * Lookup a blob object from a repository, - * given a prefix of its identifier (short id). - * - * @see git_object_lookup_prefix - * - * @param blob pointer to the looked up blob - * @param repo the repo to use when locating the blob. - * @param id identity of the blob to locate. - * @param len the length of the short identifier - * @return 0 or an error code - */ -GIT_EXTERN(int) git_blob_lookup_prefix(git_blob **blob, git_repository *repo, const git_oid *id, size_t len); - -/** - * Close an open blob - * - * This is a wrapper around git_object_free() - * - * IMPORTANT: - * It *is* necessary to call this method when you stop - * using a blob. Failure to do so will cause a memory leak. - * - * @param blob the blob to close - */ -GIT_EXTERN(void) git_blob_free(git_blob *blob); - -/** - * Get the id of a blob. - * - * @param blob a previously loaded blob. - * @return SHA1 hash for this blob. - */ -GIT_EXTERN(const git_oid *) git_blob_id(const git_blob *blob); - -/** - * Get the repository that contains the blob. - * - * @param blob A previously loaded blob. - * @return Repository that contains this blob. - */ -GIT_EXTERN(git_repository *) git_blob_owner(const git_blob *blob); - -/** - * Get a read-only buffer with the raw content of a blob. - * - * A pointer to the raw content of a blob is returned; - * this pointer is owned internally by the object and shall - * not be free'd. The pointer may be invalidated at a later - * time. - * - * @param blob pointer to the blob - * @return the pointer, or NULL on error - */ -GIT_EXTERN(const void *) git_blob_rawcontent(const git_blob *blob); - -/** - * Get the size in bytes of the contents of a blob - * - * @param blob pointer to the blob - * @return size on bytes - */ -GIT_EXTERN(git_object_size_t) git_blob_rawsize(const git_blob *blob); - -/** - * Flags to control the functionality of `git_blob_filter`. - */ -typedef enum { - /** When set, filters will not be applied to binary files. */ - GIT_BLOB_FILTER_CHECK_FOR_BINARY = (1 << 0), - - /** - * When set, filters will not load configuration from the - * system-wide `gitattributes` in `/etc` (or system equivalent). - */ - GIT_BLOB_FILTER_NO_SYSTEM_ATTRIBUTES = (1 << 1), - - /** - * When set, filters will be loaded from a `.gitattributes` file - * in the HEAD commit. - */ - GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD = (1 << 2), - - /** - * When set, filters will be loaded from a `.gitattributes` file - * in the specified commit. - */ - GIT_BLOB_FILTER_ATTRIBUTES_FROM_COMMIT = (1 << 3) -} git_blob_filter_flag_t; - -/** - * The options used when applying filter options to a file. - * - * Initialize with `GIT_BLOB_FILTER_OPTIONS_INIT`. Alternatively, you can - * use `git_blob_filter_options_init`. - * - */ -typedef struct { - int version; - - /** Flags to control the filtering process, see `git_blob_filter_flag_t` above */ - uint32_t flags; - -#ifdef GIT_DEPRECATE_HARD - void *reserved; -#else - git_oid *commit_id; -#endif - - /** - * The commit to load attributes from, when - * `GIT_BLOB_FILTER_ATTRIBUTES_FROM_COMMIT` is specified. - */ - git_oid attr_commit_id; -} git_blob_filter_options; - -#define GIT_BLOB_FILTER_OPTIONS_VERSION 1 -#define GIT_BLOB_FILTER_OPTIONS_INIT {GIT_BLOB_FILTER_OPTIONS_VERSION, GIT_BLOB_FILTER_CHECK_FOR_BINARY} - -/** - * Initialize git_blob_filter_options structure - * - * Initializes a `git_blob_filter_options` with default values. Equivalent - * to creating an instance with `GIT_BLOB_FILTER_OPTIONS_INIT`. - * - * @param opts The `git_blob_filter_options` struct to initialize. - * @param version The struct version; pass `GIT_BLOB_FILTER_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsigned int version); - -/** - * Get a buffer with the filtered content of a blob. - * - * This applies filters as if the blob was being checked out to the - * working directory under the specified filename. This may apply - * CRLF filtering or other types of changes depending on the file - * attributes set for the blob and the content detected in it. - * - * The output is written into a `git_buf` which the caller must free - * when done (via `git_buf_dispose`). - * - * If no filters need to be applied, then the `out` buffer will just - * be populated with a pointer to the raw content of the blob. In - * that case, be careful to *not* free the blob until done with the - * buffer or copy it into memory you own. - * - * @param out The git_buf to be filled in - * @param blob Pointer to the blob - * @param as_path Path used for file attribute lookups, etc. - * @param opts Options to use for filtering the blob - * @return 0 on success or an error code - */ -GIT_EXTERN(int) git_blob_filter( - git_buf *out, - git_blob *blob, - const char *as_path, - git_blob_filter_options *opts); - -/** - * Read a file from the working folder of a repository - * and write it to the Object Database as a loose blob - * - * @param id return the id of the written blob - * @param repo repository where the blob will be written. - * this repository cannot be bare - * @param relative_path file from which the blob will be created, - * relative to the repository's working dir - * @return 0 or an error code - */ -GIT_EXTERN(int) git_blob_create_from_workdir(git_oid *id, git_repository *repo, const char *relative_path); - -/** - * Read a file from the filesystem and write its content - * to the Object Database as a loose blob - * - * @param id return the id of the written blob - * @param repo repository where the blob will be written. - * this repository can be bare or not - * @param path file from which the blob will be created - * @return 0 or an error code - */ -GIT_EXTERN(int) git_blob_create_from_disk(git_oid *id, git_repository *repo, const char *path); - -/** - * Create a stream to write a new blob into the object db - * - * This function may need to buffer the data on disk and will in - * general not be the right choice if you know the size of the data - * to write. If you have data in memory, use - * `git_blob_create_from_buffer()`. If you do not, but know the size of - * the contents (and don't want/need to perform filtering), use - * `git_odb_open_wstream()`. - * - * Don't close this stream yourself but pass it to - * `git_blob_create_from_stream_commit()` to commit the write to the - * object db and get the object id. - * - * If the `hintpath` parameter is filled, it will be used to determine - * what git filters should be applied to the object before it is written - * to the object database. - * - * @param out the stream into which to write - * @param repo Repository where the blob will be written. - * This repository can be bare or not. - * @param hintpath If not NULL, will be used to select data filters - * to apply onto the content of the blob to be created. - * @return 0 or error code - */ -GIT_EXTERN(int) git_blob_create_from_stream( - git_writestream **out, - git_repository *repo, - const char *hintpath); - -/** - * Close the stream and write the blob to the object db - * - * The stream will be closed and freed. - * - * @param out the id of the new blob - * @param stream the stream to close - * @return 0 or an error code - */ -GIT_EXTERN(int) git_blob_create_from_stream_commit( - git_oid *out, - git_writestream *stream); - -/** - * Write an in-memory buffer to the ODB as a blob - * - * @param id return the id of the written blob - * @param repo repository where the blob will be written - * @param buffer data to be written into the blob - * @param len length of the data - * @return 0 or an error code - */ -GIT_EXTERN(int) git_blob_create_from_buffer( - git_oid *id, git_repository *repo, const void *buffer, size_t len); - -/** - * Determine if the blob content is most certainly binary or not. - * - * The heuristic used to guess if a file is binary is taken from core git: - * Searching for NUL bytes and looking for a reasonable ratio of printable - * to non-printable characters among the first 8000 bytes. - * - * @param blob The blob which content should be analyzed - * @return 1 if the content of the blob is detected - * as binary; 0 otherwise. - */ -GIT_EXTERN(int) git_blob_is_binary(const git_blob *blob); - -/** - * Determine if the given content is most certainly binary or not; - * this is the same mechanism used by `git_blob_is_binary` but only - * looking at raw data. - * - * @param data The blob data which content should be analyzed - * @param len The length of the data - * @return 1 if the content of the blob is detected - * as binary; 0 otherwise. - */ -GIT_EXTERN(int) git_blob_data_is_binary(const char *data, size_t len); - -/** - * Create an in-memory copy of a blob. The copy must be explicitly - * free'd or it will leak. - * - * @param out Pointer to store the copy of the object - * @param source Original object to copy - * @return 0. - */ -GIT_EXTERN(int) git_blob_dup(git_blob **out, git_blob *source); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_blob_h__ +#define INCLUDE_git_blob_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "object.h" +#include "buffer.h" + +/** + * @file git2/blob.h + * @brief Git blob load and write routines + * @defgroup git_blob Git blob load and write routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Lookup a blob object from a repository. + * + * @param blob pointer to the looked up blob + * @param repo the repo to use when locating the blob. + * @param id identity of the blob to locate. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_blob_lookup(git_blob **blob, git_repository *repo, const git_oid *id); + +/** + * Lookup a blob object from a repository, + * given a prefix of its identifier (short id). + * + * @see git_object_lookup_prefix + * + * @param blob pointer to the looked up blob + * @param repo the repo to use when locating the blob. + * @param id identity of the blob to locate. + * @param len the length of the short identifier + * @return 0 or an error code + */ +GIT_EXTERN(int) git_blob_lookup_prefix(git_blob **blob, git_repository *repo, const git_oid *id, size_t len); + +/** + * Close an open blob + * + * This is a wrapper around git_object_free() + * + * IMPORTANT: + * It *is* necessary to call this method when you stop + * using a blob. Failure to do so will cause a memory leak. + * + * @param blob the blob to close + */ +GIT_EXTERN(void) git_blob_free(git_blob *blob); + +/** + * Get the id of a blob. + * + * @param blob a previously loaded blob. + * @return SHA1 hash for this blob. + */ +GIT_EXTERN(const git_oid *) git_blob_id(const git_blob *blob); + +/** + * Get the repository that contains the blob. + * + * @param blob A previously loaded blob. + * @return Repository that contains this blob. + */ +GIT_EXTERN(git_repository *) git_blob_owner(const git_blob *blob); + +/** + * Get a read-only buffer with the raw content of a blob. + * + * A pointer to the raw content of a blob is returned; + * this pointer is owned internally by the object and shall + * not be free'd. The pointer may be invalidated at a later + * time. + * + * @param blob pointer to the blob + * @return the pointer, or NULL on error + */ +GIT_EXTERN(const void *) git_blob_rawcontent(const git_blob *blob); + +/** + * Get the size in bytes of the contents of a blob + * + * @param blob pointer to the blob + * @return size on bytes + */ +GIT_EXTERN(git_object_size_t) git_blob_rawsize(const git_blob *blob); + +/** + * Flags to control the functionality of `git_blob_filter`. + */ +typedef enum { + /** When set, filters will not be applied to binary files. */ + GIT_BLOB_FILTER_CHECK_FOR_BINARY = (1 << 0), + + /** + * When set, filters will not load configuration from the + * system-wide `gitattributes` in `/etc` (or system equivalent). + */ + GIT_BLOB_FILTER_NO_SYSTEM_ATTRIBUTES = (1 << 1), + + /** + * When set, filters will be loaded from a `.gitattributes` file + * in the HEAD commit. + */ + GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD = (1 << 2), + + /** + * When set, filters will be loaded from a `.gitattributes` file + * in the specified commit. + */ + GIT_BLOB_FILTER_ATTRIBUTES_FROM_COMMIT = (1 << 3) +} git_blob_filter_flag_t; + +/** + * The options used when applying filter options to a file. + * + * Initialize with `GIT_BLOB_FILTER_OPTIONS_INIT`. Alternatively, you can + * use `git_blob_filter_options_init`. + * + */ +typedef struct { + int version; + + /** Flags to control the filtering process, see `git_blob_filter_flag_t` above */ + uint32_t flags; + +#ifdef GIT_DEPRECATE_HARD + void *reserved; +#else + git_oid *commit_id; +#endif + + /** + * The commit to load attributes from, when + * `GIT_BLOB_FILTER_ATTRIBUTES_FROM_COMMIT` is specified. + */ + git_oid attr_commit_id; +} git_blob_filter_options; + +#define GIT_BLOB_FILTER_OPTIONS_VERSION 1 +#define GIT_BLOB_FILTER_OPTIONS_INIT {GIT_BLOB_FILTER_OPTIONS_VERSION, GIT_BLOB_FILTER_CHECK_FOR_BINARY} + +/** + * Initialize git_blob_filter_options structure + * + * Initializes a `git_blob_filter_options` with default values. Equivalent + * to creating an instance with `GIT_BLOB_FILTER_OPTIONS_INIT`. + * + * @param opts The `git_blob_filter_options` struct to initialize. + * @param version The struct version; pass `GIT_BLOB_FILTER_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsigned int version); + +/** + * Get a buffer with the filtered content of a blob. + * + * This applies filters as if the blob was being checked out to the + * working directory under the specified filename. This may apply + * CRLF filtering or other types of changes depending on the file + * attributes set for the blob and the content detected in it. + * + * The output is written into a `git_buf` which the caller must free + * when done (via `git_buf_dispose`). + * + * If no filters need to be applied, then the `out` buffer will just + * be populated with a pointer to the raw content of the blob. In + * that case, be careful to *not* free the blob until done with the + * buffer or copy it into memory you own. + * + * @param out The git_buf to be filled in + * @param blob Pointer to the blob + * @param as_path Path used for file attribute lookups, etc. + * @param opts Options to use for filtering the blob + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_blob_filter( + git_buf *out, + git_blob *blob, + const char *as_path, + git_blob_filter_options *opts); + +/** + * Read a file from the working folder of a repository + * and write it to the Object Database as a loose blob + * + * @param id return the id of the written blob + * @param repo repository where the blob will be written. + * this repository cannot be bare + * @param relative_path file from which the blob will be created, + * relative to the repository's working dir + * @return 0 or an error code + */ +GIT_EXTERN(int) git_blob_create_from_workdir(git_oid *id, git_repository *repo, const char *relative_path); + +/** + * Read a file from the filesystem and write its content + * to the Object Database as a loose blob + * + * @param id return the id of the written blob + * @param repo repository where the blob will be written. + * this repository can be bare or not + * @param path file from which the blob will be created + * @return 0 or an error code + */ +GIT_EXTERN(int) git_blob_create_from_disk(git_oid *id, git_repository *repo, const char *path); + +/** + * Create a stream to write a new blob into the object db + * + * This function may need to buffer the data on disk and will in + * general not be the right choice if you know the size of the data + * to write. If you have data in memory, use + * `git_blob_create_from_buffer()`. If you do not, but know the size of + * the contents (and don't want/need to perform filtering), use + * `git_odb_open_wstream()`. + * + * Don't close this stream yourself but pass it to + * `git_blob_create_from_stream_commit()` to commit the write to the + * object db and get the object id. + * + * If the `hintpath` parameter is filled, it will be used to determine + * what git filters should be applied to the object before it is written + * to the object database. + * + * @param out the stream into which to write + * @param repo Repository where the blob will be written. + * This repository can be bare or not. + * @param hintpath If not NULL, will be used to select data filters + * to apply onto the content of the blob to be created. + * @return 0 or error code + */ +GIT_EXTERN(int) git_blob_create_from_stream( + git_writestream **out, + git_repository *repo, + const char *hintpath); + +/** + * Close the stream and write the blob to the object db + * + * The stream will be closed and freed. + * + * @param out the id of the new blob + * @param stream the stream to close + * @return 0 or an error code + */ +GIT_EXTERN(int) git_blob_create_from_stream_commit( + git_oid *out, + git_writestream *stream); + +/** + * Write an in-memory buffer to the ODB as a blob + * + * @param id return the id of the written blob + * @param repo repository where the blob will be written + * @param buffer data to be written into the blob + * @param len length of the data + * @return 0 or an error code + */ +GIT_EXTERN(int) git_blob_create_from_buffer( + git_oid *id, git_repository *repo, const void *buffer, size_t len); + +/** + * Determine if the blob content is most certainly binary or not. + * + * The heuristic used to guess if a file is binary is taken from core git: + * Searching for NUL bytes and looking for a reasonable ratio of printable + * to non-printable characters among the first 8000 bytes. + * + * @param blob The blob which content should be analyzed + * @return 1 if the content of the blob is detected + * as binary; 0 otherwise. + */ +GIT_EXTERN(int) git_blob_is_binary(const git_blob *blob); + +/** + * Determine if the given content is most certainly binary or not; + * this is the same mechanism used by `git_blob_is_binary` but only + * looking at raw data. + * + * @param data The blob data which content should be analyzed + * @param len The length of the data + * @return 1 if the content of the blob is detected + * as binary; 0 otherwise. + */ +GIT_EXTERN(int) git_blob_data_is_binary(const char *data, size_t len); + +/** + * Create an in-memory copy of a blob. The copy must be explicitly + * free'd or it will leak. + * + * @param out Pointer to store the copy of the object + * @param source Original object to copy + * @return 0. + */ +GIT_EXTERN(int) git_blob_dup(git_blob **out, git_blob *source); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/branch.h b/3rdparty/libgit2/include/git2/branch.h index 27c6fa1..df8c617 100644 --- a/3rdparty/libgit2/include/git2/branch.h +++ b/3rdparty/libgit2/include/git2/branch.h @@ -1,336 +1,336 @@ -/* - * 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_branch_h__ -#define INCLUDE_git_branch_h__ - -#include "common.h" -#include "oid.h" -#include "types.h" - -/** - * @file git2/branch.h - * @brief Git branch parsing routines - * @defgroup git_branch Git branch management - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Create a new branch pointing at a target commit - * - * A new direct reference will be created pointing to - * this target commit. If `force` is true and a reference - * already exists with the given name, it'll be replaced. - * - * The returned reference must be freed by the user. - * - * The branch name will be checked for validity. - * See `git_tag_create()` for rules about valid names. - * - * @param out Pointer where to store the underlying reference. - * - * @param repo the repository to create the branch in. - * - * @param branch_name Name for the branch; this name is - * validated for consistency. It should also not conflict with - * an already existing branch name. - * - * @param target Commit to which this branch should point. This object - * must belong to the given `repo`. - * - * @param force Overwrite existing branch. - * - * @return 0, GIT_EINVALIDSPEC or an error code. - * A proper reference is written in the refs/heads namespace - * pointing to the provided target commit. - */ -GIT_EXTERN(int) git_branch_create( - git_reference **out, - git_repository *repo, - const char *branch_name, - const git_commit *target, - int force); - -/** - * Create a new branch pointing at a target commit - * - * This behaves like `git_branch_create()` but takes an annotated - * commit, which lets you specify which extended sha syntax string was - * specified by a user, allowing for more exact reflog messages. - * - * See the documentation for `git_branch_create()`. - * - * @see git_branch_create - */ -GIT_EXTERN(int) git_branch_create_from_annotated( - git_reference **ref_out, - git_repository *repository, - const char *branch_name, - const git_annotated_commit *commit, - int force); - -/** - * Delete an existing branch reference. - * - * Note that if the deletion succeeds, the reference object will not - * be valid anymore, and should be freed immediately by the user using - * `git_reference_free()`. - * - * @param branch A valid reference representing a branch - * @return 0 on success, or an error code. - */ -GIT_EXTERN(int) git_branch_delete(git_reference *branch); - -/** Iterator type for branches */ -typedef struct git_branch_iterator git_branch_iterator; - -/** - * Create an iterator which loops over the requested branches. - * - * @param out the iterator - * @param repo Repository where to find the branches. - * @param list_flags Filtering flags for the branch - * listing. Valid values are GIT_BRANCH_LOCAL, GIT_BRANCH_REMOTE - * or GIT_BRANCH_ALL. - * - * @return 0 on success or an error code - */ -GIT_EXTERN(int) git_branch_iterator_new( - git_branch_iterator **out, - git_repository *repo, - git_branch_t list_flags); - -/** - * Retrieve the next branch from the iterator - * - * @param out the reference - * @param out_type the type of branch (local or remote-tracking) - * @param iter the branch iterator - * @return 0 on success, GIT_ITEROVER if there are no more branches or an error code. - */ -GIT_EXTERN(int) git_branch_next(git_reference **out, git_branch_t *out_type, git_branch_iterator *iter); - -/** - * Free a branch iterator - * - * @param iter the iterator to free - */ -GIT_EXTERN(void) git_branch_iterator_free(git_branch_iterator *iter); - -/** - * Move/rename an existing local branch reference. - * - * The new branch name will be checked for validity. - * See `git_tag_create()` for rules about valid names. - * - * Note that if the move succeeds, the old reference object will not - * be valid anymore, and should be freed immediately by the user using - * `git_reference_free()`. - * - * @param out New reference object for the updated name. - * - * @param branch Current underlying reference of the branch. - * - * @param new_branch_name Target name of the branch once the move - * is performed; this name is validated for consistency. - * - * @param force Overwrite existing branch. - * - * @return 0 on success, GIT_EINVALIDSPEC or an error code. - */ -GIT_EXTERN(int) git_branch_move( - git_reference **out, - git_reference *branch, - const char *new_branch_name, - int force); - -/** - * Lookup a branch by its name in a repository. - * - * The generated reference must be freed by the user. - * The branch name will be checked for validity. - * - * @see git_tag_create for rules about valid names. - * - * @param out pointer to the looked-up branch reference - * @param repo the repository to look up the branch - * @param branch_name Name of the branch to be looked-up; - * this name is validated for consistency. - * @param branch_type Type of the considered branch. This should - * be valued with either GIT_BRANCH_LOCAL or GIT_BRANCH_REMOTE. - * - * @return 0 on success; GIT_ENOTFOUND when no matching branch - * exists, GIT_EINVALIDSPEC, otherwise an error code. - */ -GIT_EXTERN(int) git_branch_lookup( - git_reference **out, - git_repository *repo, - const char *branch_name, - git_branch_t branch_type); - -/** - * Get the branch name - * - * Given a reference object, this will check that it really is a branch (ie. - * it lives under "refs/heads/" or "refs/remotes/"), and return the branch part - * of it. - * - * @param out Pointer to the abbreviated reference name. - * Owned by ref, do not free. - * - * @param ref A reference object, ideally pointing to a branch - * - * @return 0 on success; GIT_EINVALID if the reference isn't either a local or - * remote branch, otherwise an error code. - */ -GIT_EXTERN(int) git_branch_name( - const char **out, - const git_reference *ref); - -/** - * Get the upstream of a branch - * - * Given a reference, this will return a new reference object corresponding - * to its remote tracking branch. The reference must be a local branch. - * - * @see git_branch_upstream_name for details on the resolution. - * - * @param out Pointer where to store the retrieved reference. - * @param branch Current underlying reference of the branch. - * - * @return 0 on success; GIT_ENOTFOUND when no remote tracking - * reference exists, otherwise an error code. - */ -GIT_EXTERN(int) git_branch_upstream( - git_reference **out, - const git_reference *branch); - -/** - * Set a branch's upstream branch - * - * This will update the configuration to set the branch named `branch_name` as the upstream of `branch`. - * Pass a NULL name to unset the upstream information. - * - * @note the actual tracking reference must have been already created for the - * operation to succeed. - * - * @param branch the branch to configure - * @param branch_name remote-tracking or local branch to set as upstream. - * - * @return 0 on success; GIT_ENOTFOUND if there's no branch named `branch_name` - * or an error code - */ -GIT_EXTERN(int) git_branch_set_upstream( - git_reference *branch, - const char *branch_name); - -/** - * Get the upstream name of a branch - * - * Given a local branch, this will return its remote-tracking branch information, - * as a full reference name, ie. "feature/nice" would become - * "refs/remote/origin/feature/nice", depending on that branch's configuration. - * - * @param out the buffer into which the name will be written. - * @param repo the repository where the branches live. - * @param refname reference name of the local branch. - * - * @return 0 on success, GIT_ENOTFOUND when no remote tracking reference exists, - * or an error code. - */ -GIT_EXTERN(int) git_branch_upstream_name( - git_buf *out, - git_repository *repo, - const char *refname); - -/** - * Determine if HEAD points to the given branch - * - * @param branch A reference to a local branch. - * - * @return 1 if HEAD points at the branch, 0 if it isn't, or a negative value - * as an error code. - */ -GIT_EXTERN(int) git_branch_is_head( - const git_reference *branch); - -/** - * Determine if any HEAD points to the current branch - * - * This will iterate over all known linked repositories (usually in the form of - * worktrees) and report whether any HEAD is pointing at the current branch. - * - * @param branch A reference to a local branch. - * - * @return 1 if branch is checked out, 0 if it isn't, an error code otherwise. - */ -GIT_EXTERN(int) git_branch_is_checked_out( - const git_reference *branch); - -/** - * Find the remote name of a remote-tracking branch - * - * This will return the name of the remote whose fetch refspec is matching - * the given branch. E.g. given a branch "refs/remotes/test/master", it will - * extract the "test" part. If refspecs from multiple remotes match, - * the function will return GIT_EAMBIGUOUS. - * - * @param out The buffer into which the name will be written. - * @param repo The repository where the branch lives. - * @param refname complete name of the remote tracking branch. - * - * @return 0 on success, GIT_ENOTFOUND when no matching remote was found, - * GIT_EAMBIGUOUS when the branch maps to several remotes, - * otherwise an error code. - */ -GIT_EXTERN(int) git_branch_remote_name( - git_buf *out, - git_repository *repo, - const char *refname); - -/** - * Retrieve the upstream remote of a local branch - * - * This will return the currently configured "branch.*.remote" for a given - * branch. This branch must be local. - * - * @param buf the buffer into which to write the name - * @param repo the repository in which to look - * @param refname the full name of the branch - * @return 0 or an error code - */ - GIT_EXTERN(int) git_branch_upstream_remote(git_buf *buf, git_repository *repo, const char *refname); - -/** - * Retrieve the upstream merge of a local branch - * - * This will return the currently configured "branch.*.merge" for a given - * branch. This branch must be local. - * - * @param buf the buffer into which to write the name - * @param repo the repository in which to look - * @param refname the full name of the branch - * @return 0 or an error code - */ - GIT_EXTERN(int) git_branch_upstream_merge(git_buf *buf, git_repository *repo, const char *refname); - -/** - * Determine whether a branch name is valid, meaning that (when prefixed - * with `refs/heads/`) that it is a valid reference name, and that any - * additional branch name restrictions are imposed (eg, it cannot start - * with a `-`). - * - * @param valid output pointer to set with validity of given branch name - * @param name a branch name to test - * @return 0 on success or an error code - */ -GIT_EXTERN(int) git_branch_name_is_valid(int *valid, const char *name); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_branch_h__ +#define INCLUDE_git_branch_h__ + +#include "common.h" +#include "oid.h" +#include "types.h" + +/** + * @file git2/branch.h + * @brief Git branch parsing routines + * @defgroup git_branch Git branch management + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a new branch pointing at a target commit + * + * A new direct reference will be created pointing to + * this target commit. If `force` is true and a reference + * already exists with the given name, it'll be replaced. + * + * The returned reference must be freed by the user. + * + * The branch name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * + * @param out Pointer where to store the underlying reference. + * + * @param repo the repository to create the branch in. + * + * @param branch_name Name for the branch; this name is + * validated for consistency. It should also not conflict with + * an already existing branch name. + * + * @param target Commit to which this branch should point. This object + * must belong to the given `repo`. + * + * @param force Overwrite existing branch. + * + * @return 0, GIT_EINVALIDSPEC or an error code. + * A proper reference is written in the refs/heads namespace + * pointing to the provided target commit. + */ +GIT_EXTERN(int) git_branch_create( + git_reference **out, + git_repository *repo, + const char *branch_name, + const git_commit *target, + int force); + +/** + * Create a new branch pointing at a target commit + * + * This behaves like `git_branch_create()` but takes an annotated + * commit, which lets you specify which extended sha syntax string was + * specified by a user, allowing for more exact reflog messages. + * + * See the documentation for `git_branch_create()`. + * + * @see git_branch_create + */ +GIT_EXTERN(int) git_branch_create_from_annotated( + git_reference **ref_out, + git_repository *repository, + const char *branch_name, + const git_annotated_commit *commit, + int force); + +/** + * Delete an existing branch reference. + * + * Note that if the deletion succeeds, the reference object will not + * be valid anymore, and should be freed immediately by the user using + * `git_reference_free()`. + * + * @param branch A valid reference representing a branch + * @return 0 on success, or an error code. + */ +GIT_EXTERN(int) git_branch_delete(git_reference *branch); + +/** Iterator type for branches */ +typedef struct git_branch_iterator git_branch_iterator; + +/** + * Create an iterator which loops over the requested branches. + * + * @param out the iterator + * @param repo Repository where to find the branches. + * @param list_flags Filtering flags for the branch + * listing. Valid values are GIT_BRANCH_LOCAL, GIT_BRANCH_REMOTE + * or GIT_BRANCH_ALL. + * + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_branch_iterator_new( + git_branch_iterator **out, + git_repository *repo, + git_branch_t list_flags); + +/** + * Retrieve the next branch from the iterator + * + * @param out the reference + * @param out_type the type of branch (local or remote-tracking) + * @param iter the branch iterator + * @return 0 on success, GIT_ITEROVER if there are no more branches or an error code. + */ +GIT_EXTERN(int) git_branch_next(git_reference **out, git_branch_t *out_type, git_branch_iterator *iter); + +/** + * Free a branch iterator + * + * @param iter the iterator to free + */ +GIT_EXTERN(void) git_branch_iterator_free(git_branch_iterator *iter); + +/** + * Move/rename an existing local branch reference. + * + * The new branch name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * + * Note that if the move succeeds, the old reference object will not + * be valid anymore, and should be freed immediately by the user using + * `git_reference_free()`. + * + * @param out New reference object for the updated name. + * + * @param branch Current underlying reference of the branch. + * + * @param new_branch_name Target name of the branch once the move + * is performed; this name is validated for consistency. + * + * @param force Overwrite existing branch. + * + * @return 0 on success, GIT_EINVALIDSPEC or an error code. + */ +GIT_EXTERN(int) git_branch_move( + git_reference **out, + git_reference *branch, + const char *new_branch_name, + int force); + +/** + * Lookup a branch by its name in a repository. + * + * The generated reference must be freed by the user. + * The branch name will be checked for validity. + * + * @see git_tag_create for rules about valid names. + * + * @param out pointer to the looked-up branch reference + * @param repo the repository to look up the branch + * @param branch_name Name of the branch to be looked-up; + * this name is validated for consistency. + * @param branch_type Type of the considered branch. This should + * be valued with either GIT_BRANCH_LOCAL or GIT_BRANCH_REMOTE. + * + * @return 0 on success; GIT_ENOTFOUND when no matching branch + * exists, GIT_EINVALIDSPEC, otherwise an error code. + */ +GIT_EXTERN(int) git_branch_lookup( + git_reference **out, + git_repository *repo, + const char *branch_name, + git_branch_t branch_type); + +/** + * Get the branch name + * + * Given a reference object, this will check that it really is a branch (ie. + * it lives under "refs/heads/" or "refs/remotes/"), and return the branch part + * of it. + * + * @param out Pointer to the abbreviated reference name. + * Owned by ref, do not free. + * + * @param ref A reference object, ideally pointing to a branch + * + * @return 0 on success; GIT_EINVALID if the reference isn't either a local or + * remote branch, otherwise an error code. + */ +GIT_EXTERN(int) git_branch_name( + const char **out, + const git_reference *ref); + +/** + * Get the upstream of a branch + * + * Given a reference, this will return a new reference object corresponding + * to its remote tracking branch. The reference must be a local branch. + * + * @see git_branch_upstream_name for details on the resolution. + * + * @param out Pointer where to store the retrieved reference. + * @param branch Current underlying reference of the branch. + * + * @return 0 on success; GIT_ENOTFOUND when no remote tracking + * reference exists, otherwise an error code. + */ +GIT_EXTERN(int) git_branch_upstream( + git_reference **out, + const git_reference *branch); + +/** + * Set a branch's upstream branch + * + * This will update the configuration to set the branch named `branch_name` as the upstream of `branch`. + * Pass a NULL name to unset the upstream information. + * + * @note the actual tracking reference must have been already created for the + * operation to succeed. + * + * @param branch the branch to configure + * @param branch_name remote-tracking or local branch to set as upstream. + * + * @return 0 on success; GIT_ENOTFOUND if there's no branch named `branch_name` + * or an error code + */ +GIT_EXTERN(int) git_branch_set_upstream( + git_reference *branch, + const char *branch_name); + +/** + * Get the upstream name of a branch + * + * Given a local branch, this will return its remote-tracking branch information, + * as a full reference name, ie. "feature/nice" would become + * "refs/remote/origin/feature/nice", depending on that branch's configuration. + * + * @param out the buffer into which the name will be written. + * @param repo the repository where the branches live. + * @param refname reference name of the local branch. + * + * @return 0 on success, GIT_ENOTFOUND when no remote tracking reference exists, + * or an error code. + */ +GIT_EXTERN(int) git_branch_upstream_name( + git_buf *out, + git_repository *repo, + const char *refname); + +/** + * Determine if HEAD points to the given branch + * + * @param branch A reference to a local branch. + * + * @return 1 if HEAD points at the branch, 0 if it isn't, or a negative value + * as an error code. + */ +GIT_EXTERN(int) git_branch_is_head( + const git_reference *branch); + +/** + * Determine if any HEAD points to the current branch + * + * This will iterate over all known linked repositories (usually in the form of + * worktrees) and report whether any HEAD is pointing at the current branch. + * + * @param branch A reference to a local branch. + * + * @return 1 if branch is checked out, 0 if it isn't, an error code otherwise. + */ +GIT_EXTERN(int) git_branch_is_checked_out( + const git_reference *branch); + +/** + * Find the remote name of a remote-tracking branch + * + * This will return the name of the remote whose fetch refspec is matching + * the given branch. E.g. given a branch "refs/remotes/test/master", it will + * extract the "test" part. If refspecs from multiple remotes match, + * the function will return GIT_EAMBIGUOUS. + * + * @param out The buffer into which the name will be written. + * @param repo The repository where the branch lives. + * @param refname complete name of the remote tracking branch. + * + * @return 0 on success, GIT_ENOTFOUND when no matching remote was found, + * GIT_EAMBIGUOUS when the branch maps to several remotes, + * otherwise an error code. + */ +GIT_EXTERN(int) git_branch_remote_name( + git_buf *out, + git_repository *repo, + const char *refname); + +/** + * Retrieve the upstream remote of a local branch + * + * This will return the currently configured "branch.*.remote" for a given + * branch. This branch must be local. + * + * @param buf the buffer into which to write the name + * @param repo the repository in which to look + * @param refname the full name of the branch + * @return 0 or an error code + */ + GIT_EXTERN(int) git_branch_upstream_remote(git_buf *buf, git_repository *repo, const char *refname); + +/** + * Retrieve the upstream merge of a local branch + * + * This will return the currently configured "branch.*.merge" for a given + * branch. This branch must be local. + * + * @param buf the buffer into which to write the name + * @param repo the repository in which to look + * @param refname the full name of the branch + * @return 0 or an error code + */ + GIT_EXTERN(int) git_branch_upstream_merge(git_buf *buf, git_repository *repo, const char *refname); + +/** + * Determine whether a branch name is valid, meaning that (when prefixed + * with `refs/heads/`) that it is a valid reference name, and that any + * additional branch name restrictions are imposed (eg, it cannot start + * with a `-`). + * + * @param valid output pointer to set with validity of given branch name + * @param name a branch name to test + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_branch_name_is_valid(int *valid, const char *name); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/buffer.h b/3rdparty/libgit2/include/git2/buffer.h index 9fa9720..09803e9 100644 --- a/3rdparty/libgit2/include/git2/buffer.h +++ b/3rdparty/libgit2/include/git2/buffer.h @@ -1,74 +1,74 @@ -/* - * 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_buf_h__ -#define INCLUDE_git_buf_h__ - -#include "common.h" - -/** - * @file git2/buffer.h - * @brief Buffer export structure - * - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * A data buffer for exporting data from libgit2 - * - * Sometimes libgit2 wants to return an allocated data buffer to the - * caller and have the caller take responsibility for freeing that memory. - * To make ownership clear in these cases, libgit2 uses `git_buf` to - * return this data. Callers should use `git_buf_dispose()` to release - * the memory when they are done. - * - * A `git_buf` contains a pointer to a NUL-terminated C string, and - * the length of the string (not including the NUL terminator). - */ -typedef struct { - /** - * The buffer contents. `ptr` points to the start of the buffer - * being returned. The buffer's length (in bytes) is specified - * by the `size` member of the structure, and contains a NUL - * terminator at position `(size + 1)`. - */ - char *ptr; - - /** - * This field is reserved and unused. - */ - size_t reserved; - - /** - * The length (in bytes) of the buffer pointed to by `ptr`, - * not including a NUL terminator. - */ - size_t size; -} git_buf; - -/** - * Use to initialize a `git_buf` before passing it to a function that - * will populate it. - */ -#define GIT_BUF_INIT { NULL, 0, 0 } - -/** - * Free the memory referred to by the git_buf. - * - * Note that this does not free the `git_buf` itself, just the memory - * pointed to by `buffer->ptr`. - * - * @param buffer The buffer to deallocate - */ -GIT_EXTERN(void) git_buf_dispose(git_buf *buffer); - -GIT_END_DECL - -/** @} */ - -#endif +/* + * 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_buf_h__ +#define INCLUDE_git_buf_h__ + +#include "common.h" + +/** + * @file git2/buffer.h + * @brief Buffer export structure + * + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * A data buffer for exporting data from libgit2 + * + * Sometimes libgit2 wants to return an allocated data buffer to the + * caller and have the caller take responsibility for freeing that memory. + * To make ownership clear in these cases, libgit2 uses `git_buf` to + * return this data. Callers should use `git_buf_dispose()` to release + * the memory when they are done. + * + * A `git_buf` contains a pointer to a NUL-terminated C string, and + * the length of the string (not including the NUL terminator). + */ +typedef struct { + /** + * The buffer contents. `ptr` points to the start of the buffer + * being returned. The buffer's length (in bytes) is specified + * by the `size` member of the structure, and contains a NUL + * terminator at position `(size + 1)`. + */ + char *ptr; + + /** + * This field is reserved and unused. + */ + size_t reserved; + + /** + * The length (in bytes) of the buffer pointed to by `ptr`, + * not including a NUL terminator. + */ + size_t size; +} git_buf; + +/** + * Use to initialize a `git_buf` before passing it to a function that + * will populate it. + */ +#define GIT_BUF_INIT { NULL, 0, 0 } + +/** + * Free the memory referred to by the git_buf. + * + * Note that this does not free the `git_buf` itself, just the memory + * pointed to by `buffer->ptr`. + * + * @param buffer The buffer to deallocate + */ +GIT_EXTERN(void) git_buf_dispose(git_buf *buffer); + +GIT_END_DECL + +/** @} */ + +#endif diff --git a/3rdparty/libgit2/include/git2/cert.h b/3rdparty/libgit2/include/git2/cert.h index 05213a5..2c94dba 100644 --- a/3rdparty/libgit2/include/git2/cert.h +++ b/3rdparty/libgit2/include/git2/cert.h @@ -1,172 +1,172 @@ -/* - * 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_cert_h__ -#define INCLUDE_git_cert_h__ - -#include "common.h" -#include "types.h" - -/** - * @file git2/cert.h - * @brief Git certificate objects - * @defgroup git_cert Certificate objects - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Type of host certificate structure that is passed to the check callback - */ -typedef enum git_cert_t { - /** - * No information about the certificate is available. This may - * happen when using curl. - */ - GIT_CERT_NONE, - /** - * The `data` argument to the callback will be a pointer to - * the DER-encoded data. - */ - GIT_CERT_X509, - /** - * The `data` argument to the callback will be a pointer to a - * `git_cert_hostkey` structure. - */ - GIT_CERT_HOSTKEY_LIBSSH2, - /** - * The `data` argument to the callback will be a pointer to a - * `git_strarray` with `name:content` strings containing - * information about the certificate. This is used when using - * curl. - */ - GIT_CERT_STRARRAY -} git_cert_t; - -/** - * Parent type for `git_cert_hostkey` and `git_cert_x509`. - */ -struct git_cert { - /** - * Type of certificate. A `GIT_CERT_` value. - */ - git_cert_t cert_type; -}; - -/** - * Callback for the user's custom certificate checks. - * - * @param cert The host certificate - * @param valid Whether the libgit2 checks (OpenSSL or WinHTTP) think - * this certificate is valid - * @param host Hostname of the host libgit2 connected to - * @param payload Payload provided by the caller - * @return 0 to proceed with the connection, < 0 to fail the connection - * or > 0 to indicate that the callback refused to act and that - * the existing validity determination should be honored - */ -typedef int GIT_CALLBACK(git_transport_certificate_check_cb)(git_cert *cert, int valid, const char *host, void *payload); - -/** - * Type of SSH host fingerprint - */ -typedef enum { - /** MD5 is available */ - GIT_CERT_SSH_MD5 = (1 << 0), - /** SHA-1 is available */ - GIT_CERT_SSH_SHA1 = (1 << 1), - /** SHA-256 is available */ - GIT_CERT_SSH_SHA256 = (1 << 2), - /** Raw hostkey is available */ - GIT_CERT_SSH_RAW = (1 << 3) -} git_cert_ssh_t; - -typedef enum { - /** The raw key is of an unknown type. */ - GIT_CERT_SSH_RAW_TYPE_UNKNOWN = 0, - /** The raw key is an RSA key. */ - GIT_CERT_SSH_RAW_TYPE_RSA = 1, - /** The raw key is a DSS key. */ - GIT_CERT_SSH_RAW_TYPE_DSS = 2, - /** The raw key is a ECDSA 256 key. */ - GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_256 = 3, - /** The raw key is a ECDSA 384 key. */ - GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_384 = 4, - /** The raw key is a ECDSA 521 key. */ - GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_521 = 5, - /** The raw key is a ED25519 key. */ - GIT_CERT_SSH_RAW_TYPE_KEY_ED25519 = 6 -} git_cert_ssh_raw_type_t; - -/** - * Hostkey information taken from libssh2 - */ -typedef struct { - git_cert parent; /**< The parent cert */ - - /** - * A bitmask containing the available fields. - */ - git_cert_ssh_t type; - - /** - * Hostkey hash. If `type` has `GIT_CERT_SSH_MD5` set, this will - * have the MD5 hash of the hostkey. - */ - unsigned char hash_md5[16]; - - /** - * Hostkey hash. If `type` has `GIT_CERT_SSH_SHA1` set, this will - * have the SHA-1 hash of the hostkey. - */ - unsigned char hash_sha1[20]; - - /** - * Hostkey hash. If `type` has `GIT_CERT_SSH_SHA256` set, this will - * have the SHA-256 hash of the hostkey. - */ - unsigned char hash_sha256[32]; - - /** - * Raw hostkey type. If `type` has `GIT_CERT_SSH_RAW` set, this will - * have the type of the raw hostkey. - */ - git_cert_ssh_raw_type_t raw_type; - - /** - * Pointer to the raw hostkey. If `type` has `GIT_CERT_SSH_RAW` set, - * this will have the raw contents of the hostkey. - */ - const char *hostkey; - - /** - * Raw hostkey length. If `type` has `GIT_CERT_SSH_RAW` set, this will - * have the length of the raw contents of the hostkey. - */ - size_t hostkey_len; -} git_cert_hostkey; - -/** - * X.509 certificate information - */ -typedef struct { - git_cert parent; /**< The parent cert */ - - /** - * Pointer to the X.509 certificate data - */ - void *data; - - /** - * Length of the memory block pointed to by `data`. - */ - size_t len; -} git_cert_x509; - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_cert_h__ +#define INCLUDE_git_cert_h__ + +#include "common.h" +#include "types.h" + +/** + * @file git2/cert.h + * @brief Git certificate objects + * @defgroup git_cert Certificate objects + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Type of host certificate structure that is passed to the check callback + */ +typedef enum git_cert_t { + /** + * No information about the certificate is available. This may + * happen when using curl. + */ + GIT_CERT_NONE, + /** + * The `data` argument to the callback will be a pointer to + * the DER-encoded data. + */ + GIT_CERT_X509, + /** + * The `data` argument to the callback will be a pointer to a + * `git_cert_hostkey` structure. + */ + GIT_CERT_HOSTKEY_LIBSSH2, + /** + * The `data` argument to the callback will be a pointer to a + * `git_strarray` with `name:content` strings containing + * information about the certificate. This is used when using + * curl. + */ + GIT_CERT_STRARRAY +} git_cert_t; + +/** + * Parent type for `git_cert_hostkey` and `git_cert_x509`. + */ +struct git_cert { + /** + * Type of certificate. A `GIT_CERT_` value. + */ + git_cert_t cert_type; +}; + +/** + * Callback for the user's custom certificate checks. + * + * @param cert The host certificate + * @param valid Whether the libgit2 checks (OpenSSL or WinHTTP) think + * this certificate is valid + * @param host Hostname of the host libgit2 connected to + * @param payload Payload provided by the caller + * @return 0 to proceed with the connection, < 0 to fail the connection + * or > 0 to indicate that the callback refused to act and that + * the existing validity determination should be honored + */ +typedef int GIT_CALLBACK(git_transport_certificate_check_cb)(git_cert *cert, int valid, const char *host, void *payload); + +/** + * Type of SSH host fingerprint + */ +typedef enum { + /** MD5 is available */ + GIT_CERT_SSH_MD5 = (1 << 0), + /** SHA-1 is available */ + GIT_CERT_SSH_SHA1 = (1 << 1), + /** SHA-256 is available */ + GIT_CERT_SSH_SHA256 = (1 << 2), + /** Raw hostkey is available */ + GIT_CERT_SSH_RAW = (1 << 3) +} git_cert_ssh_t; + +typedef enum { + /** The raw key is of an unknown type. */ + GIT_CERT_SSH_RAW_TYPE_UNKNOWN = 0, + /** The raw key is an RSA key. */ + GIT_CERT_SSH_RAW_TYPE_RSA = 1, + /** The raw key is a DSS key. */ + GIT_CERT_SSH_RAW_TYPE_DSS = 2, + /** The raw key is a ECDSA 256 key. */ + GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_256 = 3, + /** The raw key is a ECDSA 384 key. */ + GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_384 = 4, + /** The raw key is a ECDSA 521 key. */ + GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_521 = 5, + /** The raw key is a ED25519 key. */ + GIT_CERT_SSH_RAW_TYPE_KEY_ED25519 = 6 +} git_cert_ssh_raw_type_t; + +/** + * Hostkey information taken from libssh2 + */ +typedef struct { + git_cert parent; /**< The parent cert */ + + /** + * A bitmask containing the available fields. + */ + git_cert_ssh_t type; + + /** + * Hostkey hash. If `type` has `GIT_CERT_SSH_MD5` set, this will + * have the MD5 hash of the hostkey. + */ + unsigned char hash_md5[16]; + + /** + * Hostkey hash. If `type` has `GIT_CERT_SSH_SHA1` set, this will + * have the SHA-1 hash of the hostkey. + */ + unsigned char hash_sha1[20]; + + /** + * Hostkey hash. If `type` has `GIT_CERT_SSH_SHA256` set, this will + * have the SHA-256 hash of the hostkey. + */ + unsigned char hash_sha256[32]; + + /** + * Raw hostkey type. If `type` has `GIT_CERT_SSH_RAW` set, this will + * have the type of the raw hostkey. + */ + git_cert_ssh_raw_type_t raw_type; + + /** + * Pointer to the raw hostkey. If `type` has `GIT_CERT_SSH_RAW` set, + * this will have the raw contents of the hostkey. + */ + const char *hostkey; + + /** + * Raw hostkey length. If `type` has `GIT_CERT_SSH_RAW` set, this will + * have the length of the raw contents of the hostkey. + */ + size_t hostkey_len; +} git_cert_hostkey; + +/** + * X.509 certificate information + */ +typedef struct { + git_cert parent; /**< The parent cert */ + + /** + * Pointer to the X.509 certificate data + */ + void *data; + + /** + * Length of the memory block pointed to by `data`. + */ + size_t len; +} git_cert_x509; + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/checkout.h b/3rdparty/libgit2/include/git2/checkout.h index 9f83411..0ad60a4 100644 --- a/3rdparty/libgit2/include/git2/checkout.h +++ b/3rdparty/libgit2/include/git2/checkout.h @@ -1,417 +1,417 @@ -/* - * 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_checkout_h__ -#define INCLUDE_git_checkout_h__ - -#include "common.h" -#include "types.h" -#include "diff.h" - -/** - * @file git2/checkout.h - * @brief Git checkout routines - * @defgroup git_checkout Git checkout routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Checkout behavior flags - * - * In libgit2, checkout is used to update the working directory and index - * to match a target tree. Unlike git checkout, it does not move the HEAD - * commit for you - use `git_repository_set_head` or the like to do that. - * - * Checkout looks at (up to) four things: the "target" tree you want to - * check out, the "baseline" tree of what was checked out previously, the - * working directory for actual files, and the index for staged changes. - * - * You give checkout one of three strategies for update: - * - * - `GIT_CHECKOUT_NONE` is a dry-run strategy that checks for conflicts, - * etc., but doesn't make any actual changes. - * - * - `GIT_CHECKOUT_FORCE` is at the opposite extreme, taking any action to - * make the working directory match the target (including potentially - * discarding modified files). - * - * - `GIT_CHECKOUT_SAFE` is between these two options, it will only make - * modifications that will not lose changes. - * - * | target == baseline | target != baseline | - * ---------------------|-----------------------|----------------------| - * workdir == baseline | no action | create, update, or | - * | | delete file | - * ---------------------|-----------------------|----------------------| - * workdir exists and | no action | conflict (notify | - * is != baseline | notify dirty MODIFIED | and cancel checkout) | - * ---------------------|-----------------------|----------------------| - * workdir missing, | notify dirty DELETED | create file | - * baseline present | | | - * ---------------------|-----------------------|----------------------| - * - * To emulate `git checkout`, use `GIT_CHECKOUT_SAFE` with a checkout - * notification callback (see below) that displays information about dirty - * files. The default behavior will cancel checkout on conflicts. - * - * To emulate `git checkout-index`, use `GIT_CHECKOUT_SAFE` with a - * notification callback that cancels the operation if a dirty-but-existing - * file is found in the working directory. This core git command isn't - * quite "force" but is sensitive about some types of changes. - * - * To emulate `git checkout -f`, use `GIT_CHECKOUT_FORCE`. - * - * - * There are some additional flags to modify the behavior of checkout: - * - * - GIT_CHECKOUT_ALLOW_CONFLICTS makes SAFE mode apply safe file updates - * even if there are conflicts (instead of cancelling the checkout). - * - * - GIT_CHECKOUT_REMOVE_UNTRACKED means remove untracked files (i.e. not - * in target, baseline, or index, and not ignored) from the working dir. - * - * - GIT_CHECKOUT_REMOVE_IGNORED means remove ignored files (that are also - * untracked) from the working directory as well. - * - * - GIT_CHECKOUT_UPDATE_ONLY means to only update the content of files that - * already exist. Files will not be created nor deleted. This just skips - * applying adds, deletes, and typechanges. - * - * - GIT_CHECKOUT_DONT_UPDATE_INDEX prevents checkout from writing the - * updated files' information to the index. - * - * - Normally, checkout will reload the index and git attributes from disk - * before any operations. GIT_CHECKOUT_NO_REFRESH prevents this reload. - * - * - Unmerged index entries are conflicts. GIT_CHECKOUT_SKIP_UNMERGED skips - * files with unmerged index entries instead. GIT_CHECKOUT_USE_OURS and - * GIT_CHECKOUT_USE_THEIRS to proceed with the checkout using either the - * stage 2 ("ours") or stage 3 ("theirs") version of files in the index. - * - * - GIT_CHECKOUT_DONT_OVERWRITE_IGNORED prevents ignored files from being - * overwritten. Normally, files that are ignored in the working directory - * are not considered "precious" and may be overwritten if the checkout - * target contains that file. - * - * - GIT_CHECKOUT_DONT_REMOVE_EXISTING prevents checkout from removing - * files or folders that fold to the same name on case insensitive - * filesystems. This can cause files to retain their existing names - * and write through existing symbolic links. - */ -typedef enum { - GIT_CHECKOUT_NONE = 0, /**< default is a dry run, no actual updates */ - - /** - * Allow safe updates that cannot overwrite uncommitted data. - * If the uncommitted changes don't conflict with the checked out files, - * the checkout will still proceed, leaving the changes intact. - * - * Mutually exclusive with GIT_CHECKOUT_FORCE. - * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE. - */ - GIT_CHECKOUT_SAFE = (1u << 0), - - /** - * Allow all updates to force working directory to look like index. - * - * Mutually exclusive with GIT_CHECKOUT_SAFE. - * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE. - */ - GIT_CHECKOUT_FORCE = (1u << 1), - - - /** Allow checkout to recreate missing files */ - GIT_CHECKOUT_RECREATE_MISSING = (1u << 2), - - /** Allow checkout to make safe updates even if conflicts are found */ - GIT_CHECKOUT_ALLOW_CONFLICTS = (1u << 4), - - /** Remove untracked files not in index (that are not ignored) */ - GIT_CHECKOUT_REMOVE_UNTRACKED = (1u << 5), - - /** Remove ignored files not in index */ - GIT_CHECKOUT_REMOVE_IGNORED = (1u << 6), - - /** Only update existing files, don't create new ones */ - GIT_CHECKOUT_UPDATE_ONLY = (1u << 7), - - /** - * Normally checkout updates index entries as it goes; this stops that. - * Implies `GIT_CHECKOUT_DONT_WRITE_INDEX`. - */ - GIT_CHECKOUT_DONT_UPDATE_INDEX = (1u << 8), - - /** Don't refresh index/config/etc before doing checkout */ - GIT_CHECKOUT_NO_REFRESH = (1u << 9), - - /** Allow checkout to skip unmerged files */ - GIT_CHECKOUT_SKIP_UNMERGED = (1u << 10), - /** For unmerged files, checkout stage 2 from index */ - GIT_CHECKOUT_USE_OURS = (1u << 11), - /** For unmerged files, checkout stage 3 from index */ - GIT_CHECKOUT_USE_THEIRS = (1u << 12), - - /** Treat pathspec as simple list of exact match file paths */ - GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH = (1u << 13), - - /** Ignore directories in use, they will be left empty */ - GIT_CHECKOUT_SKIP_LOCKED_DIRECTORIES = (1u << 18), - - /** Don't overwrite ignored files that exist in the checkout target */ - GIT_CHECKOUT_DONT_OVERWRITE_IGNORED = (1u << 19), - - /** Write normal merge files for conflicts */ - GIT_CHECKOUT_CONFLICT_STYLE_MERGE = (1u << 20), - - /** Include common ancestor data in diff3 format files for conflicts */ - GIT_CHECKOUT_CONFLICT_STYLE_DIFF3 = (1u << 21), - - /** Don't overwrite existing files or folders */ - GIT_CHECKOUT_DONT_REMOVE_EXISTING = (1u << 22), - - /** Normally checkout writes the index upon completion; this prevents that. */ - GIT_CHECKOUT_DONT_WRITE_INDEX = (1u << 23), - - /** - * Show what would be done by a checkout. Stop after sending - * notifications; don't update the working directory or index. - */ - GIT_CHECKOUT_DRY_RUN = (1u << 24), - - /** Include common ancestor data in zdiff3 format for conflicts */ - GIT_CHECKOUT_CONFLICT_STYLE_ZDIFF3 = (1u << 25), - - /** - * THE FOLLOWING OPTIONS ARE NOT YET IMPLEMENTED - */ - - /** Recursively checkout submodules with same options (NOT IMPLEMENTED) */ - GIT_CHECKOUT_UPDATE_SUBMODULES = (1u << 16), - /** Recursively checkout submodules if HEAD moved in super repo (NOT IMPLEMENTED) */ - GIT_CHECKOUT_UPDATE_SUBMODULES_IF_CHANGED = (1u << 17) - -} git_checkout_strategy_t; - -/** - * Checkout notification flags - * - * Checkout will invoke an options notification callback (`notify_cb`) for - * certain cases - you pick which ones via `notify_flags`: - * - * Returning a non-zero value from this callback will cancel the checkout. - * The non-zero return value will be propagated back and returned by the - * git_checkout_... call. - * - * Notification callbacks are made prior to modifying any files on disk, - * so canceling on any notification will still happen prior to any files - * being modified. - */ -typedef enum { - GIT_CHECKOUT_NOTIFY_NONE = 0, - - /** - * Invokes checkout on conflicting paths. - */ - GIT_CHECKOUT_NOTIFY_CONFLICT = (1u << 0), - - /** - * Notifies about "dirty" files, i.e. those that do not need an update - * but no longer match the baseline. Core git displays these files when - * checkout runs, but won't stop the checkout. - */ - GIT_CHECKOUT_NOTIFY_DIRTY = (1u << 1), - - /** - * Sends notification for any file changed. - */ - GIT_CHECKOUT_NOTIFY_UPDATED = (1u << 2), - - /** - * Notifies about untracked files. - */ - GIT_CHECKOUT_NOTIFY_UNTRACKED = (1u << 3), - - /** - * Notifies about ignored files. - */ - GIT_CHECKOUT_NOTIFY_IGNORED = (1u << 4), - - GIT_CHECKOUT_NOTIFY_ALL = 0x0FFFFu -} git_checkout_notify_t; - -/** Checkout performance-reporting structure */ -typedef struct { - size_t mkdir_calls; - size_t stat_calls; - size_t chmod_calls; -} git_checkout_perfdata; - -/** Checkout notification callback function */ -typedef int GIT_CALLBACK(git_checkout_notify_cb)( - git_checkout_notify_t why, - const char *path, - const git_diff_file *baseline, - const git_diff_file *target, - const git_diff_file *workdir, - void *payload); - -/** Checkout progress notification function */ -typedef void GIT_CALLBACK(git_checkout_progress_cb)( - const char *path, - size_t completed_steps, - size_t total_steps, - void *payload); - -/** Checkout perfdata notification function */ -typedef void GIT_CALLBACK(git_checkout_perfdata_cb)( - const git_checkout_perfdata *perfdata, - void *payload); - -/** - * Checkout options structure - * - * Initialize with `GIT_CHECKOUT_OPTIONS_INIT`. Alternatively, you can - * use `git_checkout_options_init`. - * - */ -typedef struct git_checkout_options { - unsigned int version; /**< The version */ - - unsigned int checkout_strategy; /**< default will be a safe checkout */ - - int disable_filters; /**< don't apply filters like CRLF conversion */ - unsigned int dir_mode; /**< default is 0755 */ - unsigned int file_mode; /**< default is 0644 or 0755 as dictated by blob */ - int file_open_flags; /**< default is O_CREAT | O_TRUNC | O_WRONLY */ - - unsigned int notify_flags; /**< see `git_checkout_notify_t` above */ - - /** - * Optional callback to get notifications on specific file states. - * @see git_checkout_notify_t - */ - git_checkout_notify_cb notify_cb; - - /** Payload passed to notify_cb */ - void *notify_payload; - - /** Optional callback to notify the consumer of checkout progress. */ - git_checkout_progress_cb progress_cb; - - /** Payload passed to progress_cb */ - void *progress_payload; - - /** - * A list of wildmatch patterns or paths. - * - * By default, all paths are processed. If you pass an array of wildmatch - * patterns, those will be used to filter which paths should be taken into - * account. - * - * Use GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH to treat as a simple list. - */ - git_strarray paths; - - /** - * The expected content of the working directory; defaults to HEAD. - * - * If the working directory does not match this baseline information, - * that will produce a checkout conflict. - */ - git_tree *baseline; - - /** - * Like `baseline` above, though expressed as an index. This - * option overrides `baseline`. - */ - git_index *baseline_index; - - const char *target_directory; /**< alternative checkout path to workdir */ - - const char *ancestor_label; /**< the name of the common ancestor side of conflicts */ - const char *our_label; /**< the name of the "our" side of conflicts */ - const char *their_label; /**< the name of the "their" side of conflicts */ - - /** Optional callback to notify the consumer of performance data. */ - git_checkout_perfdata_cb perfdata_cb; - - /** Payload passed to perfdata_cb */ - void *perfdata_payload; -} git_checkout_options; - -#define GIT_CHECKOUT_OPTIONS_VERSION 1 -#define GIT_CHECKOUT_OPTIONS_INIT {GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE} - -/** - * Initialize git_checkout_options structure - * - * Initializes a `git_checkout_options` with default values. Equivalent to creating - * an instance with GIT_CHECKOUT_OPTIONS_INIT. - * - * @param opts The `git_checkout_options` struct to initialize. - * @param version The struct version; pass `GIT_CHECKOUT_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_checkout_options_init( - git_checkout_options *opts, - unsigned int version); - -/** - * Updates files in the index and the working tree to match the content of - * the commit pointed at by HEAD. - * - * Note that this is _not_ the correct mechanism used to switch branches; - * do not change your `HEAD` and then call this method, that would leave - * you with checkout conflicts since your working directory would then - * appear to be dirty. Instead, checkout the target of the branch and - * then update `HEAD` using `git_repository_set_head` to point to the - * branch you checked out. - * - * @param repo repository to check out (must be non-bare) - * @param opts specifies checkout options (may be NULL) - * @return 0 on success, GIT_EUNBORNBRANCH if HEAD points to a non - * existing branch, non-zero value returned by `notify_cb`, or - * other error code < 0 (use git_error_last for error details) - */ -GIT_EXTERN(int) git_checkout_head( - git_repository *repo, - const git_checkout_options *opts); - -/** - * Updates files in the working tree to match the content of the index. - * - * @param repo repository into which to check out (must be non-bare) - * @param index index to be checked out (or NULL to use repository index) - * @param opts specifies checkout options (may be NULL) - * @return 0 on success, non-zero return value from `notify_cb`, or error - * code < 0 (use git_error_last for error details) - */ -GIT_EXTERN(int) git_checkout_index( - git_repository *repo, - git_index *index, - const git_checkout_options *opts); - -/** - * Updates files in the index and working tree to match the content of the - * tree pointed at by the treeish. - * - * @param repo repository to check out (must be non-bare) - * @param treeish a commit, tag or tree which content will be used to update - * the working directory (or NULL to use HEAD) - * @param opts specifies checkout options (may be NULL) - * @return 0 on success, non-zero return value from `notify_cb`, or error - * code < 0 (use git_error_last for error details) - */ -GIT_EXTERN(int) git_checkout_tree( - git_repository *repo, - const git_object *treeish, - const git_checkout_options *opts); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_checkout_h__ +#define INCLUDE_git_checkout_h__ + +#include "common.h" +#include "types.h" +#include "diff.h" + +/** + * @file git2/checkout.h + * @brief Git checkout routines + * @defgroup git_checkout Git checkout routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Checkout behavior flags + * + * In libgit2, checkout is used to update the working directory and index + * to match a target tree. Unlike git checkout, it does not move the HEAD + * commit for you - use `git_repository_set_head` or the like to do that. + * + * Checkout looks at (up to) four things: the "target" tree you want to + * check out, the "baseline" tree of what was checked out previously, the + * working directory for actual files, and the index for staged changes. + * + * You give checkout one of three strategies for update: + * + * - `GIT_CHECKOUT_NONE` is a dry-run strategy that checks for conflicts, + * etc., but doesn't make any actual changes. + * + * - `GIT_CHECKOUT_FORCE` is at the opposite extreme, taking any action to + * make the working directory match the target (including potentially + * discarding modified files). + * + * - `GIT_CHECKOUT_SAFE` is between these two options, it will only make + * modifications that will not lose changes. + * + * | target == baseline | target != baseline | + * ---------------------|-----------------------|----------------------| + * workdir == baseline | no action | create, update, or | + * | | delete file | + * ---------------------|-----------------------|----------------------| + * workdir exists and | no action | conflict (notify | + * is != baseline | notify dirty MODIFIED | and cancel checkout) | + * ---------------------|-----------------------|----------------------| + * workdir missing, | notify dirty DELETED | create file | + * baseline present | | | + * ---------------------|-----------------------|----------------------| + * + * To emulate `git checkout`, use `GIT_CHECKOUT_SAFE` with a checkout + * notification callback (see below) that displays information about dirty + * files. The default behavior will cancel checkout on conflicts. + * + * To emulate `git checkout-index`, use `GIT_CHECKOUT_SAFE` with a + * notification callback that cancels the operation if a dirty-but-existing + * file is found in the working directory. This core git command isn't + * quite "force" but is sensitive about some types of changes. + * + * To emulate `git checkout -f`, use `GIT_CHECKOUT_FORCE`. + * + * + * There are some additional flags to modify the behavior of checkout: + * + * - GIT_CHECKOUT_ALLOW_CONFLICTS makes SAFE mode apply safe file updates + * even if there are conflicts (instead of cancelling the checkout). + * + * - GIT_CHECKOUT_REMOVE_UNTRACKED means remove untracked files (i.e. not + * in target, baseline, or index, and not ignored) from the working dir. + * + * - GIT_CHECKOUT_REMOVE_IGNORED means remove ignored files (that are also + * untracked) from the working directory as well. + * + * - GIT_CHECKOUT_UPDATE_ONLY means to only update the content of files that + * already exist. Files will not be created nor deleted. This just skips + * applying adds, deletes, and typechanges. + * + * - GIT_CHECKOUT_DONT_UPDATE_INDEX prevents checkout from writing the + * updated files' information to the index. + * + * - Normally, checkout will reload the index and git attributes from disk + * before any operations. GIT_CHECKOUT_NO_REFRESH prevents this reload. + * + * - Unmerged index entries are conflicts. GIT_CHECKOUT_SKIP_UNMERGED skips + * files with unmerged index entries instead. GIT_CHECKOUT_USE_OURS and + * GIT_CHECKOUT_USE_THEIRS to proceed with the checkout using either the + * stage 2 ("ours") or stage 3 ("theirs") version of files in the index. + * + * - GIT_CHECKOUT_DONT_OVERWRITE_IGNORED prevents ignored files from being + * overwritten. Normally, files that are ignored in the working directory + * are not considered "precious" and may be overwritten if the checkout + * target contains that file. + * + * - GIT_CHECKOUT_DONT_REMOVE_EXISTING prevents checkout from removing + * files or folders that fold to the same name on case insensitive + * filesystems. This can cause files to retain their existing names + * and write through existing symbolic links. + */ +typedef enum { + GIT_CHECKOUT_NONE = 0, /**< default is a dry run, no actual updates */ + + /** + * Allow safe updates that cannot overwrite uncommitted data. + * If the uncommitted changes don't conflict with the checked out files, + * the checkout will still proceed, leaving the changes intact. + * + * Mutually exclusive with GIT_CHECKOUT_FORCE. + * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE. + */ + GIT_CHECKOUT_SAFE = (1u << 0), + + /** + * Allow all updates to force working directory to look like index. + * + * Mutually exclusive with GIT_CHECKOUT_SAFE. + * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE. + */ + GIT_CHECKOUT_FORCE = (1u << 1), + + + /** Allow checkout to recreate missing files */ + GIT_CHECKOUT_RECREATE_MISSING = (1u << 2), + + /** Allow checkout to make safe updates even if conflicts are found */ + GIT_CHECKOUT_ALLOW_CONFLICTS = (1u << 4), + + /** Remove untracked files not in index (that are not ignored) */ + GIT_CHECKOUT_REMOVE_UNTRACKED = (1u << 5), + + /** Remove ignored files not in index */ + GIT_CHECKOUT_REMOVE_IGNORED = (1u << 6), + + /** Only update existing files, don't create new ones */ + GIT_CHECKOUT_UPDATE_ONLY = (1u << 7), + + /** + * Normally checkout updates index entries as it goes; this stops that. + * Implies `GIT_CHECKOUT_DONT_WRITE_INDEX`. + */ + GIT_CHECKOUT_DONT_UPDATE_INDEX = (1u << 8), + + /** Don't refresh index/config/etc before doing checkout */ + GIT_CHECKOUT_NO_REFRESH = (1u << 9), + + /** Allow checkout to skip unmerged files */ + GIT_CHECKOUT_SKIP_UNMERGED = (1u << 10), + /** For unmerged files, checkout stage 2 from index */ + GIT_CHECKOUT_USE_OURS = (1u << 11), + /** For unmerged files, checkout stage 3 from index */ + GIT_CHECKOUT_USE_THEIRS = (1u << 12), + + /** Treat pathspec as simple list of exact match file paths */ + GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH = (1u << 13), + + /** Ignore directories in use, they will be left empty */ + GIT_CHECKOUT_SKIP_LOCKED_DIRECTORIES = (1u << 18), + + /** Don't overwrite ignored files that exist in the checkout target */ + GIT_CHECKOUT_DONT_OVERWRITE_IGNORED = (1u << 19), + + /** Write normal merge files for conflicts */ + GIT_CHECKOUT_CONFLICT_STYLE_MERGE = (1u << 20), + + /** Include common ancestor data in diff3 format files for conflicts */ + GIT_CHECKOUT_CONFLICT_STYLE_DIFF3 = (1u << 21), + + /** Don't overwrite existing files or folders */ + GIT_CHECKOUT_DONT_REMOVE_EXISTING = (1u << 22), + + /** Normally checkout writes the index upon completion; this prevents that. */ + GIT_CHECKOUT_DONT_WRITE_INDEX = (1u << 23), + + /** + * Show what would be done by a checkout. Stop after sending + * notifications; don't update the working directory or index. + */ + GIT_CHECKOUT_DRY_RUN = (1u << 24), + + /** Include common ancestor data in zdiff3 format for conflicts */ + GIT_CHECKOUT_CONFLICT_STYLE_ZDIFF3 = (1u << 25), + + /** + * THE FOLLOWING OPTIONS ARE NOT YET IMPLEMENTED + */ + + /** Recursively checkout submodules with same options (NOT IMPLEMENTED) */ + GIT_CHECKOUT_UPDATE_SUBMODULES = (1u << 16), + /** Recursively checkout submodules if HEAD moved in super repo (NOT IMPLEMENTED) */ + GIT_CHECKOUT_UPDATE_SUBMODULES_IF_CHANGED = (1u << 17) + +} git_checkout_strategy_t; + +/** + * Checkout notification flags + * + * Checkout will invoke an options notification callback (`notify_cb`) for + * certain cases - you pick which ones via `notify_flags`: + * + * Returning a non-zero value from this callback will cancel the checkout. + * The non-zero return value will be propagated back and returned by the + * git_checkout_... call. + * + * Notification callbacks are made prior to modifying any files on disk, + * so canceling on any notification will still happen prior to any files + * being modified. + */ +typedef enum { + GIT_CHECKOUT_NOTIFY_NONE = 0, + + /** + * Invokes checkout on conflicting paths. + */ + GIT_CHECKOUT_NOTIFY_CONFLICT = (1u << 0), + + /** + * Notifies about "dirty" files, i.e. those that do not need an update + * but no longer match the baseline. Core git displays these files when + * checkout runs, but won't stop the checkout. + */ + GIT_CHECKOUT_NOTIFY_DIRTY = (1u << 1), + + /** + * Sends notification for any file changed. + */ + GIT_CHECKOUT_NOTIFY_UPDATED = (1u << 2), + + /** + * Notifies about untracked files. + */ + GIT_CHECKOUT_NOTIFY_UNTRACKED = (1u << 3), + + /** + * Notifies about ignored files. + */ + GIT_CHECKOUT_NOTIFY_IGNORED = (1u << 4), + + GIT_CHECKOUT_NOTIFY_ALL = 0x0FFFFu +} git_checkout_notify_t; + +/** Checkout performance-reporting structure */ +typedef struct { + size_t mkdir_calls; + size_t stat_calls; + size_t chmod_calls; +} git_checkout_perfdata; + +/** Checkout notification callback function */ +typedef int GIT_CALLBACK(git_checkout_notify_cb)( + git_checkout_notify_t why, + const char *path, + const git_diff_file *baseline, + const git_diff_file *target, + const git_diff_file *workdir, + void *payload); + +/** Checkout progress notification function */ +typedef void GIT_CALLBACK(git_checkout_progress_cb)( + const char *path, + size_t completed_steps, + size_t total_steps, + void *payload); + +/** Checkout perfdata notification function */ +typedef void GIT_CALLBACK(git_checkout_perfdata_cb)( + const git_checkout_perfdata *perfdata, + void *payload); + +/** + * Checkout options structure + * + * Initialize with `GIT_CHECKOUT_OPTIONS_INIT`. Alternatively, you can + * use `git_checkout_options_init`. + * + */ +typedef struct git_checkout_options { + unsigned int version; /**< The version */ + + unsigned int checkout_strategy; /**< default will be a safe checkout */ + + int disable_filters; /**< don't apply filters like CRLF conversion */ + unsigned int dir_mode; /**< default is 0755 */ + unsigned int file_mode; /**< default is 0644 or 0755 as dictated by blob */ + int file_open_flags; /**< default is O_CREAT | O_TRUNC | O_WRONLY */ + + unsigned int notify_flags; /**< see `git_checkout_notify_t` above */ + + /** + * Optional callback to get notifications on specific file states. + * @see git_checkout_notify_t + */ + git_checkout_notify_cb notify_cb; + + /** Payload passed to notify_cb */ + void *notify_payload; + + /** Optional callback to notify the consumer of checkout progress. */ + git_checkout_progress_cb progress_cb; + + /** Payload passed to progress_cb */ + void *progress_payload; + + /** + * A list of wildmatch patterns or paths. + * + * By default, all paths are processed. If you pass an array of wildmatch + * patterns, those will be used to filter which paths should be taken into + * account. + * + * Use GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH to treat as a simple list. + */ + git_strarray paths; + + /** + * The expected content of the working directory; defaults to HEAD. + * + * If the working directory does not match this baseline information, + * that will produce a checkout conflict. + */ + git_tree *baseline; + + /** + * Like `baseline` above, though expressed as an index. This + * option overrides `baseline`. + */ + git_index *baseline_index; + + const char *target_directory; /**< alternative checkout path to workdir */ + + const char *ancestor_label; /**< the name of the common ancestor side of conflicts */ + const char *our_label; /**< the name of the "our" side of conflicts */ + const char *their_label; /**< the name of the "their" side of conflicts */ + + /** Optional callback to notify the consumer of performance data. */ + git_checkout_perfdata_cb perfdata_cb; + + /** Payload passed to perfdata_cb */ + void *perfdata_payload; +} git_checkout_options; + +#define GIT_CHECKOUT_OPTIONS_VERSION 1 +#define GIT_CHECKOUT_OPTIONS_INIT {GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE} + +/** + * Initialize git_checkout_options structure + * + * Initializes a `git_checkout_options` with default values. Equivalent to creating + * an instance with GIT_CHECKOUT_OPTIONS_INIT. + * + * @param opts The `git_checkout_options` struct to initialize. + * @param version The struct version; pass `GIT_CHECKOUT_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_checkout_options_init( + git_checkout_options *opts, + unsigned int version); + +/** + * Updates files in the index and the working tree to match the content of + * the commit pointed at by HEAD. + * + * Note that this is _not_ the correct mechanism used to switch branches; + * do not change your `HEAD` and then call this method, that would leave + * you with checkout conflicts since your working directory would then + * appear to be dirty. Instead, checkout the target of the branch and + * then update `HEAD` using `git_repository_set_head` to point to the + * branch you checked out. + * + * @param repo repository to check out (must be non-bare) + * @param opts specifies checkout options (may be NULL) + * @return 0 on success, GIT_EUNBORNBRANCH if HEAD points to a non + * existing branch, non-zero value returned by `notify_cb`, or + * other error code < 0 (use git_error_last for error details) + */ +GIT_EXTERN(int) git_checkout_head( + git_repository *repo, + const git_checkout_options *opts); + +/** + * Updates files in the working tree to match the content of the index. + * + * @param repo repository into which to check out (must be non-bare) + * @param index index to be checked out (or NULL to use repository index) + * @param opts specifies checkout options (may be NULL) + * @return 0 on success, non-zero return value from `notify_cb`, or error + * code < 0 (use git_error_last for error details) + */ +GIT_EXTERN(int) git_checkout_index( + git_repository *repo, + git_index *index, + const git_checkout_options *opts); + +/** + * Updates files in the index and working tree to match the content of the + * tree pointed at by the treeish. + * + * @param repo repository to check out (must be non-bare) + * @param treeish a commit, tag or tree which content will be used to update + * the working directory (or NULL to use HEAD) + * @param opts specifies checkout options (may be NULL) + * @return 0 on success, non-zero return value from `notify_cb`, or error + * code < 0 (use git_error_last for error details) + */ +GIT_EXTERN(int) git_checkout_tree( + git_repository *repo, + const git_object *treeish, + const git_checkout_options *opts); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/cherrypick.h b/3rdparty/libgit2/include/git2/cherrypick.h index 0e6a252..3ebb3f9 100644 --- a/3rdparty/libgit2/include/git2/cherrypick.h +++ b/3rdparty/libgit2/include/git2/cherrypick.h @@ -1,92 +1,92 @@ -/* - * 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_cherrypick_h__ -#define INCLUDE_git_cherrypick_h__ - -#include "common.h" -#include "types.h" -#include "merge.h" - -/** - * @file git2/cherrypick.h - * @brief Git cherry-pick routines - * @defgroup git_cherrypick Git cherry-pick routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Cherry-pick options - */ -typedef struct { - unsigned int version; - - /** For merge commits, the "mainline" is treated as the parent. */ - unsigned int mainline; - - git_merge_options merge_opts; /**< Options for the merging */ - git_checkout_options checkout_opts; /**< Options for the checkout */ -} git_cherrypick_options; - -#define GIT_CHERRYPICK_OPTIONS_VERSION 1 -#define GIT_CHERRYPICK_OPTIONS_INIT {GIT_CHERRYPICK_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT} - -/** - * Initialize git_cherrypick_options structure - * - * Initializes a `git_cherrypick_options` with default values. Equivalent to creating - * an instance with GIT_CHERRYPICK_OPTIONS_INIT. - * - * @param opts The `git_cherrypick_options` struct to initialize. - * @param version The struct version; pass `GIT_CHERRYPICK_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_cherrypick_options_init( - git_cherrypick_options *opts, - unsigned int version); - -/** - * Cherry-picks the given commit against the given "our" commit, producing an - * index that reflects the result of the cherry-pick. - * - * The returned index must be freed explicitly with `git_index_free`. - * - * @param out pointer to store the index result in - * @param repo the repository that contains the given commits - * @param cherrypick_commit the commit to cherry-pick - * @param our_commit the commit to cherry-pick against (eg, HEAD) - * @param mainline the parent of the `cherrypick_commit`, if it is a merge - * @param merge_options the merge options (or null for defaults) - * @return zero on success, -1 on failure. - */ -GIT_EXTERN(int) git_cherrypick_commit( - git_index **out, - git_repository *repo, - git_commit *cherrypick_commit, - git_commit *our_commit, - unsigned int mainline, - const git_merge_options *merge_options); - -/** - * Cherry-pick the given commit, producing changes in the index and working directory. - * - * @param repo the repository to cherry-pick - * @param commit the commit to cherry-pick - * @param cherrypick_options the cherry-pick options (or null for defaults) - * @return zero on success, -1 on failure. - */ -GIT_EXTERN(int) git_cherrypick( - git_repository *repo, - git_commit *commit, - const git_cherrypick_options *cherrypick_options); - -/** @} */ -GIT_END_DECL - -#endif - +/* + * 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_cherrypick_h__ +#define INCLUDE_git_cherrypick_h__ + +#include "common.h" +#include "types.h" +#include "merge.h" + +/** + * @file git2/cherrypick.h + * @brief Git cherry-pick routines + * @defgroup git_cherrypick Git cherry-pick routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Cherry-pick options + */ +typedef struct { + unsigned int version; + + /** For merge commits, the "mainline" is treated as the parent. */ + unsigned int mainline; + + git_merge_options merge_opts; /**< Options for the merging */ + git_checkout_options checkout_opts; /**< Options for the checkout */ +} git_cherrypick_options; + +#define GIT_CHERRYPICK_OPTIONS_VERSION 1 +#define GIT_CHERRYPICK_OPTIONS_INIT {GIT_CHERRYPICK_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT} + +/** + * Initialize git_cherrypick_options structure + * + * Initializes a `git_cherrypick_options` with default values. Equivalent to creating + * an instance with GIT_CHERRYPICK_OPTIONS_INIT. + * + * @param opts The `git_cherrypick_options` struct to initialize. + * @param version The struct version; pass `GIT_CHERRYPICK_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_cherrypick_options_init( + git_cherrypick_options *opts, + unsigned int version); + +/** + * Cherry-picks the given commit against the given "our" commit, producing an + * index that reflects the result of the cherry-pick. + * + * The returned index must be freed explicitly with `git_index_free`. + * + * @param out pointer to store the index result in + * @param repo the repository that contains the given commits + * @param cherrypick_commit the commit to cherry-pick + * @param our_commit the commit to cherry-pick against (eg, HEAD) + * @param mainline the parent of the `cherrypick_commit`, if it is a merge + * @param merge_options the merge options (or null for defaults) + * @return zero on success, -1 on failure. + */ +GIT_EXTERN(int) git_cherrypick_commit( + git_index **out, + git_repository *repo, + git_commit *cherrypick_commit, + git_commit *our_commit, + unsigned int mainline, + const git_merge_options *merge_options); + +/** + * Cherry-pick the given commit, producing changes in the index and working directory. + * + * @param repo the repository to cherry-pick + * @param commit the commit to cherry-pick + * @param cherrypick_options the cherry-pick options (or null for defaults) + * @return zero on success, -1 on failure. + */ +GIT_EXTERN(int) git_cherrypick( + git_repository *repo, + git_commit *commit, + const git_cherrypick_options *cherrypick_options); + +/** @} */ +GIT_END_DECL + +#endif + diff --git a/3rdparty/libgit2/include/git2/clone.h b/3rdparty/libgit2/include/git2/clone.h index 3481f25..c32a59e 100644 --- a/3rdparty/libgit2/include/git2/clone.h +++ b/3rdparty/libgit2/include/git2/clone.h @@ -1,209 +1,209 @@ -/* - * 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_clone_h__ -#define INCLUDE_git_clone_h__ - -#include "common.h" -#include "types.h" -#include "indexer.h" -#include "checkout.h" -#include "remote.h" -#include "transport.h" - - -/** - * @file git2/clone.h - * @brief Git cloning routines - * @defgroup git_clone Git cloning routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Options for bypassing the git-aware transport on clone. Bypassing - * it means that instead of a fetch, libgit2 will copy the object - * database directory instead of figuring out what it needs, which is - * faster. If possible, it will hardlink the files to save space. - */ -typedef enum { - /** - * Auto-detect (default), libgit2 will bypass the git-aware - * transport for local paths, but use a normal fetch for - * `file://` urls. - */ - GIT_CLONE_LOCAL_AUTO, - /** - * Bypass the git-aware transport even for a `file://` url. - */ - GIT_CLONE_LOCAL, - /** - * Do no bypass the git-aware transport - */ - GIT_CLONE_NO_LOCAL, - /** - * Bypass the git-aware transport, but do not try to use - * hardlinks. - */ - GIT_CLONE_LOCAL_NO_LINKS -} git_clone_local_t; - -/** - * The signature of a function matching git_remote_create, with an additional - * void* as a callback payload. - * - * Callers of git_clone may provide a function matching this signature to override - * the remote creation and customization process during a clone operation. - * - * @param out the resulting remote - * @param repo the repository in which to create the remote - * @param name the remote's name - * @param url the remote's url - * @param payload an opaque payload - * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code - */ -typedef int GIT_CALLBACK(git_remote_create_cb)( - git_remote **out, - git_repository *repo, - const char *name, - const char *url, - void *payload); - -/** - * The signature of a function matching git_repository_init, with an - * additional void * as callback payload. - * - * Callers of git_clone my provide a function matching this signature - * to override the repository creation and customization process - * during a clone operation. - * - * @param out the resulting repository - * @param path path in which to create the repository - * @param bare whether the repository is bare. This is the value from the clone options - * @param payload payload specified by the options - * @return 0, or a negative value to indicate error - */ -typedef int GIT_CALLBACK(git_repository_create_cb)( - git_repository **out, - const char *path, - int bare, - void *payload); - -/** - * Clone options structure - * - * Initialize with `GIT_CLONE_OPTIONS_INIT`. Alternatively, you can - * use `git_clone_options_init`. - * - */ -typedef struct git_clone_options { - unsigned int version; - - /** - * These options are passed to the checkout step. To disable - * checkout, set the `checkout_strategy` to - * `GIT_CHECKOUT_NONE`. - */ - git_checkout_options checkout_opts; - - /** - * Options which control the fetch, including callbacks. - * - * The callbacks are used for reporting fetch progress, and for acquiring - * credentials in the event they are needed. - */ - git_fetch_options fetch_opts; - - /** - * Set to zero (false) to create a standard repo, or non-zero - * for a bare repo - */ - int bare; - - /** - * Whether to use a fetch or copy the object database. - */ - git_clone_local_t local; - - /** - * The name of the branch to checkout. NULL means use the - * remote's default branch. - */ - const char *checkout_branch; - - /** - * A callback used to create the new repository into which to - * clone. If NULL, the 'bare' field will be used to determine - * whether to create a bare repository. - */ - git_repository_create_cb repository_cb; - - /** - * An opaque payload to pass to the git_repository creation callback. - * This parameter is ignored unless repository_cb is non-NULL. - */ - void *repository_cb_payload; - - /** - * A callback used to create the git_remote, prior to its being - * used to perform the clone operation. See the documentation for - * git_remote_create_cb for details. This parameter may be NULL, - * indicating that git_clone should provide default behavior. - */ - git_remote_create_cb remote_cb; - - /** - * An opaque payload to pass to the git_remote creation callback. - * This parameter is ignored unless remote_cb is non-NULL. - */ - void *remote_cb_payload; -} git_clone_options; - -#define GIT_CLONE_OPTIONS_VERSION 1 -#define GIT_CLONE_OPTIONS_INIT { GIT_CLONE_OPTIONS_VERSION, \ - { GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE }, \ - GIT_FETCH_OPTIONS_INIT } - -/** - * Initialize git_clone_options structure - * - * Initializes a `git_clone_options` with default values. Equivalent to creating - * an instance with GIT_CLONE_OPTIONS_INIT. - * - * @param opts The `git_clone_options` struct to initialize. - * @param version The struct version; pass `GIT_CLONE_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_clone_options_init( - git_clone_options *opts, - unsigned int version); - -/** - * Clone a remote repository. - * - * By default this creates its repository and initial remote to match - * git's defaults. You can use the options in the callback to - * customize how these are created. - * - * @param out pointer that will receive the resulting repository object - * @param url the remote repository to clone - * @param local_path local directory to clone to - * @param options configuration options for the clone. If NULL, the - * function works as though GIT_OPTIONS_INIT were passed. - * @return 0 on success, any non-zero return value from a callback - * function, or a negative value to indicate an error (use - * `git_error_last` for a detailed error message) - */ -GIT_EXTERN(int) git_clone( - git_repository **out, - const char *url, - const char *local_path, - const git_clone_options *options); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_clone_h__ +#define INCLUDE_git_clone_h__ + +#include "common.h" +#include "types.h" +#include "indexer.h" +#include "checkout.h" +#include "remote.h" +#include "transport.h" + + +/** + * @file git2/clone.h + * @brief Git cloning routines + * @defgroup git_clone Git cloning routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Options for bypassing the git-aware transport on clone. Bypassing + * it means that instead of a fetch, libgit2 will copy the object + * database directory instead of figuring out what it needs, which is + * faster. If possible, it will hardlink the files to save space. + */ +typedef enum { + /** + * Auto-detect (default), libgit2 will bypass the git-aware + * transport for local paths, but use a normal fetch for + * `file://` urls. + */ + GIT_CLONE_LOCAL_AUTO, + /** + * Bypass the git-aware transport even for a `file://` url. + */ + GIT_CLONE_LOCAL, + /** + * Do no bypass the git-aware transport + */ + GIT_CLONE_NO_LOCAL, + /** + * Bypass the git-aware transport, but do not try to use + * hardlinks. + */ + GIT_CLONE_LOCAL_NO_LINKS +} git_clone_local_t; + +/** + * The signature of a function matching git_remote_create, with an additional + * void* as a callback payload. + * + * Callers of git_clone may provide a function matching this signature to override + * the remote creation and customization process during a clone operation. + * + * @param out the resulting remote + * @param repo the repository in which to create the remote + * @param name the remote's name + * @param url the remote's url + * @param payload an opaque payload + * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code + */ +typedef int GIT_CALLBACK(git_remote_create_cb)( + git_remote **out, + git_repository *repo, + const char *name, + const char *url, + void *payload); + +/** + * The signature of a function matching git_repository_init, with an + * additional void * as callback payload. + * + * Callers of git_clone my provide a function matching this signature + * to override the repository creation and customization process + * during a clone operation. + * + * @param out the resulting repository + * @param path path in which to create the repository + * @param bare whether the repository is bare. This is the value from the clone options + * @param payload payload specified by the options + * @return 0, or a negative value to indicate error + */ +typedef int GIT_CALLBACK(git_repository_create_cb)( + git_repository **out, + const char *path, + int bare, + void *payload); + +/** + * Clone options structure + * + * Initialize with `GIT_CLONE_OPTIONS_INIT`. Alternatively, you can + * use `git_clone_options_init`. + * + */ +typedef struct git_clone_options { + unsigned int version; + + /** + * These options are passed to the checkout step. To disable + * checkout, set the `checkout_strategy` to + * `GIT_CHECKOUT_NONE`. + */ + git_checkout_options checkout_opts; + + /** + * Options which control the fetch, including callbacks. + * + * The callbacks are used for reporting fetch progress, and for acquiring + * credentials in the event they are needed. + */ + git_fetch_options fetch_opts; + + /** + * Set to zero (false) to create a standard repo, or non-zero + * for a bare repo + */ + int bare; + + /** + * Whether to use a fetch or copy the object database. + */ + git_clone_local_t local; + + /** + * The name of the branch to checkout. NULL means use the + * remote's default branch. + */ + const char *checkout_branch; + + /** + * A callback used to create the new repository into which to + * clone. If NULL, the 'bare' field will be used to determine + * whether to create a bare repository. + */ + git_repository_create_cb repository_cb; + + /** + * An opaque payload to pass to the git_repository creation callback. + * This parameter is ignored unless repository_cb is non-NULL. + */ + void *repository_cb_payload; + + /** + * A callback used to create the git_remote, prior to its being + * used to perform the clone operation. See the documentation for + * git_remote_create_cb for details. This parameter may be NULL, + * indicating that git_clone should provide default behavior. + */ + git_remote_create_cb remote_cb; + + /** + * An opaque payload to pass to the git_remote creation callback. + * This parameter is ignored unless remote_cb is non-NULL. + */ + void *remote_cb_payload; +} git_clone_options; + +#define GIT_CLONE_OPTIONS_VERSION 1 +#define GIT_CLONE_OPTIONS_INIT { GIT_CLONE_OPTIONS_VERSION, \ + { GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE }, \ + GIT_FETCH_OPTIONS_INIT } + +/** + * Initialize git_clone_options structure + * + * Initializes a `git_clone_options` with default values. Equivalent to creating + * an instance with GIT_CLONE_OPTIONS_INIT. + * + * @param opts The `git_clone_options` struct to initialize. + * @param version The struct version; pass `GIT_CLONE_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_clone_options_init( + git_clone_options *opts, + unsigned int version); + +/** + * Clone a remote repository. + * + * By default this creates its repository and initial remote to match + * git's defaults. You can use the options in the callback to + * customize how these are created. + * + * @param out pointer that will receive the resulting repository object + * @param url the remote repository to clone + * @param local_path local directory to clone to + * @param options configuration options for the clone. If NULL, the + * function works as though GIT_OPTIONS_INIT were passed. + * @return 0 on success, any non-zero return value from a callback + * function, or a negative value to indicate an error (use + * `git_error_last` for a detailed error message) + */ +GIT_EXTERN(int) git_clone( + git_repository **out, + const char *url, + const char *local_path, + const git_clone_options *options); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/commit.h b/3rdparty/libgit2/include/git2/commit.h index ef38c66..bef1050 100644 --- a/3rdparty/libgit2/include/git2/commit.h +++ b/3rdparty/libgit2/include/git2/commit.h @@ -1,607 +1,607 @@ -/* - * 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_commit_h__ -#define INCLUDE_git_commit_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "object.h" - -/** - * @file git2/commit.h - * @brief Git commit parsing, formatting routines - * @defgroup git_commit Git commit parsing, formatting routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Lookup a commit object from a repository. - * - * The returned object should be released with `git_commit_free` when no - * longer needed. - * - * @param commit pointer to the looked up commit - * @param repo the repo to use when locating the commit. - * @param id identity of the commit to locate. If the object is - * an annotated tag it will be peeled back to the commit. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_lookup( - git_commit **commit, git_repository *repo, const git_oid *id); - -/** - * Lookup a commit object from a repository, given a prefix of its - * identifier (short id). - * - * The returned object should be released with `git_commit_free` when no - * longer needed. - * - * @see git_object_lookup_prefix - * - * @param commit pointer to the looked up commit - * @param repo the repo to use when locating the commit. - * @param id identity of the commit to locate. If the object is - * an annotated tag it will be peeled back to the commit. - * @param len the length of the short identifier - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_lookup_prefix( - git_commit **commit, git_repository *repo, const git_oid *id, size_t len); - -/** - * Close an open commit - * - * This is a wrapper around git_object_free() - * - * IMPORTANT: - * It *is* necessary to call this method when you stop - * using a commit. Failure to do so will cause a memory leak. - * - * @param commit the commit to close - */ - -GIT_EXTERN(void) git_commit_free(git_commit *commit); - -/** - * Get the id of a commit. - * - * @param commit a previously loaded commit. - * @return object identity for the commit. - */ -GIT_EXTERN(const git_oid *) git_commit_id(const git_commit *commit); - -/** - * Get the repository that contains the commit. - * - * @param commit A previously loaded commit. - * @return Repository that contains this commit. - */ -GIT_EXTERN(git_repository *) git_commit_owner(const git_commit *commit); - -/** - * Get the encoding for the message of a commit, - * as a string representing a standard encoding name. - * - * The encoding may be NULL if the `encoding` header - * in the commit is missing; in that case UTF-8 is assumed. - * - * @param commit a previously loaded commit. - * @return NULL, or the encoding - */ -GIT_EXTERN(const char *) git_commit_message_encoding(const git_commit *commit); - -/** - * Get the full message of a commit. - * - * The returned message will be slightly prettified by removing any - * potential leading newlines. - * - * @param commit a previously loaded commit. - * @return the message of a commit - */ -GIT_EXTERN(const char *) git_commit_message(const git_commit *commit); - -/** - * Get the full raw message of a commit. - * - * @param commit a previously loaded commit. - * @return the raw message of a commit - */ -GIT_EXTERN(const char *) git_commit_message_raw(const git_commit *commit); - -/** - * Get the short "summary" of the git commit message. - * - * The returned message is the summary of the commit, comprising the - * first paragraph of the message with whitespace trimmed and squashed. - * - * @param commit a previously loaded commit. - * @return the summary of a commit or NULL on error - */ -GIT_EXTERN(const char *) git_commit_summary(git_commit *commit); - -/** - * Get the long "body" of the git commit message. - * - * The returned message is the body of the commit, comprising - * everything but the first paragraph of the message. Leading and - * trailing whitespaces are trimmed. - * - * @param commit a previously loaded commit. - * @return the body of a commit or NULL when no the message only - * consists of a summary - */ -GIT_EXTERN(const char *) git_commit_body(git_commit *commit); - -/** - * Get the commit time (i.e. committer time) of a commit. - * - * @param commit a previously loaded commit. - * @return the time of a commit - */ -GIT_EXTERN(git_time_t) git_commit_time(const git_commit *commit); - -/** - * Get the commit timezone offset (i.e. committer's preferred timezone) of a commit. - * - * @param commit a previously loaded commit. - * @return positive or negative timezone offset, in minutes from UTC - */ -GIT_EXTERN(int) git_commit_time_offset(const git_commit *commit); - -/** - * Get the committer of a commit. - * - * @param commit a previously loaded commit. - * @return the committer of a commit - */ -GIT_EXTERN(const git_signature *) git_commit_committer(const git_commit *commit); - -/** - * Get the author of a commit. - * - * @param commit a previously loaded commit. - * @return the author of a commit - */ -GIT_EXTERN(const git_signature *) git_commit_author(const git_commit *commit); - -/** - * Get the committer of a commit, using the mailmap to map names and email - * addresses to canonical real names and email addresses. - * - * Call `git_signature_free` to free the signature. - * - * @param out a pointer to store the resolved signature. - * @param commit a previously loaded commit. - * @param mailmap the mailmap to resolve with. (may be NULL) - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_committer_with_mailmap( - git_signature **out, const git_commit *commit, const git_mailmap *mailmap); - -/** - * Get the author of a commit, using the mailmap to map names and email - * addresses to canonical real names and email addresses. - * - * Call `git_signature_free` to free the signature. - * - * @param out a pointer to store the resolved signature. - * @param commit a previously loaded commit. - * @param mailmap the mailmap to resolve with. (may be NULL) - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_author_with_mailmap( - git_signature **out, const git_commit *commit, const git_mailmap *mailmap); - -/** - * Get the full raw text of the commit header. - * - * @param commit a previously loaded commit - * @return the header text of the commit - */ -GIT_EXTERN(const char *) git_commit_raw_header(const git_commit *commit); - -/** - * Get the tree pointed to by a commit. - * - * @param tree_out pointer where to store the tree object - * @param commit a previously loaded commit. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, const git_commit *commit); - -/** - * Get the id of the tree pointed to by a commit. This differs from - * `git_commit_tree` in that no attempts are made to fetch an object - * from the ODB. - * - * @param commit a previously loaded commit. - * @return the id of tree pointed to by commit. - */ -GIT_EXTERN(const git_oid *) git_commit_tree_id(const git_commit *commit); - -/** - * Get the number of parents of this commit - * - * @param commit a previously loaded commit. - * @return integer of count of parents - */ -GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit); - -/** - * Get the specified parent of the commit. - * - * @param out Pointer where to store the parent commit - * @param commit a previously loaded commit. - * @param n the position of the parent (from 0 to `parentcount`) - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_parent( - git_commit **out, - const git_commit *commit, - unsigned int n); - -/** - * Get the oid of a specified parent for a commit. This is different from - * `git_commit_parent`, which will attempt to load the parent commit from - * the ODB. - * - * @param commit a previously loaded commit. - * @param n the position of the parent (from 0 to `parentcount`) - * @return the id of the parent, NULL on error. - */ -GIT_EXTERN(const git_oid *) git_commit_parent_id( - const git_commit *commit, - unsigned int n); - -/** - * Get the commit object that is the th generation ancestor - * of the named commit object, following only the first parents. - * The returned commit has to be freed by the caller. - * - * Passing `0` as the generation number returns another instance of the - * base commit itself. - * - * @param ancestor Pointer where to store the ancestor commit - * @param commit a previously loaded commit. - * @param n the requested generation - * @return 0 on success; GIT_ENOTFOUND if no matching ancestor exists - * or an error code - */ -GIT_EXTERN(int) git_commit_nth_gen_ancestor( - git_commit **ancestor, - const git_commit *commit, - unsigned int n); - -/** - * Get an arbitrary header field - * - * @param out the buffer to fill; existing content will be - * overwritten - * @param commit the commit to look in - * @param field the header field to return - * @return 0 on succeess, GIT_ENOTFOUND if the field does not exist, - * or an error code - */ -GIT_EXTERN(int) git_commit_header_field(git_buf *out, const git_commit *commit, const char *field); - -/** - * Extract the signature from a commit - * - * If the id is not for a commit, the error class will be - * `GIT_ERROR_INVALID`. If the commit does not have a signature, the - * error class will be `GIT_ERROR_OBJECT`. - * - * @param signature the signature block; existing content will be - * overwritten - * @param signed_data signed data; this is the commit contents minus the signature block; - * existing content will be overwritten - * @param repo the repository in which the commit exists - * @param commit_id the commit from which to extract the data - * @param field the name of the header field containing the signature - * block; pass `NULL` to extract the default 'gpgsig' - * @return 0 on success, GIT_ENOTFOUND if the id is not for a commit - * or the commit does not have a signature. - */ -GIT_EXTERN(int) git_commit_extract_signature(git_buf *signature, git_buf *signed_data, git_repository *repo, git_oid *commit_id, const char *field); - -/** - * Create new commit in the repository from a list of `git_object` pointers - * - * The message will **not** be cleaned up automatically. You can do that - * with the `git_message_prettify()` function. - * - * @param id Pointer in which to store the OID of the newly created commit - * - * @param repo Repository where to store the commit - * - * @param update_ref If not NULL, name of the reference that - * will be updated to point to this commit. If the reference - * is not direct, it will be resolved to a direct reference. - * Use "HEAD" to update the HEAD of the current branch and - * make it point to this commit. If the reference doesn't - * exist yet, it will be created. If it does exist, the first - * parent must be the tip of this branch. - * - * @param author Signature with author and author time of commit - * - * @param committer Signature with committer and * commit time of commit - * - * @param message_encoding The encoding for the message in the - * commit, represented with a standard encoding name. - * E.g. "UTF-8". If NULL, no encoding header is written and - * UTF-8 is assumed. - * - * @param message Full message for this commit - * - * @param tree An instance of a `git_tree` object that will - * be used as the tree for the commit. This tree object must - * also be owned by the given `repo`. - * - * @param parent_count Number of parents for this commit - * - * @param parents Array of `parent_count` pointers to `git_commit` - * objects that will be used as the parents for this commit. This - * array may be NULL if `parent_count` is 0 (root commit). All the - * given commits must be owned by the `repo`. - * - * @return 0 or an error code - * The created commit will be written to the Object Database and - * the given reference will be updated to point to it - */ -GIT_EXTERN(int) git_commit_create( - git_oid *id, - git_repository *repo, - const char *update_ref, - const git_signature *author, - const git_signature *committer, - const char *message_encoding, - const char *message, - const git_tree *tree, - size_t parent_count, - git_commit * const parents[]); - -/** - * Create new commit in the repository using a variable argument list. - * - * The message will **not** be cleaned up automatically. You can do that - * with the `git_message_prettify()` function. - * - * The parents for the commit are specified as a variable list of pointers - * to `const git_commit *`. Note that this is a convenience method which may - * not be safe to export for certain languages or compilers - * - * All other parameters remain the same as `git_commit_create()`. - * - * @see git_commit_create - */ -GIT_EXTERN(int) git_commit_create_v( - git_oid *id, - git_repository *repo, - const char *update_ref, - const git_signature *author, - const git_signature *committer, - const char *message_encoding, - const char *message, - const git_tree *tree, - size_t parent_count, - ...); - -typedef struct { - unsigned int version; - - /** - * Flags for creating the commit. - * - * If `allow_empty_commit` is specified, a commit with no changes - * from the prior commit (and "empty" commit) is allowed. Otherwise, - * commit creation will be stopped. - */ - unsigned int allow_empty_commit : 1; - - /** The commit author, or NULL for the default. */ - const git_signature *author; - - /** The committer, or NULL for the default. */ - const git_signature *committer; - - /** Encoding for the commit message; leave NULL for default. */ - const char *message_encoding; -} git_commit_create_options; - -#define GIT_COMMIT_CREATE_OPTIONS_VERSION 1 -#define GIT_COMMIT_CREATE_OPTIONS_INIT { GIT_COMMIT_CREATE_OPTIONS_VERSION } - -/** - * Commits the staged changes in the repository; this is a near analog to - * `git commit -m message`. - * - * By default, empty commits are not allowed. - * - * @param id pointer to store the new commit's object id - * @param repo repository to commit changes in - * @param message the commit message - * @param opts options for creating the commit - * @return 0 on success, GIT_EUNCHANGED if there were no changes to commit, or an error code - */ -GIT_EXTERN(int) git_commit_create_from_stage( - git_oid *id, - git_repository *repo, - const char *message, - const git_commit_create_options *opts); - -/** - * Amend an existing commit by replacing only non-NULL values. - * - * This creates a new commit that is exactly the same as the old commit, - * except that any non-NULL values will be updated. The new commit has - * the same parents as the old commit. - * - * The `update_ref` value works as in the regular `git_commit_create()`, - * updating the ref to point to the newly rewritten commit. If you want - * to amend a commit that is not currently the tip of the branch and then - * rewrite the following commits to reach a ref, pass this as NULL and - * update the rest of the commit chain and ref separately. - * - * Unlike `git_commit_create()`, the `author`, `committer`, `message`, - * `message_encoding`, and `tree` parameters can be NULL in which case this - * will use the values from the original `commit_to_amend`. - * - * All parameters have the same meanings as in `git_commit_create()`. - * - * @see git_commit_create - */ -GIT_EXTERN(int) git_commit_amend( - git_oid *id, - const git_commit *commit_to_amend, - const char *update_ref, - const git_signature *author, - const git_signature *committer, - const char *message_encoding, - const char *message, - const git_tree *tree); - -/** - * Create a commit and write it into a buffer - * - * Create a commit as with `git_commit_create()` but instead of - * writing it to the objectdb, write the contents of the object into a - * buffer. - * - * @param out the buffer into which to write the commit object content - * - * @param repo Repository where the referenced tree and parents live - * - * @param author Signature with author and author time of commit - * - * @param committer Signature with committer and * commit time of commit - * - * @param message_encoding The encoding for the message in the - * commit, represented with a standard encoding name. - * E.g. "UTF-8". If NULL, no encoding header is written and - * UTF-8 is assumed. - * - * @param message Full message for this commit - * - * @param tree An instance of a `git_tree` object that will - * be used as the tree for the commit. This tree object must - * also be owned by the given `repo`. - * - * @param parent_count Number of parents for this commit - * - * @param parents Array of `parent_count` pointers to `git_commit` - * objects that will be used as the parents for this commit. This - * array may be NULL if `parent_count` is 0 (root commit). All the - * given commits must be owned by the `repo`. - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_create_buffer( - git_buf *out, - git_repository *repo, - const git_signature *author, - const git_signature *committer, - const char *message_encoding, - const char *message, - const git_tree *tree, - size_t parent_count, - git_commit * const parents[]); - -/** - * Create a commit object from the given buffer and signature - * - * Given the unsigned commit object's contents, its signature and the - * header field in which to store the signature, attach the signature - * to the commit and write it into the given repository. - * - * @param out the resulting commit id - * @param repo the repository to create the commit in. - * @param commit_content the content of the unsigned commit object - * @param signature the signature to add to the commit. Leave `NULL` - * to create a commit without adding a signature field. - * @param signature_field which header field should contain this - * signature. Leave `NULL` for the default of "gpgsig" - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_create_with_signature( - git_oid *out, - git_repository *repo, - const char *commit_content, - const char *signature, - const char *signature_field); - -/** - * Create an in-memory copy of a commit. The copy must be explicitly - * free'd or it will leak. - * - * @param out Pointer to store the copy of the commit - * @param source Original commit to copy - * @return 0 - */ -GIT_EXTERN(int) git_commit_dup(git_commit **out, git_commit *source); - -/** - * Commit creation callback: used when a function is going to create - * commits (for example, in `git_rebase_commit`) to allow callers to - * override the commit creation behavior. For example, users may - * wish to sign commits by providing this information to - * `git_commit_create_buffer`, signing that buffer, then calling - * `git_commit_create_with_signature`. The resultant commit id - * should be set in the `out` object id parameter. - * - * @param out pointer that this callback will populate with the object - * id of the commit that is created - * @param author the author name and time of the commit - * @param committer the committer name and time of the commit - * @param message_encoding the encoding of the given message, or NULL - * to assume UTF8 - * @param message the commit message - * @param tree the tree to be committed - * @param parent_count the number of parents for this commit - * @param parents the commit parents - * @param payload the payload pointer in the rebase options - * @return 0 if this callback has created the commit and populated the out - * parameter, GIT_PASSTHROUGH if the callback has not created a - * commit and wants the calling function to create the commit as - * if no callback had been specified, any other value to stop - * and return a failure - */ -typedef int (*git_commit_create_cb)( - git_oid *out, - const git_signature *author, - const git_signature *committer, - const char *message_encoding, - const char *message, - const git_tree *tree, - size_t parent_count, - git_commit * const parents[], - void *payload); - -/** An array of commits returned from the library */ -typedef struct git_commitarray { - git_commit *const *commits; - size_t count; -} git_commitarray; - -/** - * Free the commits contained in a commit array. This method should - * be called on `git_commitarray` objects that were provided by the - * library. Not doing so will result in a memory leak. - * - * This does not free the `git_commitarray` itself, since the library - * will never allocate that object directly itself. - * - * @param array The git_commitarray that contains commits to free - */ -GIT_EXTERN(void) git_commitarray_dispose(git_commitarray *array); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_commit_h__ +#define INCLUDE_git_commit_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "object.h" + +/** + * @file git2/commit.h + * @brief Git commit parsing, formatting routines + * @defgroup git_commit Git commit parsing, formatting routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Lookup a commit object from a repository. + * + * The returned object should be released with `git_commit_free` when no + * longer needed. + * + * @param commit pointer to the looked up commit + * @param repo the repo to use when locating the commit. + * @param id identity of the commit to locate. If the object is + * an annotated tag it will be peeled back to the commit. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_lookup( + git_commit **commit, git_repository *repo, const git_oid *id); + +/** + * Lookup a commit object from a repository, given a prefix of its + * identifier (short id). + * + * The returned object should be released with `git_commit_free` when no + * longer needed. + * + * @see git_object_lookup_prefix + * + * @param commit pointer to the looked up commit + * @param repo the repo to use when locating the commit. + * @param id identity of the commit to locate. If the object is + * an annotated tag it will be peeled back to the commit. + * @param len the length of the short identifier + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_lookup_prefix( + git_commit **commit, git_repository *repo, const git_oid *id, size_t len); + +/** + * Close an open commit + * + * This is a wrapper around git_object_free() + * + * IMPORTANT: + * It *is* necessary to call this method when you stop + * using a commit. Failure to do so will cause a memory leak. + * + * @param commit the commit to close + */ + +GIT_EXTERN(void) git_commit_free(git_commit *commit); + +/** + * Get the id of a commit. + * + * @param commit a previously loaded commit. + * @return object identity for the commit. + */ +GIT_EXTERN(const git_oid *) git_commit_id(const git_commit *commit); + +/** + * Get the repository that contains the commit. + * + * @param commit A previously loaded commit. + * @return Repository that contains this commit. + */ +GIT_EXTERN(git_repository *) git_commit_owner(const git_commit *commit); + +/** + * Get the encoding for the message of a commit, + * as a string representing a standard encoding name. + * + * The encoding may be NULL if the `encoding` header + * in the commit is missing; in that case UTF-8 is assumed. + * + * @param commit a previously loaded commit. + * @return NULL, or the encoding + */ +GIT_EXTERN(const char *) git_commit_message_encoding(const git_commit *commit); + +/** + * Get the full message of a commit. + * + * The returned message will be slightly prettified by removing any + * potential leading newlines. + * + * @param commit a previously loaded commit. + * @return the message of a commit + */ +GIT_EXTERN(const char *) git_commit_message(const git_commit *commit); + +/** + * Get the full raw message of a commit. + * + * @param commit a previously loaded commit. + * @return the raw message of a commit + */ +GIT_EXTERN(const char *) git_commit_message_raw(const git_commit *commit); + +/** + * Get the short "summary" of the git commit message. + * + * The returned message is the summary of the commit, comprising the + * first paragraph of the message with whitespace trimmed and squashed. + * + * @param commit a previously loaded commit. + * @return the summary of a commit or NULL on error + */ +GIT_EXTERN(const char *) git_commit_summary(git_commit *commit); + +/** + * Get the long "body" of the git commit message. + * + * The returned message is the body of the commit, comprising + * everything but the first paragraph of the message. Leading and + * trailing whitespaces are trimmed. + * + * @param commit a previously loaded commit. + * @return the body of a commit or NULL when no the message only + * consists of a summary + */ +GIT_EXTERN(const char *) git_commit_body(git_commit *commit); + +/** + * Get the commit time (i.e. committer time) of a commit. + * + * @param commit a previously loaded commit. + * @return the time of a commit + */ +GIT_EXTERN(git_time_t) git_commit_time(const git_commit *commit); + +/** + * Get the commit timezone offset (i.e. committer's preferred timezone) of a commit. + * + * @param commit a previously loaded commit. + * @return positive or negative timezone offset, in minutes from UTC + */ +GIT_EXTERN(int) git_commit_time_offset(const git_commit *commit); + +/** + * Get the committer of a commit. + * + * @param commit a previously loaded commit. + * @return the committer of a commit + */ +GIT_EXTERN(const git_signature *) git_commit_committer(const git_commit *commit); + +/** + * Get the author of a commit. + * + * @param commit a previously loaded commit. + * @return the author of a commit + */ +GIT_EXTERN(const git_signature *) git_commit_author(const git_commit *commit); + +/** + * Get the committer of a commit, using the mailmap to map names and email + * addresses to canonical real names and email addresses. + * + * Call `git_signature_free` to free the signature. + * + * @param out a pointer to store the resolved signature. + * @param commit a previously loaded commit. + * @param mailmap the mailmap to resolve with. (may be NULL) + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_committer_with_mailmap( + git_signature **out, const git_commit *commit, const git_mailmap *mailmap); + +/** + * Get the author of a commit, using the mailmap to map names and email + * addresses to canonical real names and email addresses. + * + * Call `git_signature_free` to free the signature. + * + * @param out a pointer to store the resolved signature. + * @param commit a previously loaded commit. + * @param mailmap the mailmap to resolve with. (may be NULL) + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_author_with_mailmap( + git_signature **out, const git_commit *commit, const git_mailmap *mailmap); + +/** + * Get the full raw text of the commit header. + * + * @param commit a previously loaded commit + * @return the header text of the commit + */ +GIT_EXTERN(const char *) git_commit_raw_header(const git_commit *commit); + +/** + * Get the tree pointed to by a commit. + * + * @param tree_out pointer where to store the tree object + * @param commit a previously loaded commit. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, const git_commit *commit); + +/** + * Get the id of the tree pointed to by a commit. This differs from + * `git_commit_tree` in that no attempts are made to fetch an object + * from the ODB. + * + * @param commit a previously loaded commit. + * @return the id of tree pointed to by commit. + */ +GIT_EXTERN(const git_oid *) git_commit_tree_id(const git_commit *commit); + +/** + * Get the number of parents of this commit + * + * @param commit a previously loaded commit. + * @return integer of count of parents + */ +GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit); + +/** + * Get the specified parent of the commit. + * + * @param out Pointer where to store the parent commit + * @param commit a previously loaded commit. + * @param n the position of the parent (from 0 to `parentcount`) + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_parent( + git_commit **out, + const git_commit *commit, + unsigned int n); + +/** + * Get the oid of a specified parent for a commit. This is different from + * `git_commit_parent`, which will attempt to load the parent commit from + * the ODB. + * + * @param commit a previously loaded commit. + * @param n the position of the parent (from 0 to `parentcount`) + * @return the id of the parent, NULL on error. + */ +GIT_EXTERN(const git_oid *) git_commit_parent_id( + const git_commit *commit, + unsigned int n); + +/** + * Get the commit object that is the th generation ancestor + * of the named commit object, following only the first parents. + * The returned commit has to be freed by the caller. + * + * Passing `0` as the generation number returns another instance of the + * base commit itself. + * + * @param ancestor Pointer where to store the ancestor commit + * @param commit a previously loaded commit. + * @param n the requested generation + * @return 0 on success; GIT_ENOTFOUND if no matching ancestor exists + * or an error code + */ +GIT_EXTERN(int) git_commit_nth_gen_ancestor( + git_commit **ancestor, + const git_commit *commit, + unsigned int n); + +/** + * Get an arbitrary header field + * + * @param out the buffer to fill; existing content will be + * overwritten + * @param commit the commit to look in + * @param field the header field to return + * @return 0 on succeess, GIT_ENOTFOUND if the field does not exist, + * or an error code + */ +GIT_EXTERN(int) git_commit_header_field(git_buf *out, const git_commit *commit, const char *field); + +/** + * Extract the signature from a commit + * + * If the id is not for a commit, the error class will be + * `GIT_ERROR_INVALID`. If the commit does not have a signature, the + * error class will be `GIT_ERROR_OBJECT`. + * + * @param signature the signature block; existing content will be + * overwritten + * @param signed_data signed data; this is the commit contents minus the signature block; + * existing content will be overwritten + * @param repo the repository in which the commit exists + * @param commit_id the commit from which to extract the data + * @param field the name of the header field containing the signature + * block; pass `NULL` to extract the default 'gpgsig' + * @return 0 on success, GIT_ENOTFOUND if the id is not for a commit + * or the commit does not have a signature. + */ +GIT_EXTERN(int) git_commit_extract_signature(git_buf *signature, git_buf *signed_data, git_repository *repo, git_oid *commit_id, const char *field); + +/** + * Create new commit in the repository from a list of `git_object` pointers + * + * The message will **not** be cleaned up automatically. You can do that + * with the `git_message_prettify()` function. + * + * @param id Pointer in which to store the OID of the newly created commit + * + * @param repo Repository where to store the commit + * + * @param update_ref If not NULL, name of the reference that + * will be updated to point to this commit. If the reference + * is not direct, it will be resolved to a direct reference. + * Use "HEAD" to update the HEAD of the current branch and + * make it point to this commit. If the reference doesn't + * exist yet, it will be created. If it does exist, the first + * parent must be the tip of this branch. + * + * @param author Signature with author and author time of commit + * + * @param committer Signature with committer and * commit time of commit + * + * @param message_encoding The encoding for the message in the + * commit, represented with a standard encoding name. + * E.g. "UTF-8". If NULL, no encoding header is written and + * UTF-8 is assumed. + * + * @param message Full message for this commit + * + * @param tree An instance of a `git_tree` object that will + * be used as the tree for the commit. This tree object must + * also be owned by the given `repo`. + * + * @param parent_count Number of parents for this commit + * + * @param parents Array of `parent_count` pointers to `git_commit` + * objects that will be used as the parents for this commit. This + * array may be NULL if `parent_count` is 0 (root commit). All the + * given commits must be owned by the `repo`. + * + * @return 0 or an error code + * The created commit will be written to the Object Database and + * the given reference will be updated to point to it + */ +GIT_EXTERN(int) git_commit_create( + git_oid *id, + git_repository *repo, + const char *update_ref, + const git_signature *author, + const git_signature *committer, + const char *message_encoding, + const char *message, + const git_tree *tree, + size_t parent_count, + git_commit * const parents[]); + +/** + * Create new commit in the repository using a variable argument list. + * + * The message will **not** be cleaned up automatically. You can do that + * with the `git_message_prettify()` function. + * + * The parents for the commit are specified as a variable list of pointers + * to `const git_commit *`. Note that this is a convenience method which may + * not be safe to export for certain languages or compilers + * + * All other parameters remain the same as `git_commit_create()`. + * + * @see git_commit_create + */ +GIT_EXTERN(int) git_commit_create_v( + git_oid *id, + git_repository *repo, + const char *update_ref, + const git_signature *author, + const git_signature *committer, + const char *message_encoding, + const char *message, + const git_tree *tree, + size_t parent_count, + ...); + +typedef struct { + unsigned int version; + + /** + * Flags for creating the commit. + * + * If `allow_empty_commit` is specified, a commit with no changes + * from the prior commit (and "empty" commit) is allowed. Otherwise, + * commit creation will be stopped. + */ + unsigned int allow_empty_commit : 1; + + /** The commit author, or NULL for the default. */ + const git_signature *author; + + /** The committer, or NULL for the default. */ + const git_signature *committer; + + /** Encoding for the commit message; leave NULL for default. */ + const char *message_encoding; +} git_commit_create_options; + +#define GIT_COMMIT_CREATE_OPTIONS_VERSION 1 +#define GIT_COMMIT_CREATE_OPTIONS_INIT { GIT_COMMIT_CREATE_OPTIONS_VERSION } + +/** + * Commits the staged changes in the repository; this is a near analog to + * `git commit -m message`. + * + * By default, empty commits are not allowed. + * + * @param id pointer to store the new commit's object id + * @param repo repository to commit changes in + * @param message the commit message + * @param opts options for creating the commit + * @return 0 on success, GIT_EUNCHANGED if there were no changes to commit, or an error code + */ +GIT_EXTERN(int) git_commit_create_from_stage( + git_oid *id, + git_repository *repo, + const char *message, + const git_commit_create_options *opts); + +/** + * Amend an existing commit by replacing only non-NULL values. + * + * This creates a new commit that is exactly the same as the old commit, + * except that any non-NULL values will be updated. The new commit has + * the same parents as the old commit. + * + * The `update_ref` value works as in the regular `git_commit_create()`, + * updating the ref to point to the newly rewritten commit. If you want + * to amend a commit that is not currently the tip of the branch and then + * rewrite the following commits to reach a ref, pass this as NULL and + * update the rest of the commit chain and ref separately. + * + * Unlike `git_commit_create()`, the `author`, `committer`, `message`, + * `message_encoding`, and `tree` parameters can be NULL in which case this + * will use the values from the original `commit_to_amend`. + * + * All parameters have the same meanings as in `git_commit_create()`. + * + * @see git_commit_create + */ +GIT_EXTERN(int) git_commit_amend( + git_oid *id, + const git_commit *commit_to_amend, + const char *update_ref, + const git_signature *author, + const git_signature *committer, + const char *message_encoding, + const char *message, + const git_tree *tree); + +/** + * Create a commit and write it into a buffer + * + * Create a commit as with `git_commit_create()` but instead of + * writing it to the objectdb, write the contents of the object into a + * buffer. + * + * @param out the buffer into which to write the commit object content + * + * @param repo Repository where the referenced tree and parents live + * + * @param author Signature with author and author time of commit + * + * @param committer Signature with committer and * commit time of commit + * + * @param message_encoding The encoding for the message in the + * commit, represented with a standard encoding name. + * E.g. "UTF-8". If NULL, no encoding header is written and + * UTF-8 is assumed. + * + * @param message Full message for this commit + * + * @param tree An instance of a `git_tree` object that will + * be used as the tree for the commit. This tree object must + * also be owned by the given `repo`. + * + * @param parent_count Number of parents for this commit + * + * @param parents Array of `parent_count` pointers to `git_commit` + * objects that will be used as the parents for this commit. This + * array may be NULL if `parent_count` is 0 (root commit). All the + * given commits must be owned by the `repo`. + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_create_buffer( + git_buf *out, + git_repository *repo, + const git_signature *author, + const git_signature *committer, + const char *message_encoding, + const char *message, + const git_tree *tree, + size_t parent_count, + git_commit * const parents[]); + +/** + * Create a commit object from the given buffer and signature + * + * Given the unsigned commit object's contents, its signature and the + * header field in which to store the signature, attach the signature + * to the commit and write it into the given repository. + * + * @param out the resulting commit id + * @param repo the repository to create the commit in. + * @param commit_content the content of the unsigned commit object + * @param signature the signature to add to the commit. Leave `NULL` + * to create a commit without adding a signature field. + * @param signature_field which header field should contain this + * signature. Leave `NULL` for the default of "gpgsig" + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_create_with_signature( + git_oid *out, + git_repository *repo, + const char *commit_content, + const char *signature, + const char *signature_field); + +/** + * Create an in-memory copy of a commit. The copy must be explicitly + * free'd or it will leak. + * + * @param out Pointer to store the copy of the commit + * @param source Original commit to copy + * @return 0 + */ +GIT_EXTERN(int) git_commit_dup(git_commit **out, git_commit *source); + +/** + * Commit creation callback: used when a function is going to create + * commits (for example, in `git_rebase_commit`) to allow callers to + * override the commit creation behavior. For example, users may + * wish to sign commits by providing this information to + * `git_commit_create_buffer`, signing that buffer, then calling + * `git_commit_create_with_signature`. The resultant commit id + * should be set in the `out` object id parameter. + * + * @param out pointer that this callback will populate with the object + * id of the commit that is created + * @param author the author name and time of the commit + * @param committer the committer name and time of the commit + * @param message_encoding the encoding of the given message, or NULL + * to assume UTF8 + * @param message the commit message + * @param tree the tree to be committed + * @param parent_count the number of parents for this commit + * @param parents the commit parents + * @param payload the payload pointer in the rebase options + * @return 0 if this callback has created the commit and populated the out + * parameter, GIT_PASSTHROUGH if the callback has not created a + * commit and wants the calling function to create the commit as + * if no callback had been specified, any other value to stop + * and return a failure + */ +typedef int (*git_commit_create_cb)( + git_oid *out, + const git_signature *author, + const git_signature *committer, + const char *message_encoding, + const char *message, + const git_tree *tree, + size_t parent_count, + git_commit * const parents[], + void *payload); + +/** An array of commits returned from the library */ +typedef struct git_commitarray { + git_commit *const *commits; + size_t count; +} git_commitarray; + +/** + * Free the commits contained in a commit array. This method should + * be called on `git_commitarray` objects that were provided by the + * library. Not doing so will result in a memory leak. + * + * This does not free the `git_commitarray` itself, since the library + * will never allocate that object directly itself. + * + * @param array The git_commitarray that contains commits to free + */ +GIT_EXTERN(void) git_commitarray_dispose(git_commitarray *array); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/common.h b/3rdparty/libgit2/include/git2/common.h index 0f42c34..51daa19 100644 --- a/3rdparty/libgit2/include/git2/common.h +++ b/3rdparty/libgit2/include/git2/common.h @@ -1,514 +1,514 @@ -/* - * 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 -#include - -#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 -# include -#elif !defined(__CLANG_INTTYPES_H) -# include -#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 __cdecl -#else -# define GIT_EXTERN(type) extern type -#endif - -/** Declare a callback function for application use. */ -#if defined(_MSC_VER) -# define GIT_CALLBACK(name) (__cdecl *name) -#else -# define GIT_CALLBACK(name) (*name) -#endif - -/** Declare a function as deprecated. */ -#if defined(__GNUC__) -# define GIT_DEPRECATED(func) \ - __attribute__((deprecated)) \ - __attribute__((used)) \ - func -#elif defined(_MSC_VER) -# define GIT_DEPRECATED(func) __declspec(deprecated) func -#else -# define GIT_DEPRECATED(func) func -#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 -#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 - * AmigaOS, and a colon ":" for all other systems. - */ -#if defined(GIT_WIN32) || defined(AMIGA) -#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 - -/** - * 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 - * @return 0 on success or an error code on failure - */ -GIT_EXTERN(int) git_libgit2_version(int *major, int *minor, int *rev); - -/** - * Return the prerelease state of the libgit2 library currently being - * used. For nightly builds during active development, this will be - * "alpha". Releases may have a "beta" or release candidate ("rc1", - * "rc2", etc) prerelease. For a final release, this function returns - * NULL. - * - * @return the name of the prerelease state or NULL - */ -GIT_EXTERN(const char *) git_libgit2_prerelease(void); - -/** - * Combinations of these values describe the features with which libgit2 - * was compiled - */ -typedef enum { - /** - * If set, libgit2 was built thread-aware and can be safely used from multiple - * threads. - */ - GIT_FEATURE_THREADS = (1 << 0), - /** - * If set, libgit2 was built with and linked against a TLS implementation. - * Custom TLS streams may still be added by the user to support HTTPS - * regardless of this. - */ - GIT_FEATURE_HTTPS = (1 << 1), - /** - * If set, libgit2 was built with and linked against libssh2. A custom - * transport may still be added by the user to support libssh2 regardless of - * this. - */ - GIT_FEATURE_SSH = (1 << 2), - /** - * If set, libgit2 was built with support for sub-second resolution in file - * modification times. - */ - 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_FEATURE_NSEC - * Libgit2 supports the sub-second resolution in file modification times. - */ -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_ENABLE_STRICT_SYMBOLIC_REF_CREATION, - GIT_OPT_SET_SSL_CIPHERS, - GIT_OPT_GET_USER_AGENT, - GIT_OPT_ENABLE_OFS_DELTA, - GIT_OPT_ENABLE_FSYNC_GITDIR, - GIT_OPT_GET_WINDOWS_SHAREMODE, - GIT_OPT_SET_WINDOWS_SHAREMODE, - GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION, - GIT_OPT_SET_ALLOCATOR, - GIT_OPT_ENABLE_UNSAVED_INDEX_SAFETY, - GIT_OPT_GET_PACK_MAX_OBJECTS, - GIT_OPT_SET_PACK_MAX_OBJECTS, - GIT_OPT_DISABLE_PACK_KEEP_FILE_CHECKS, - GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE, - GIT_OPT_GET_MWINDOW_FILE_LIMIT, - GIT_OPT_SET_MWINDOW_FILE_LIMIT, - GIT_OPT_SET_ODB_PACKED_PRIORITY, - GIT_OPT_SET_ODB_LOOSE_PRIORITY, - GIT_OPT_GET_EXTENSIONS, - GIT_OPT_SET_EXTENSIONS, - GIT_OPT_GET_OWNER_VALIDATION, - GIT_OPT_SET_OWNER_VALIDATION, - GIT_OPT_GET_HOMEDIR, - GIT_OPT_SET_HOMEDIR, - GIT_OPT_SET_SERVER_CONNECT_TIMEOUT, - GIT_OPT_GET_SERVER_CONNECT_TIMEOUT, - GIT_OPT_SET_SERVER_TIMEOUT, - GIT_OPT_GET_SERVER_TIMEOUT -} 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_MWINDOW_FILE_LIMIT, size_t *): - * - * > Get the maximum number of files that will be mapped at any time by the - * > library - * - * * opts(GIT_OPT_SET_MWINDOW_FILE_LIMIT, size_t): - * - * > Set the maximum number of files that can be mapped at any time - * > by the library. The default (0) is unlimited. - * - * * 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_object_t 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_OBJECT_BLOB (i.e. won't cache blobs) and 4k - * > for GIT_OBJECT_COMMIT, GIT_OBJECT_TREE, and GIT_OBJECT_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_SET_WINDOWS_SHAREMODE, unsigned long value) - * - * > Set the share mode used when opening files on Windows. - * > For more information, see the documentation for CreateFile. - * > The default is: FILE_SHARE_READ | FILE_SHARE_WRITE. This is - * > ignored and unused on non-Windows platforms. - * - * * opts(GIT_OPT_GET_WINDOWS_SHAREMODE, unsigned long *value) - * - * > Get the share mode used when opening files on Windows. - * - * * 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_ENABLE_STRICT_SYMBOLIC_REF_CREATION, int enabled) - * - * > Validate the target of a symbolic ref when creating it. For - * > example, `foobar` is not a valid ref, therefore `foobar` is - * > not a valid target for a symbolic ref by default, whereas - * > `refs/heads/foobar` is. Disabling this bypasses validation - * > so that an arbitrary strings such as `foobar` can be used - * > for a symbolic ref target. 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. - * - * * opts(GIT_OPT_GET_USER_AGENT, git_buf *out) - * - * > Get the value of the User-Agent header. - * > The User-Agent is written to the `out` buffer. - * - * * opts(GIT_OPT_ENABLE_OFS_DELTA, int enabled) - * - * > Enable or disable the use of "offset deltas" when creating packfiles, - * > and the negotiation of them when talking to a remote server. - * > Offset deltas store a delta base location as an offset into the - * > packfile from the current location, which provides a shorter encoding - * > and thus smaller resultant packfiles. - * > Packfiles containing offset deltas can still be read. - * > This defaults to enabled. - * - * * opts(GIT_OPT_ENABLE_FSYNC_GITDIR, int enabled) - * - * > Enable synchronized writes of files in the gitdir using `fsync` - * > (or the platform equivalent) to ensure that new object data - * > is written to permanent storage, not simply cached. This - * > defaults to disabled. - * - * opts(GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION, int enabled) - * - * > Enable strict verification of object hashsums when reading - * > objects from disk. This may impact performance due to an - * > additional checksum calculation on each object. This defaults - * > to enabled. - * - * opts(GIT_OPT_SET_ALLOCATOR, git_allocator *allocator) - * - * > Set the memory allocator to a different memory allocator. This - * > allocator will then be used to make all memory allocations for - * > libgit2 operations. If the given `allocator` is NULL, then the - * > system default will be restored. - * - * opts(GIT_OPT_ENABLE_UNSAVED_INDEX_SAFETY, int enabled) - * - * > Ensure that there are no unsaved changes in the index before - * > beginning any operation that reloads the index from disk (eg, - * > checkout). If there are unsaved changes, the instruction will - * > fail. (Using the FORCE flag to checkout will still overwrite - * > these changes.) - * - * opts(GIT_OPT_GET_PACK_MAX_OBJECTS, size_t *out) - * - * > Get the maximum number of objects libgit2 will allow in a pack - * > file when downloading a pack file from a remote. This can be - * > used to limit maximum memory usage when fetching from an untrusted - * > remote. - * - * opts(GIT_OPT_SET_PACK_MAX_OBJECTS, size_t objects) - * - * > Set the maximum number of objects libgit2 will allow in a pack - * > file when downloading a pack file from a remote. - * - * opts(GIT_OPT_DISABLE_PACK_KEEP_FILE_CHECKS, int enabled) - * > This will cause .keep file existence checks to be skipped when - * > accessing packfiles, which can help performance with remote filesystems. - * - * opts(GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE, int enabled) - * > When connecting to a server using NTLM or Negotiate - * > authentication, use expect/continue when POSTing data. - * > This option is not available on Windows. - * - * opts(GIT_OPT_SET_ODB_PACKED_PRIORITY, int priority) - * > Override the default priority of the packed ODB backend which - * > is added when default backends are assigned to a repository - * - * opts(GIT_OPT_SET_ODB_LOOSE_PRIORITY, int priority) - * > Override the default priority of the loose ODB backend which - * > is added when default backends are assigned to a repository - * - * opts(GIT_OPT_GET_EXTENSIONS, git_strarray *out) - * > Returns the list of git extensions that are supported. This - * > is the list of built-in extensions supported by libgit2 and - * > custom extensions that have been added with - * > `GIT_OPT_SET_EXTENSIONS`. Extensions that have been negated - * > will not be returned. The returned list should be released - * > with `git_strarray_dispose`. - * - * opts(GIT_OPT_SET_EXTENSIONS, const char **extensions, size_t len) - * > Set that the given git extensions are supported by the caller. - * > Extensions supported by libgit2 may be negated by prefixing - * > them with a `!`. For example: setting extensions to - * > { "!noop", "newext" } indicates that the caller does not want - * > to support repositories with the `noop` extension but does want - * > to support repositories with the `newext` extension. - * - * opts(GIT_OPT_GET_OWNER_VALIDATION, int *enabled) - * > Gets the owner validation setting for repository - * > directories. - * - * opts(GIT_OPT_SET_OWNER_VALIDATION, int enabled) - * > Set that repository directories should be owned by the current - * > user. The default is to validate ownership. - * - * opts(GIT_OPT_GET_HOMEDIR, git_buf *out) - * > Gets the current user's home directory, as it will be used - * > for file lookups. The path is written to the `out` buffer. - * - * opts(GIT_OPT_SET_HOMEDIR, const char *path) - * > Sets the directory used as the current user's home directory, - * > for file lookups. - * > - * > - `path` directory of home directory. - * - * opts(GIT_OPT_GET_SERVER_CONNECT_TIMEOUT, int *timeout) - * > Gets the timeout (in milliseconds) to attempt connections to - * > a remote server. - * - * opts(GIT_OPT_SET_SERVER_CONNECT_TIMEOUT, int timeout) - * > Sets the timeout (in milliseconds) to attempt connections to - * > a remote server. Set to 0 to use the system default. Note that - * > this may not be able to be configured longer than the system - * > default, typically 75 seconds. - * - * opts(GIT_OPT_GET_SERVER_TIMEOUT, int *timeout) - * > Gets the timeout (in milliseconds) for reading from and writing - * > to a remote server. - * - * opts(GIT_OPT_SET_SERVER_TIMEOUT, int timeout) - * > Sets the timeout (in milliseconds) for reading from and writing - * > to a remote server. Set to 0 to use the system default. - * - * @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 +/* + * 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 +#include + +#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 +# include +#elif !defined(__CLANG_INTTYPES_H) +# include +#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 __cdecl +#else +# define GIT_EXTERN(type) extern type +#endif + +/** Declare a callback function for application use. */ +#if defined(_MSC_VER) +# define GIT_CALLBACK(name) (__cdecl *name) +#else +# define GIT_CALLBACK(name) (*name) +#endif + +/** Declare a function as deprecated. */ +#if defined(__GNUC__) +# define GIT_DEPRECATED(func) \ + __attribute__((deprecated)) \ + __attribute__((used)) \ + func +#elif defined(_MSC_VER) +# define GIT_DEPRECATED(func) __declspec(deprecated) func +#else +# define GIT_DEPRECATED(func) func +#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 +#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 + * AmigaOS, and a colon ":" for all other systems. + */ +#if defined(GIT_WIN32) || defined(AMIGA) +#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 + +/** + * 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 + * @return 0 on success or an error code on failure + */ +GIT_EXTERN(int) git_libgit2_version(int *major, int *minor, int *rev); + +/** + * Return the prerelease state of the libgit2 library currently being + * used. For nightly builds during active development, this will be + * "alpha". Releases may have a "beta" or release candidate ("rc1", + * "rc2", etc) prerelease. For a final release, this function returns + * NULL. + * + * @return the name of the prerelease state or NULL + */ +GIT_EXTERN(const char *) git_libgit2_prerelease(void); + +/** + * Combinations of these values describe the features with which libgit2 + * was compiled + */ +typedef enum { + /** + * If set, libgit2 was built thread-aware and can be safely used from multiple + * threads. + */ + GIT_FEATURE_THREADS = (1 << 0), + /** + * If set, libgit2 was built with and linked against a TLS implementation. + * Custom TLS streams may still be added by the user to support HTTPS + * regardless of this. + */ + GIT_FEATURE_HTTPS = (1 << 1), + /** + * If set, libgit2 was built with and linked against libssh2. A custom + * transport may still be added by the user to support libssh2 regardless of + * this. + */ + GIT_FEATURE_SSH = (1 << 2), + /** + * If set, libgit2 was built with support for sub-second resolution in file + * modification times. + */ + 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_FEATURE_NSEC + * Libgit2 supports the sub-second resolution in file modification times. + */ +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_ENABLE_STRICT_SYMBOLIC_REF_CREATION, + GIT_OPT_SET_SSL_CIPHERS, + GIT_OPT_GET_USER_AGENT, + GIT_OPT_ENABLE_OFS_DELTA, + GIT_OPT_ENABLE_FSYNC_GITDIR, + GIT_OPT_GET_WINDOWS_SHAREMODE, + GIT_OPT_SET_WINDOWS_SHAREMODE, + GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION, + GIT_OPT_SET_ALLOCATOR, + GIT_OPT_ENABLE_UNSAVED_INDEX_SAFETY, + GIT_OPT_GET_PACK_MAX_OBJECTS, + GIT_OPT_SET_PACK_MAX_OBJECTS, + GIT_OPT_DISABLE_PACK_KEEP_FILE_CHECKS, + GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE, + GIT_OPT_GET_MWINDOW_FILE_LIMIT, + GIT_OPT_SET_MWINDOW_FILE_LIMIT, + GIT_OPT_SET_ODB_PACKED_PRIORITY, + GIT_OPT_SET_ODB_LOOSE_PRIORITY, + GIT_OPT_GET_EXTENSIONS, + GIT_OPT_SET_EXTENSIONS, + GIT_OPT_GET_OWNER_VALIDATION, + GIT_OPT_SET_OWNER_VALIDATION, + GIT_OPT_GET_HOMEDIR, + GIT_OPT_SET_HOMEDIR, + GIT_OPT_SET_SERVER_CONNECT_TIMEOUT, + GIT_OPT_GET_SERVER_CONNECT_TIMEOUT, + GIT_OPT_SET_SERVER_TIMEOUT, + GIT_OPT_GET_SERVER_TIMEOUT +} 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_MWINDOW_FILE_LIMIT, size_t *): + * + * > Get the maximum number of files that will be mapped at any time by the + * > library + * + * * opts(GIT_OPT_SET_MWINDOW_FILE_LIMIT, size_t): + * + * > Set the maximum number of files that can be mapped at any time + * > by the library. The default (0) is unlimited. + * + * * 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_object_t 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_OBJECT_BLOB (i.e. won't cache blobs) and 4k + * > for GIT_OBJECT_COMMIT, GIT_OBJECT_TREE, and GIT_OBJECT_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_SET_WINDOWS_SHAREMODE, unsigned long value) + * + * > Set the share mode used when opening files on Windows. + * > For more information, see the documentation for CreateFile. + * > The default is: FILE_SHARE_READ | FILE_SHARE_WRITE. This is + * > ignored and unused on non-Windows platforms. + * + * * opts(GIT_OPT_GET_WINDOWS_SHAREMODE, unsigned long *value) + * + * > Get the share mode used when opening files on Windows. + * + * * 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_ENABLE_STRICT_SYMBOLIC_REF_CREATION, int enabled) + * + * > Validate the target of a symbolic ref when creating it. For + * > example, `foobar` is not a valid ref, therefore `foobar` is + * > not a valid target for a symbolic ref by default, whereas + * > `refs/heads/foobar` is. Disabling this bypasses validation + * > so that an arbitrary strings such as `foobar` can be used + * > for a symbolic ref target. 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. + * + * * opts(GIT_OPT_GET_USER_AGENT, git_buf *out) + * + * > Get the value of the User-Agent header. + * > The User-Agent is written to the `out` buffer. + * + * * opts(GIT_OPT_ENABLE_OFS_DELTA, int enabled) + * + * > Enable or disable the use of "offset deltas" when creating packfiles, + * > and the negotiation of them when talking to a remote server. + * > Offset deltas store a delta base location as an offset into the + * > packfile from the current location, which provides a shorter encoding + * > and thus smaller resultant packfiles. + * > Packfiles containing offset deltas can still be read. + * > This defaults to enabled. + * + * * opts(GIT_OPT_ENABLE_FSYNC_GITDIR, int enabled) + * + * > Enable synchronized writes of files in the gitdir using `fsync` + * > (or the platform equivalent) to ensure that new object data + * > is written to permanent storage, not simply cached. This + * > defaults to disabled. + * + * opts(GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION, int enabled) + * + * > Enable strict verification of object hashsums when reading + * > objects from disk. This may impact performance due to an + * > additional checksum calculation on each object. This defaults + * > to enabled. + * + * opts(GIT_OPT_SET_ALLOCATOR, git_allocator *allocator) + * + * > Set the memory allocator to a different memory allocator. This + * > allocator will then be used to make all memory allocations for + * > libgit2 operations. If the given `allocator` is NULL, then the + * > system default will be restored. + * + * opts(GIT_OPT_ENABLE_UNSAVED_INDEX_SAFETY, int enabled) + * + * > Ensure that there are no unsaved changes in the index before + * > beginning any operation that reloads the index from disk (eg, + * > checkout). If there are unsaved changes, the instruction will + * > fail. (Using the FORCE flag to checkout will still overwrite + * > these changes.) + * + * opts(GIT_OPT_GET_PACK_MAX_OBJECTS, size_t *out) + * + * > Get the maximum number of objects libgit2 will allow in a pack + * > file when downloading a pack file from a remote. This can be + * > used to limit maximum memory usage when fetching from an untrusted + * > remote. + * + * opts(GIT_OPT_SET_PACK_MAX_OBJECTS, size_t objects) + * + * > Set the maximum number of objects libgit2 will allow in a pack + * > file when downloading a pack file from a remote. + * + * opts(GIT_OPT_DISABLE_PACK_KEEP_FILE_CHECKS, int enabled) + * > This will cause .keep file existence checks to be skipped when + * > accessing packfiles, which can help performance with remote filesystems. + * + * opts(GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE, int enabled) + * > When connecting to a server using NTLM or Negotiate + * > authentication, use expect/continue when POSTing data. + * > This option is not available on Windows. + * + * opts(GIT_OPT_SET_ODB_PACKED_PRIORITY, int priority) + * > Override the default priority of the packed ODB backend which + * > is added when default backends are assigned to a repository + * + * opts(GIT_OPT_SET_ODB_LOOSE_PRIORITY, int priority) + * > Override the default priority of the loose ODB backend which + * > is added when default backends are assigned to a repository + * + * opts(GIT_OPT_GET_EXTENSIONS, git_strarray *out) + * > Returns the list of git extensions that are supported. This + * > is the list of built-in extensions supported by libgit2 and + * > custom extensions that have been added with + * > `GIT_OPT_SET_EXTENSIONS`. Extensions that have been negated + * > will not be returned. The returned list should be released + * > with `git_strarray_dispose`. + * + * opts(GIT_OPT_SET_EXTENSIONS, const char **extensions, size_t len) + * > Set that the given git extensions are supported by the caller. + * > Extensions supported by libgit2 may be negated by prefixing + * > them with a `!`. For example: setting extensions to + * > { "!noop", "newext" } indicates that the caller does not want + * > to support repositories with the `noop` extension but does want + * > to support repositories with the `newext` extension. + * + * opts(GIT_OPT_GET_OWNER_VALIDATION, int *enabled) + * > Gets the owner validation setting for repository + * > directories. + * + * opts(GIT_OPT_SET_OWNER_VALIDATION, int enabled) + * > Set that repository directories should be owned by the current + * > user. The default is to validate ownership. + * + * opts(GIT_OPT_GET_HOMEDIR, git_buf *out) + * > Gets the current user's home directory, as it will be used + * > for file lookups. The path is written to the `out` buffer. + * + * opts(GIT_OPT_SET_HOMEDIR, const char *path) + * > Sets the directory used as the current user's home directory, + * > for file lookups. + * > + * > - `path` directory of home directory. + * + * opts(GIT_OPT_GET_SERVER_CONNECT_TIMEOUT, int *timeout) + * > Gets the timeout (in milliseconds) to attempt connections to + * > a remote server. + * + * opts(GIT_OPT_SET_SERVER_CONNECT_TIMEOUT, int timeout) + * > Sets the timeout (in milliseconds) to attempt connections to + * > a remote server. Set to 0 to use the system default. Note that + * > this may not be able to be configured longer than the system + * > default, typically 75 seconds. + * + * opts(GIT_OPT_GET_SERVER_TIMEOUT, int *timeout) + * > Gets the timeout (in milliseconds) for reading from and writing + * > to a remote server. + * + * opts(GIT_OPT_SET_SERVER_TIMEOUT, int timeout) + * > Sets the timeout (in milliseconds) for reading from and writing + * > to a remote server. Set to 0 to use the system default. + * + * @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 diff --git a/3rdparty/libgit2/include/git2/config.h b/3rdparty/libgit2/include/git2/config.h index 3236143..68a6b5d 100644 --- a/3rdparty/libgit2/include/git2/config.h +++ b/3rdparty/libgit2/include/git2/config.h @@ -1,822 +1,822 @@ -/* - * 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_config_h__ -#define INCLUDE_git_config_h__ - -#include "common.h" -#include "types.h" -#include "buffer.h" - -/** - * @file git2/config.h - * @brief Git config management routines - * @defgroup git_config Git config management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Priority level of a config file. - * - * These priority levels correspond to the natural escalation logic - * (from higher to lower) when reading or searching for config entries - * in git.git. Meaning that for the same key, the configuration in - * the local configuration is preferred over the configuration in - * the system configuration file. - * - * Callers can add their own custom configuration, beginning at the - * `GIT_CONFIG_LEVEL_APP` level. - * - * Writes, by default, occur in the highest priority level backend - * that is writable. This ordering can be overridden with - * `git_config_set_writeorder`. - * - * git_config_open_default() and git_repository_config() honor those - * priority levels as well. - */ -typedef enum { - /** System-wide on Windows, for compatibility with portable git */ - GIT_CONFIG_LEVEL_PROGRAMDATA = 1, - - /** System-wide configuration file; /etc/gitconfig on Linux systems */ - GIT_CONFIG_LEVEL_SYSTEM = 2, - - /** XDG compatible configuration file; typically ~/.config/git/config */ - GIT_CONFIG_LEVEL_XDG = 3, - - /** User-specific configuration file (also called Global configuration - * file); typically ~/.gitconfig - */ - GIT_CONFIG_LEVEL_GLOBAL = 4, - - /** Repository specific configuration file; $WORK_DIR/.git/config on - * non-bare repos - */ - GIT_CONFIG_LEVEL_LOCAL = 5, - - /** Worktree specific configuration file; $GIT_DIR/config.worktree - */ - GIT_CONFIG_LEVEL_WORKTREE = 6, - - /** Application specific configuration file; freely defined by applications - */ - GIT_CONFIG_LEVEL_APP = 7, - - /** Represents the highest level available config file (i.e. the most - * specific config file available that actually is loaded) - */ - GIT_CONFIG_HIGHEST_LEVEL = -1 -} git_config_level_t; - -/** - * An entry in a configuration file - */ -typedef struct git_config_entry { - /** Name of the configuration entry (normalized) */ - const char *name; - - /** Literal (string) value of the entry */ - const char *value; - - /** The type of backend that this entry exists in (eg, "file") */ - const char *backend_type; - - /** - * The path to the origin of this entry. For config files, this is - * the path to the file. - */ - const char *origin_path; - - /** Depth of includes where this variable was found */ - unsigned int include_depth; - - /** Configuration level for the file this was found in */ - git_config_level_t level; - - /** - * Free function for this entry; for internal purposes. Callers - * should call `git_config_entry_free` to free data. - */ - void GIT_CALLBACK(free)(struct git_config_entry *entry); -} git_config_entry; - -/** - * Free a config entry - * - * @param entry The entry to free. - */ -GIT_EXTERN(void) git_config_entry_free(git_config_entry *entry); - -/** - * A config enumeration callback - * - * @param entry the entry currently being enumerated - * @param payload a user-specified pointer - * @return non-zero to terminate the iteration. - */ -typedef int GIT_CALLBACK(git_config_foreach_cb)(const git_config_entry *entry, void *payload); - -/** - * An opaque structure for a configuration iterator - */ -typedef struct git_config_iterator git_config_iterator; - -/** - * Config var type - */ -typedef enum { - GIT_CONFIGMAP_FALSE = 0, - GIT_CONFIGMAP_TRUE = 1, - GIT_CONFIGMAP_INT32, - GIT_CONFIGMAP_STRING -} git_configmap_t; - -/** - * Mapping from config variables to values. - */ -typedef struct { - git_configmap_t type; - const char *str_match; - int map_value; -} git_configmap; - -/** - * Locate the path to the global configuration file - * - * The user or global configuration file is usually - * located in `$HOME/.gitconfig`. - * - * This method will try to guess the full path to that - * file, if the file exists. The returned path - * may be used on any `git_config` call to load the - * global configuration file. - * - * This method will not guess the path to the xdg compatible - * config file (`.config/git/config`). - * - * @param out Pointer to a user-allocated git_buf in which to store the path - * @return 0 if a global configuration file has been found. Its path will be stored in `out`. - */ -GIT_EXTERN(int) git_config_find_global(git_buf *out); - -/** - * Locate the path to the global xdg compatible configuration file - * - * The xdg compatible configuration file is usually - * located in `$HOME/.config/git/config`. - * - * This method will try to guess the full path to that - * file, if the file exists. The returned path - * may be used on any `git_config` call to load the - * xdg compatible configuration file. - * - * @param out Pointer to a user-allocated git_buf in which to store the path - * @return 0 if a xdg compatible configuration file has been - * found. Its path will be stored in `out`. - */ -GIT_EXTERN(int) git_config_find_xdg(git_buf *out); - -/** - * Locate the path to the system configuration file - * - * If `/etc/gitconfig` doesn't exist, it will look for - * `%PROGRAMFILES%\Git\etc\gitconfig`. - * - * @param out Pointer to a user-allocated git_buf in which to store the path - * @return 0 if a system configuration file has been - * found. Its path will be stored in `out`. - */ -GIT_EXTERN(int) git_config_find_system(git_buf *out); - -/** - * Locate the path to the configuration file in ProgramData - * - * Look for the file in `%PROGRAMDATA%\Git\config` used by portable git. - * - * @param out Pointer to a user-allocated git_buf in which to store the path - * @return 0 if a ProgramData configuration file has been - * found. Its path will be stored in `out`. - */ -GIT_EXTERN(int) git_config_find_programdata(git_buf *out); - -/** - * Open the global, XDG and system configuration files - * - * Utility wrapper that finds the global, XDG and system configuration files - * and opens them into a single prioritized config object that can be - * used when accessing default config data outside a repository. - * - * @param out Pointer to store the config instance - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_open_default(git_config **out); - -/** - * Allocate a new configuration object - * - * This object is empty, so you have to add a file to it before you - * can do anything with it. - * - * @param out pointer to the new configuration - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_new(git_config **out); - -/** - * Add an on-disk config file instance to an existing config - * - * The on-disk file pointed at by `path` will be opened and - * parsed; it's expected to be a native Git config file following - * the default Git config syntax (see man git-config). - * - * If the file does not exist, the file will still be added and it - * will be created the first time we write to it. - * - * Note that the configuration object will free the file - * automatically. - * - * Further queries on this config object will access each - * of the config file instances in order (instances with - * a higher priority level will be accessed first). - * - * @param cfg the configuration to add the file to - * @param path path to the configuration file to add - * @param level the priority level of the backend - * @param force replace config file at the given priority level - * @param repo optional repository to allow parsing of - * conditional includes - * @return 0 on success, GIT_EEXISTS when adding more than one file - * for a given priority level (and force_replace set to 0), - * GIT_ENOTFOUND when the file doesn't exist or error code - */ -GIT_EXTERN(int) git_config_add_file_ondisk( - git_config *cfg, - const char *path, - git_config_level_t level, - const git_repository *repo, - int force); - -/** - * Create a new config instance containing a single on-disk file - * - * This method is a simple utility wrapper for the following sequence - * of calls: - * - git_config_new - * - git_config_add_file_ondisk - * - * @param out The configuration instance to create - * @param path Path to the on-disk file to open - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_config_open_ondisk(git_config **out, const char *path); - -/** - * Build a single-level focused config object from a multi-level one. - * - * The returned config object can be used to perform get/set/delete operations - * on a single specific level. - * - * Getting several times the same level from the same parent multi-level config - * will return different config instances, but containing the same config_file - * instance. - * - * @param out The configuration instance to create - * @param parent Multi-level config to search for the given level - * @param level Configuration level to search for - * @return 0, GIT_ENOTFOUND if the passed level cannot be found in the - * multi-level parent config, or an error code - */ -GIT_EXTERN(int) git_config_open_level( - git_config **out, - const git_config *parent, - git_config_level_t level); - -/** - * Open the global/XDG configuration file according to git's rules - * - * Git allows you to store your global configuration at - * `$HOME/.gitconfig` or `$XDG_CONFIG_HOME/git/config`. For backwards - * compatibility, the XDG file shouldn't be used unless the use has - * created it explicitly. With this function you'll open the correct - * one to write to. - * - * @param out pointer in which to store the config object - * @param config the config object in which to look - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_open_global(git_config **out, git_config *config); - -GIT_EXTERN(int) git_config_set_writeorder( - git_config *cfg, - git_config_level_t *levels, - size_t len); - -/** - * Create a snapshot of the configuration - * - * Create a snapshot of the current state of a configuration, which - * allows you to look into a consistent view of the configuration for - * looking up complex values (e.g. a remote, submodule). - * - * The string returned when querying such a config object is valid - * until it is freed. - * - * @param out pointer in which to store the snapshot config object - * @param config configuration to snapshot - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_snapshot(git_config **out, git_config *config); - -/** - * Free the configuration and its associated memory and files - * - * @param cfg the configuration to free - */ -GIT_EXTERN(void) git_config_free(git_config *cfg); - -/** - * Get the git_config_entry of a config variable. - * - * Free the git_config_entry after use with `git_config_entry_free()`. - * - * @param out pointer to the variable git_config_entry - * @param cfg where to look for the variable - * @param name the variable's name - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_get_entry( - git_config_entry **out, - const git_config *cfg, - const char *name); - -/** - * Get the value of an integer config variable. - * - * All config files will be looked into, in the order of their - * defined level. A higher level means a higher priority. The - * first occurrence of the variable will be returned here. - * - * @param out pointer to the variable where the value should be stored - * @param cfg where to look for the variable - * @param name the variable's name - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_get_int32(int32_t *out, const git_config *cfg, const char *name); - -/** - * Get the value of a long integer config variable. - * - * All config files will be looked into, in the order of their - * defined level. A higher level means a higher priority. The - * first occurrence of the variable will be returned here. - * - * @param out pointer to the variable where the value should be stored - * @param cfg where to look for the variable - * @param name the variable's name - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_get_int64(int64_t *out, const git_config *cfg, const char *name); - -/** - * Get the value of a boolean config variable. - * - * This function uses the usual C convention of 0 being false and - * anything else true. - * - * All config files will be looked into, in the order of their - * defined level. A higher level means a higher priority. The - * first occurrence of the variable will be returned here. - * - * @param out pointer to the variable where the value should be stored - * @param cfg where to look for the variable - * @param name the variable's name - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_get_bool(int *out, const git_config *cfg, const char *name); - -/** - * Get the value of a path config variable. - * - * A leading '~' will be expanded to the global search path (which - * defaults to the user's home directory but can be overridden via - * `git_libgit2_opts()`. - * - * All config files will be looked into, in the order of their - * defined level. A higher level means a higher priority. The - * first occurrence of the variable will be returned here. - * - * @param out the buffer in which to store the result - * @param cfg where to look for the variable - * @param name the variable's name - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_get_path(git_buf *out, const git_config *cfg, const char *name); - -/** - * Get the value of a string config variable. - * - * This function can only be used on snapshot config objects. The - * string is owned by the config and should not be freed by the - * user. The pointer will be valid until the config is freed. - * - * All config files will be looked into, in the order of their - * defined level. A higher level means a higher priority. The - * first occurrence of the variable will be returned here. - * - * @param out pointer to the string - * @param cfg where to look for the variable - * @param name the variable's name - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_get_string(const char **out, const git_config *cfg, const char *name); - -/** - * Get the value of a string config variable. - * - * The value of the config will be copied into the buffer. - * - * All config files will be looked into, in the order of their - * defined level. A higher level means a higher priority. The - * first occurrence of the variable will be returned here. - * - * @param out buffer in which to store the string - * @param cfg where to look for the variable - * @param name the variable's name - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_get_string_buf(git_buf *out, const git_config *cfg, const char *name); - -/** - * Get each value of a multivar in a foreach callback - * - * The callback will be called on each variable found - * - * The regular expression is applied case-sensitively on the normalized form of - * the variable name: the section and variable parts are lower-cased. The - * subsection is left unchanged. - * - * @param cfg where to look for the variable - * @param name the variable's name - * @param regexp regular expression to filter which variables we're - * interested in. Use NULL to indicate all - * @param callback the function to be called on each value of the variable - * @param payload opaque pointer to pass to the callback - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_get_multivar_foreach(const git_config *cfg, const char *name, const char *regexp, git_config_foreach_cb callback, void *payload); - -/** - * Get each value of a multivar - * - * The regular expression is applied case-sensitively on the normalized form of - * the variable name: the section and variable parts are lower-cased. The - * subsection is left unchanged. - * - * @param out pointer to store the iterator - * @param cfg where to look for the variable - * @param name the variable's name - * @param regexp regular expression to filter which variables we're - * interested in. Use NULL to indicate all - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_multivar_iterator_new(git_config_iterator **out, const git_config *cfg, const char *name, const char *regexp); - -/** - * Return the current entry and advance the iterator - * - * The pointers returned by this function are valid until the next call - * to `git_config_next` or until the iterator is freed. - * - * @param entry pointer to store the entry - * @param iter the iterator - * @return 0 or an error code. GIT_ITEROVER if the iteration has completed - */ -GIT_EXTERN(int) git_config_next(git_config_entry **entry, git_config_iterator *iter); - -/** - * Free a config iterator - * - * @param iter the iterator to free - */ -GIT_EXTERN(void) git_config_iterator_free(git_config_iterator *iter); - -/** - * Set the value of an integer config variable in the config file - * with the highest level (usually the local one). - * - * @param cfg where to look for the variable - * @param name the variable's name - * @param value Integer value for the variable - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_set_int32(git_config *cfg, const char *name, int32_t value); - -/** - * Set the value of a long integer config variable in the config file - * with the highest level (usually the local one). - * - * @param cfg where to look for the variable - * @param name the variable's name - * @param value Long integer value for the variable - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_set_int64(git_config *cfg, const char *name, int64_t value); - -/** - * Set the value of a boolean config variable in the config file - * with the highest level (usually the local one). - * - * @param cfg where to look for the variable - * @param name the variable's name - * @param value the value to store - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_set_bool(git_config *cfg, const char *name, int value); - -/** - * Set the value of a string config variable in the config file - * with the highest level (usually the local one). - * - * A copy of the string is made and the user is free to use it - * afterwards. - * - * @param cfg where to look for the variable - * @param name the variable's name - * @param value the string to store. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_set_string(git_config *cfg, const char *name, const char *value); - -/** - * Set a multivar in the local config file. - * - * The regular expression is applied case-sensitively on the value. - * - * @param cfg where to look for the variable - * @param name the variable's name - * @param regexp a regular expression to indicate which values to replace - * @param value the new value. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_set_multivar(git_config *cfg, const char *name, const char *regexp, const char *value); - -/** - * Delete a config variable from the config file - * with the highest level (usually the local one). - * - * @param cfg the configuration - * @param name the variable to delete - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_delete_entry(git_config *cfg, const char *name); - -/** - * Deletes one or several entries from a multivar in the local config file. - * - * The regular expression is applied case-sensitively on the value. - * - * @param cfg where to look for the variables - * @param name the variable's name - * @param regexp a regular expression to indicate which values to delete - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_delete_multivar(git_config *cfg, const char *name, const char *regexp); - -/** - * Perform an operation on each config variable. - * - * The callback receives the normalized name and value of each variable - * in the config backend, and the data pointer passed to this function. - * If the callback returns a non-zero value, the function stops iterating - * and returns that value to the caller. - * - * The pointers passed to the callback are only valid as long as the - * iteration is ongoing. - * - * @param cfg where to get the variables from - * @param callback the function to call on each variable - * @param payload the data to pass to the callback - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_config_foreach( - const git_config *cfg, - git_config_foreach_cb callback, - void *payload); - -/** - * Iterate over all the config variables - * - * Use `git_config_next` to advance the iteration and - * `git_config_iterator_free` when done. - * - * @param out pointer to store the iterator - * @param cfg where to get the variables from - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_iterator_new(git_config_iterator **out, const git_config *cfg); - -/** - * Iterate over all the config variables whose name matches a pattern - * - * Use `git_config_next` to advance the iteration and - * `git_config_iterator_free` when done. - * - * The regular expression is applied case-sensitively on the normalized form of - * the variable name: the section and variable parts are lower-cased. The - * subsection is left unchanged. - * - * @param out pointer to store the iterator - * @param cfg where to ge the variables from - * @param regexp regular expression to match the names - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator **out, const git_config *cfg, const char *regexp); - -/** - * Perform an operation on each config variable matching a regular expression. - * - * This behaves like `git_config_foreach` with an additional filter of a - * regular expression that filters which config keys are passed to the - * callback. - * - * The regular expression is applied case-sensitively on the normalized form of - * the variable name: the section and variable parts are lower-cased. The - * subsection is left unchanged. - * - * The regular expression is applied case-sensitively on the normalized form of - * the variable name: the case-insensitive parts are lower-case. - * - * @param cfg where to get the variables from - * @param regexp regular expression to match against config names - * @param callback the function to call on each variable - * @param payload the data to pass to the callback - * @return 0 or the return value of the callback which didn't return 0 - */ -GIT_EXTERN(int) git_config_foreach_match( - const git_config *cfg, - const char *regexp, - git_config_foreach_cb callback, - void *payload); - -/** - * Query the value of a config variable and return it mapped to - * an integer constant. - * - * This is a helper method to easily map different possible values - * to a variable to integer constants that easily identify them. - * - * A mapping array looks as follows: - * - * git_configmap autocrlf_mapping[] = { - * {GIT_CVAR_FALSE, NULL, GIT_AUTO_CRLF_FALSE}, - * {GIT_CVAR_TRUE, NULL, GIT_AUTO_CRLF_TRUE}, - * {GIT_CVAR_STRING, "input", GIT_AUTO_CRLF_INPUT}, - * {GIT_CVAR_STRING, "default", GIT_AUTO_CRLF_DEFAULT}}; - * - * On any "false" value for the variable (e.g. "false", "FALSE", "no"), the - * mapping will store `GIT_AUTO_CRLF_FALSE` in the `out` parameter. - * - * The same thing applies for any "true" value such as "true", "yes" or "1", storing - * the `GIT_AUTO_CRLF_TRUE` variable. - * - * Otherwise, if the value matches the string "input" (with case insensitive comparison), - * the given constant will be stored in `out`, and likewise for "default". - * - * If not a single match can be made to store in `out`, an error code will be - * returned. - * - * @param out place to store the result of the mapping - * @param cfg config file to get the variables from - * @param name name of the config variable to lookup - * @param maps array of `git_configmap` objects specifying the possible mappings - * @param map_n number of mapping objects in `maps` - * @return 0 on success, error code otherwise - */ -GIT_EXTERN(int) git_config_get_mapped( - int *out, - const git_config *cfg, - const char *name, - const git_configmap *maps, - size_t map_n); - -/** - * Maps a string value to an integer constant - * - * @param out place to store the result of the parsing - * @param maps array of `git_configmap` objects specifying the possible mappings - * @param map_n number of mapping objects in `maps` - * @param value value to parse - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_lookup_map_value( - int *out, - const git_configmap *maps, - size_t map_n, - const char *value); - -/** - * Parse a string value as a bool. - * - * Valid values for true are: 'true', 'yes', 'on', 1 or any - * number different from 0 - * Valid values for false are: 'false', 'no', 'off', 0 - * - * @param out place to store the result of the parsing - * @param value value to parse - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value); - -/** - * Parse a string value as an int32. - * - * An optional value suffix of 'k', 'm', or 'g' will - * cause the value to be multiplied by 1024, 1048576, - * or 1073741824 prior to output. - * - * @param out place to store the result of the parsing - * @param value value to parse - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value); - -/** - * Parse a string value as an int64. - * - * An optional value suffix of 'k', 'm', or 'g' will - * cause the value to be multiplied by 1024, 1048576, - * or 1073741824 prior to output. - * - * @param out place to store the result of the parsing - * @param value value to parse - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value); - -/** - * Parse a string value as a path. - * - * A leading '~' will be expanded to the global search path (which - * defaults to the user's home directory but can be overridden via - * `git_libgit2_opts()`. - * - * If the value does not begin with a tilde, the input will be - * returned. - * - * @param out placae to store the result of parsing - * @param value the path to evaluate - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_parse_path(git_buf *out, const char *value); - -/** - * Perform an operation on each config variable in a given config backend, - * matching a regular expression. - * - * This behaves like `git_config_foreach_match` except that only config - * entries from the given backend entry are enumerated. - * - * The regular expression is applied case-sensitively on the normalized form of - * the variable name: the section and variable parts are lower-cased. The - * subsection is left unchanged. - * - * @param backend where to get the variables from - * @param regexp regular expression to match against config names (can be NULL) - * @param callback the function to call on each variable - * @param payload the data to pass to the callback - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_config_backend_foreach_match( - git_config_backend *backend, - const char *regexp, - git_config_foreach_cb callback, - void *payload); - - -/** - * Lock the backend with the highest priority - * - * Locking disallows anybody else from writing to that backend. Any - * updates made after locking will not be visible to a reader until - * the file is unlocked. - * - * You can apply the changes by calling `git_transaction_commit()` - * before freeing the transaction. Either of these actions will unlock - * the config. - * - * @param tx the resulting transaction, use this to commit or undo the - * changes - * @param cfg the configuration in which to lock - * @return 0 or an error code - */ -GIT_EXTERN(int) git_config_lock(git_transaction **tx, git_config *cfg); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_config_h__ +#define INCLUDE_git_config_h__ + +#include "common.h" +#include "types.h" +#include "buffer.h" + +/** + * @file git2/config.h + * @brief Git config management routines + * @defgroup git_config Git config management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Priority level of a config file. + * + * These priority levels correspond to the natural escalation logic + * (from higher to lower) when reading or searching for config entries + * in git.git. Meaning that for the same key, the configuration in + * the local configuration is preferred over the configuration in + * the system configuration file. + * + * Callers can add their own custom configuration, beginning at the + * `GIT_CONFIG_LEVEL_APP` level. + * + * Writes, by default, occur in the highest priority level backend + * that is writable. This ordering can be overridden with + * `git_config_set_writeorder`. + * + * git_config_open_default() and git_repository_config() honor those + * priority levels as well. + */ +typedef enum { + /** System-wide on Windows, for compatibility with portable git */ + GIT_CONFIG_LEVEL_PROGRAMDATA = 1, + + /** System-wide configuration file; /etc/gitconfig on Linux systems */ + GIT_CONFIG_LEVEL_SYSTEM = 2, + + /** XDG compatible configuration file; typically ~/.config/git/config */ + GIT_CONFIG_LEVEL_XDG = 3, + + /** User-specific configuration file (also called Global configuration + * file); typically ~/.gitconfig + */ + GIT_CONFIG_LEVEL_GLOBAL = 4, + + /** Repository specific configuration file; $WORK_DIR/.git/config on + * non-bare repos + */ + GIT_CONFIG_LEVEL_LOCAL = 5, + + /** Worktree specific configuration file; $GIT_DIR/config.worktree + */ + GIT_CONFIG_LEVEL_WORKTREE = 6, + + /** Application specific configuration file; freely defined by applications + */ + GIT_CONFIG_LEVEL_APP = 7, + + /** Represents the highest level available config file (i.e. the most + * specific config file available that actually is loaded) + */ + GIT_CONFIG_HIGHEST_LEVEL = -1 +} git_config_level_t; + +/** + * An entry in a configuration file + */ +typedef struct git_config_entry { + /** Name of the configuration entry (normalized) */ + const char *name; + + /** Literal (string) value of the entry */ + const char *value; + + /** The type of backend that this entry exists in (eg, "file") */ + const char *backend_type; + + /** + * The path to the origin of this entry. For config files, this is + * the path to the file. + */ + const char *origin_path; + + /** Depth of includes where this variable was found */ + unsigned int include_depth; + + /** Configuration level for the file this was found in */ + git_config_level_t level; + + /** + * Free function for this entry; for internal purposes. Callers + * should call `git_config_entry_free` to free data. + */ + void GIT_CALLBACK(free)(struct git_config_entry *entry); +} git_config_entry; + +/** + * Free a config entry + * + * @param entry The entry to free. + */ +GIT_EXTERN(void) git_config_entry_free(git_config_entry *entry); + +/** + * A config enumeration callback + * + * @param entry the entry currently being enumerated + * @param payload a user-specified pointer + * @return non-zero to terminate the iteration. + */ +typedef int GIT_CALLBACK(git_config_foreach_cb)(const git_config_entry *entry, void *payload); + +/** + * An opaque structure for a configuration iterator + */ +typedef struct git_config_iterator git_config_iterator; + +/** + * Config var type + */ +typedef enum { + GIT_CONFIGMAP_FALSE = 0, + GIT_CONFIGMAP_TRUE = 1, + GIT_CONFIGMAP_INT32, + GIT_CONFIGMAP_STRING +} git_configmap_t; + +/** + * Mapping from config variables to values. + */ +typedef struct { + git_configmap_t type; + const char *str_match; + int map_value; +} git_configmap; + +/** + * Locate the path to the global configuration file + * + * The user or global configuration file is usually + * located in `$HOME/.gitconfig`. + * + * This method will try to guess the full path to that + * file, if the file exists. The returned path + * may be used on any `git_config` call to load the + * global configuration file. + * + * This method will not guess the path to the xdg compatible + * config file (`.config/git/config`). + * + * @param out Pointer to a user-allocated git_buf in which to store the path + * @return 0 if a global configuration file has been found. Its path will be stored in `out`. + */ +GIT_EXTERN(int) git_config_find_global(git_buf *out); + +/** + * Locate the path to the global xdg compatible configuration file + * + * The xdg compatible configuration file is usually + * located in `$HOME/.config/git/config`. + * + * This method will try to guess the full path to that + * file, if the file exists. The returned path + * may be used on any `git_config` call to load the + * xdg compatible configuration file. + * + * @param out Pointer to a user-allocated git_buf in which to store the path + * @return 0 if a xdg compatible configuration file has been + * found. Its path will be stored in `out`. + */ +GIT_EXTERN(int) git_config_find_xdg(git_buf *out); + +/** + * Locate the path to the system configuration file + * + * If `/etc/gitconfig` doesn't exist, it will look for + * `%PROGRAMFILES%\Git\etc\gitconfig`. + * + * @param out Pointer to a user-allocated git_buf in which to store the path + * @return 0 if a system configuration file has been + * found. Its path will be stored in `out`. + */ +GIT_EXTERN(int) git_config_find_system(git_buf *out); + +/** + * Locate the path to the configuration file in ProgramData + * + * Look for the file in `%PROGRAMDATA%\Git\config` used by portable git. + * + * @param out Pointer to a user-allocated git_buf in which to store the path + * @return 0 if a ProgramData configuration file has been + * found. Its path will be stored in `out`. + */ +GIT_EXTERN(int) git_config_find_programdata(git_buf *out); + +/** + * Open the global, XDG and system configuration files + * + * Utility wrapper that finds the global, XDG and system configuration files + * and opens them into a single prioritized config object that can be + * used when accessing default config data outside a repository. + * + * @param out Pointer to store the config instance + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_open_default(git_config **out); + +/** + * Allocate a new configuration object + * + * This object is empty, so you have to add a file to it before you + * can do anything with it. + * + * @param out pointer to the new configuration + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_new(git_config **out); + +/** + * Add an on-disk config file instance to an existing config + * + * The on-disk file pointed at by `path` will be opened and + * parsed; it's expected to be a native Git config file following + * the default Git config syntax (see man git-config). + * + * If the file does not exist, the file will still be added and it + * will be created the first time we write to it. + * + * Note that the configuration object will free the file + * automatically. + * + * Further queries on this config object will access each + * of the config file instances in order (instances with + * a higher priority level will be accessed first). + * + * @param cfg the configuration to add the file to + * @param path path to the configuration file to add + * @param level the priority level of the backend + * @param force replace config file at the given priority level + * @param repo optional repository to allow parsing of + * conditional includes + * @return 0 on success, GIT_EEXISTS when adding more than one file + * for a given priority level (and force_replace set to 0), + * GIT_ENOTFOUND when the file doesn't exist or error code + */ +GIT_EXTERN(int) git_config_add_file_ondisk( + git_config *cfg, + const char *path, + git_config_level_t level, + const git_repository *repo, + int force); + +/** + * Create a new config instance containing a single on-disk file + * + * This method is a simple utility wrapper for the following sequence + * of calls: + * - git_config_new + * - git_config_add_file_ondisk + * + * @param out The configuration instance to create + * @param path Path to the on-disk file to open + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_config_open_ondisk(git_config **out, const char *path); + +/** + * Build a single-level focused config object from a multi-level one. + * + * The returned config object can be used to perform get/set/delete operations + * on a single specific level. + * + * Getting several times the same level from the same parent multi-level config + * will return different config instances, but containing the same config_file + * instance. + * + * @param out The configuration instance to create + * @param parent Multi-level config to search for the given level + * @param level Configuration level to search for + * @return 0, GIT_ENOTFOUND if the passed level cannot be found in the + * multi-level parent config, or an error code + */ +GIT_EXTERN(int) git_config_open_level( + git_config **out, + const git_config *parent, + git_config_level_t level); + +/** + * Open the global/XDG configuration file according to git's rules + * + * Git allows you to store your global configuration at + * `$HOME/.gitconfig` or `$XDG_CONFIG_HOME/git/config`. For backwards + * compatibility, the XDG file shouldn't be used unless the use has + * created it explicitly. With this function you'll open the correct + * one to write to. + * + * @param out pointer in which to store the config object + * @param config the config object in which to look + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_open_global(git_config **out, git_config *config); + +GIT_EXTERN(int) git_config_set_writeorder( + git_config *cfg, + git_config_level_t *levels, + size_t len); + +/** + * Create a snapshot of the configuration + * + * Create a snapshot of the current state of a configuration, which + * allows you to look into a consistent view of the configuration for + * looking up complex values (e.g. a remote, submodule). + * + * The string returned when querying such a config object is valid + * until it is freed. + * + * @param out pointer in which to store the snapshot config object + * @param config configuration to snapshot + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_snapshot(git_config **out, git_config *config); + +/** + * Free the configuration and its associated memory and files + * + * @param cfg the configuration to free + */ +GIT_EXTERN(void) git_config_free(git_config *cfg); + +/** + * Get the git_config_entry of a config variable. + * + * Free the git_config_entry after use with `git_config_entry_free()`. + * + * @param out pointer to the variable git_config_entry + * @param cfg where to look for the variable + * @param name the variable's name + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_get_entry( + git_config_entry **out, + const git_config *cfg, + const char *name); + +/** + * Get the value of an integer config variable. + * + * All config files will be looked into, in the order of their + * defined level. A higher level means a higher priority. The + * first occurrence of the variable will be returned here. + * + * @param out pointer to the variable where the value should be stored + * @param cfg where to look for the variable + * @param name the variable's name + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_get_int32(int32_t *out, const git_config *cfg, const char *name); + +/** + * Get the value of a long integer config variable. + * + * All config files will be looked into, in the order of their + * defined level. A higher level means a higher priority. The + * first occurrence of the variable will be returned here. + * + * @param out pointer to the variable where the value should be stored + * @param cfg where to look for the variable + * @param name the variable's name + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_get_int64(int64_t *out, const git_config *cfg, const char *name); + +/** + * Get the value of a boolean config variable. + * + * This function uses the usual C convention of 0 being false and + * anything else true. + * + * All config files will be looked into, in the order of their + * defined level. A higher level means a higher priority. The + * first occurrence of the variable will be returned here. + * + * @param out pointer to the variable where the value should be stored + * @param cfg where to look for the variable + * @param name the variable's name + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_get_bool(int *out, const git_config *cfg, const char *name); + +/** + * Get the value of a path config variable. + * + * A leading '~' will be expanded to the global search path (which + * defaults to the user's home directory but can be overridden via + * `git_libgit2_opts()`. + * + * All config files will be looked into, in the order of their + * defined level. A higher level means a higher priority. The + * first occurrence of the variable will be returned here. + * + * @param out the buffer in which to store the result + * @param cfg where to look for the variable + * @param name the variable's name + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_get_path(git_buf *out, const git_config *cfg, const char *name); + +/** + * Get the value of a string config variable. + * + * This function can only be used on snapshot config objects. The + * string is owned by the config and should not be freed by the + * user. The pointer will be valid until the config is freed. + * + * All config files will be looked into, in the order of their + * defined level. A higher level means a higher priority. The + * first occurrence of the variable will be returned here. + * + * @param out pointer to the string + * @param cfg where to look for the variable + * @param name the variable's name + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_get_string(const char **out, const git_config *cfg, const char *name); + +/** + * Get the value of a string config variable. + * + * The value of the config will be copied into the buffer. + * + * All config files will be looked into, in the order of their + * defined level. A higher level means a higher priority. The + * first occurrence of the variable will be returned here. + * + * @param out buffer in which to store the string + * @param cfg where to look for the variable + * @param name the variable's name + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_get_string_buf(git_buf *out, const git_config *cfg, const char *name); + +/** + * Get each value of a multivar in a foreach callback + * + * The callback will be called on each variable found + * + * The regular expression is applied case-sensitively on the normalized form of + * the variable name: the section and variable parts are lower-cased. The + * subsection is left unchanged. + * + * @param cfg where to look for the variable + * @param name the variable's name + * @param regexp regular expression to filter which variables we're + * interested in. Use NULL to indicate all + * @param callback the function to be called on each value of the variable + * @param payload opaque pointer to pass to the callback + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_get_multivar_foreach(const git_config *cfg, const char *name, const char *regexp, git_config_foreach_cb callback, void *payload); + +/** + * Get each value of a multivar + * + * The regular expression is applied case-sensitively on the normalized form of + * the variable name: the section and variable parts are lower-cased. The + * subsection is left unchanged. + * + * @param out pointer to store the iterator + * @param cfg where to look for the variable + * @param name the variable's name + * @param regexp regular expression to filter which variables we're + * interested in. Use NULL to indicate all + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_multivar_iterator_new(git_config_iterator **out, const git_config *cfg, const char *name, const char *regexp); + +/** + * Return the current entry and advance the iterator + * + * The pointers returned by this function are valid until the next call + * to `git_config_next` or until the iterator is freed. + * + * @param entry pointer to store the entry + * @param iter the iterator + * @return 0 or an error code. GIT_ITEROVER if the iteration has completed + */ +GIT_EXTERN(int) git_config_next(git_config_entry **entry, git_config_iterator *iter); + +/** + * Free a config iterator + * + * @param iter the iterator to free + */ +GIT_EXTERN(void) git_config_iterator_free(git_config_iterator *iter); + +/** + * Set the value of an integer config variable in the config file + * with the highest level (usually the local one). + * + * @param cfg where to look for the variable + * @param name the variable's name + * @param value Integer value for the variable + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_set_int32(git_config *cfg, const char *name, int32_t value); + +/** + * Set the value of a long integer config variable in the config file + * with the highest level (usually the local one). + * + * @param cfg where to look for the variable + * @param name the variable's name + * @param value Long integer value for the variable + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_set_int64(git_config *cfg, const char *name, int64_t value); + +/** + * Set the value of a boolean config variable in the config file + * with the highest level (usually the local one). + * + * @param cfg where to look for the variable + * @param name the variable's name + * @param value the value to store + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_set_bool(git_config *cfg, const char *name, int value); + +/** + * Set the value of a string config variable in the config file + * with the highest level (usually the local one). + * + * A copy of the string is made and the user is free to use it + * afterwards. + * + * @param cfg where to look for the variable + * @param name the variable's name + * @param value the string to store. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_set_string(git_config *cfg, const char *name, const char *value); + +/** + * Set a multivar in the local config file. + * + * The regular expression is applied case-sensitively on the value. + * + * @param cfg where to look for the variable + * @param name the variable's name + * @param regexp a regular expression to indicate which values to replace + * @param value the new value. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_set_multivar(git_config *cfg, const char *name, const char *regexp, const char *value); + +/** + * Delete a config variable from the config file + * with the highest level (usually the local one). + * + * @param cfg the configuration + * @param name the variable to delete + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_delete_entry(git_config *cfg, const char *name); + +/** + * Deletes one or several entries from a multivar in the local config file. + * + * The regular expression is applied case-sensitively on the value. + * + * @param cfg where to look for the variables + * @param name the variable's name + * @param regexp a regular expression to indicate which values to delete + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_delete_multivar(git_config *cfg, const char *name, const char *regexp); + +/** + * Perform an operation on each config variable. + * + * The callback receives the normalized name and value of each variable + * in the config backend, and the data pointer passed to this function. + * If the callback returns a non-zero value, the function stops iterating + * and returns that value to the caller. + * + * The pointers passed to the callback are only valid as long as the + * iteration is ongoing. + * + * @param cfg where to get the variables from + * @param callback the function to call on each variable + * @param payload the data to pass to the callback + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_config_foreach( + const git_config *cfg, + git_config_foreach_cb callback, + void *payload); + +/** + * Iterate over all the config variables + * + * Use `git_config_next` to advance the iteration and + * `git_config_iterator_free` when done. + * + * @param out pointer to store the iterator + * @param cfg where to get the variables from + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_iterator_new(git_config_iterator **out, const git_config *cfg); + +/** + * Iterate over all the config variables whose name matches a pattern + * + * Use `git_config_next` to advance the iteration and + * `git_config_iterator_free` when done. + * + * The regular expression is applied case-sensitively on the normalized form of + * the variable name: the section and variable parts are lower-cased. The + * subsection is left unchanged. + * + * @param out pointer to store the iterator + * @param cfg where to ge the variables from + * @param regexp regular expression to match the names + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator **out, const git_config *cfg, const char *regexp); + +/** + * Perform an operation on each config variable matching a regular expression. + * + * This behaves like `git_config_foreach` with an additional filter of a + * regular expression that filters which config keys are passed to the + * callback. + * + * The regular expression is applied case-sensitively on the normalized form of + * the variable name: the section and variable parts are lower-cased. The + * subsection is left unchanged. + * + * The regular expression is applied case-sensitively on the normalized form of + * the variable name: the case-insensitive parts are lower-case. + * + * @param cfg where to get the variables from + * @param regexp regular expression to match against config names + * @param callback the function to call on each variable + * @param payload the data to pass to the callback + * @return 0 or the return value of the callback which didn't return 0 + */ +GIT_EXTERN(int) git_config_foreach_match( + const git_config *cfg, + const char *regexp, + git_config_foreach_cb callback, + void *payload); + +/** + * Query the value of a config variable and return it mapped to + * an integer constant. + * + * This is a helper method to easily map different possible values + * to a variable to integer constants that easily identify them. + * + * A mapping array looks as follows: + * + * git_configmap autocrlf_mapping[] = { + * {GIT_CVAR_FALSE, NULL, GIT_AUTO_CRLF_FALSE}, + * {GIT_CVAR_TRUE, NULL, GIT_AUTO_CRLF_TRUE}, + * {GIT_CVAR_STRING, "input", GIT_AUTO_CRLF_INPUT}, + * {GIT_CVAR_STRING, "default", GIT_AUTO_CRLF_DEFAULT}}; + * + * On any "false" value for the variable (e.g. "false", "FALSE", "no"), the + * mapping will store `GIT_AUTO_CRLF_FALSE` in the `out` parameter. + * + * The same thing applies for any "true" value such as "true", "yes" or "1", storing + * the `GIT_AUTO_CRLF_TRUE` variable. + * + * Otherwise, if the value matches the string "input" (with case insensitive comparison), + * the given constant will be stored in `out`, and likewise for "default". + * + * If not a single match can be made to store in `out`, an error code will be + * returned. + * + * @param out place to store the result of the mapping + * @param cfg config file to get the variables from + * @param name name of the config variable to lookup + * @param maps array of `git_configmap` objects specifying the possible mappings + * @param map_n number of mapping objects in `maps` + * @return 0 on success, error code otherwise + */ +GIT_EXTERN(int) git_config_get_mapped( + int *out, + const git_config *cfg, + const char *name, + const git_configmap *maps, + size_t map_n); + +/** + * Maps a string value to an integer constant + * + * @param out place to store the result of the parsing + * @param maps array of `git_configmap` objects specifying the possible mappings + * @param map_n number of mapping objects in `maps` + * @param value value to parse + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_lookup_map_value( + int *out, + const git_configmap *maps, + size_t map_n, + const char *value); + +/** + * Parse a string value as a bool. + * + * Valid values for true are: 'true', 'yes', 'on', 1 or any + * number different from 0 + * Valid values for false are: 'false', 'no', 'off', 0 + * + * @param out place to store the result of the parsing + * @param value value to parse + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value); + +/** + * Parse a string value as an int32. + * + * An optional value suffix of 'k', 'm', or 'g' will + * cause the value to be multiplied by 1024, 1048576, + * or 1073741824 prior to output. + * + * @param out place to store the result of the parsing + * @param value value to parse + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value); + +/** + * Parse a string value as an int64. + * + * An optional value suffix of 'k', 'm', or 'g' will + * cause the value to be multiplied by 1024, 1048576, + * or 1073741824 prior to output. + * + * @param out place to store the result of the parsing + * @param value value to parse + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value); + +/** + * Parse a string value as a path. + * + * A leading '~' will be expanded to the global search path (which + * defaults to the user's home directory but can be overridden via + * `git_libgit2_opts()`. + * + * If the value does not begin with a tilde, the input will be + * returned. + * + * @param out placae to store the result of parsing + * @param value the path to evaluate + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_parse_path(git_buf *out, const char *value); + +/** + * Perform an operation on each config variable in a given config backend, + * matching a regular expression. + * + * This behaves like `git_config_foreach_match` except that only config + * entries from the given backend entry are enumerated. + * + * The regular expression is applied case-sensitively on the normalized form of + * the variable name: the section and variable parts are lower-cased. The + * subsection is left unchanged. + * + * @param backend where to get the variables from + * @param regexp regular expression to match against config names (can be NULL) + * @param callback the function to call on each variable + * @param payload the data to pass to the callback + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_config_backend_foreach_match( + git_config_backend *backend, + const char *regexp, + git_config_foreach_cb callback, + void *payload); + + +/** + * Lock the backend with the highest priority + * + * Locking disallows anybody else from writing to that backend. Any + * updates made after locking will not be visible to a reader until + * the file is unlocked. + * + * You can apply the changes by calling `git_transaction_commit()` + * before freeing the transaction. Either of these actions will unlock + * the config. + * + * @param tx the resulting transaction, use this to commit or undo the + * changes + * @param cfg the configuration in which to lock + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_lock(git_transaction **tx, git_config *cfg); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/cred_helpers.h b/3rdparty/libgit2/include/git2/cred_helpers.h index 3721b6d..880a58b 100644 --- a/3rdparty/libgit2/include/git2/cred_helpers.h +++ b/3rdparty/libgit2/include/git2/cred_helpers.h @@ -1,15 +1,15 @@ -/* - * 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_cred_helpers_h__ -#define INCLUDE_git_cred_helpers_h__ - -/* These declarations have moved. */ -#ifndef GIT_DEPRECATE_HARD -# include "git2/credential_helpers.h" -#endif - -#endif +/* + * 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_cred_helpers_h__ +#define INCLUDE_git_cred_helpers_h__ + +/* These declarations have moved. */ +#ifndef GIT_DEPRECATE_HARD +# include "git2/credential_helpers.h" +#endif + +#endif diff --git a/3rdparty/libgit2/include/git2/credential.h b/3rdparty/libgit2/include/git2/credential.h index 7a04bc0..a611501 100644 --- a/3rdparty/libgit2/include/git2/credential.h +++ b/3rdparty/libgit2/include/git2/credential.h @@ -1,315 +1,315 @@ -/* - * 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_credential_h__ -#define INCLUDE_git_credential_h__ - -#include "common.h" - -/** - * @file git2/credential.h - * @brief Git authentication & credential management - * @defgroup git_credential Authentication & credential management - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Supported credential types - * - * This represents the various types of authentication methods supported by - * the library. - */ -typedef enum { - /** - * A vanilla user/password request - * @see git_credential_userpass_plaintext_new - */ - GIT_CREDENTIAL_USERPASS_PLAINTEXT = (1u << 0), - - /** - * An SSH key-based authentication request - * @see git_credential_ssh_key_new - */ - GIT_CREDENTIAL_SSH_KEY = (1u << 1), - - /** - * An SSH key-based authentication request, with a custom signature - * @see git_credential_ssh_custom_new - */ - GIT_CREDENTIAL_SSH_CUSTOM = (1u << 2), - - /** - * An NTLM/Negotiate-based authentication request. - * @see git_credential_default - */ - GIT_CREDENTIAL_DEFAULT = (1u << 3), - - /** - * An SSH interactive authentication request - * @see git_credential_ssh_interactive_new - */ - GIT_CREDENTIAL_SSH_INTERACTIVE = (1u << 4), - - /** - * Username-only authentication request - * - * Used as a pre-authentication step if the underlying transport - * (eg. SSH, with no username in its URL) does not know which username - * to use. - * - * @see git_credential_username_new - */ - GIT_CREDENTIAL_USERNAME = (1u << 5), - - /** - * An SSH key-based authentication request - * - * Allows credentials to be read from memory instead of files. - * Note that because of differences in crypto backend support, it might - * not be functional. - * - * @see git_credential_ssh_key_memory_new - */ - GIT_CREDENTIAL_SSH_MEMORY = (1u << 6) -} git_credential_t; - -/** - * The base structure for all credential types - */ -typedef struct git_credential git_credential; - -typedef struct git_credential_userpass_plaintext git_credential_userpass_plaintext; - -/** Username-only credential information */ -typedef struct git_credential_username git_credential_username; - -/** A key for NTLM/Kerberos "default" credentials */ -typedef struct git_credential git_credential_default; - -/** - * A ssh key from disk - */ -typedef struct git_credential_ssh_key git_credential_ssh_key; - -/** - * Keyboard-interactive based ssh authentication - */ -typedef struct git_credential_ssh_interactive git_credential_ssh_interactive; - -/** - * A key with a custom signature function - */ -typedef struct git_credential_ssh_custom git_credential_ssh_custom; - -/** - * Credential acquisition callback. - * - * This callback is usually involved any time another system might need - * authentication. As such, you are expected to provide a valid - * git_credential object back, depending on allowed_types (a - * git_credential_t bitmask). - * - * Note that most authentication details are your responsibility - this - * callback will be called until the authentication succeeds, or you report - * an error. As such, it's easy to get in a loop if you fail to stop providing - * the same incorrect credentials. - * - * @param out The newly created credential object. - * @param url The resource for which we are demanding a credential. - * @param username_from_url The username that was embedded in a "user\@host" - * remote url, or NULL if not included. - * @param allowed_types A bitmask stating which credential types are OK to return. - * @param payload The payload provided when specifying this callback. - * @return 0 for success, < 0 to indicate an error, > 0 to indicate - * no credential was acquired - */ -typedef int GIT_CALLBACK(git_credential_acquire_cb)( - git_credential **out, - const char *url, - const char *username_from_url, - unsigned int allowed_types, - void *payload); - -/** - * Free a credential. - * - * This is only necessary if you own the object; that is, if you are a - * transport. - * - * @param cred the object to free - */ -GIT_EXTERN(void) git_credential_free(git_credential *cred); - -/** - * Check whether a credential object contains username information. - * - * @param cred object to check - * @return 1 if the credential object has non-NULL username, 0 otherwise - */ -GIT_EXTERN(int) git_credential_has_username(git_credential *cred); - -/** - * Return the username associated with a credential object. - * - * @param cred object to check - * @return the credential username, or NULL if not applicable - */ -GIT_EXTERN(const char *) git_credential_get_username(git_credential *cred); - -/** - * Create a new plain-text username and password credential object. - * The supplied credential parameter will be internally duplicated. - * - * @param out The newly created credential object. - * @param username The username of the credential. - * @param password The password of the credential. - * @return 0 for success or an error code for failure - */ -GIT_EXTERN(int) git_credential_userpass_plaintext_new( - git_credential **out, - const char *username, - const char *password); - -/** - * Create a "default" credential usable for Negotiate mechanisms like NTLM - * or Kerberos authentication. - * - * @param out The newly created credential object. - * @return 0 for success or an error code for failure - */ -GIT_EXTERN(int) git_credential_default_new(git_credential **out); - -/** - * Create a credential to specify a username. - * - * This is used with ssh authentication to query for the username if - * none is specified in the url. - * - * @param out The newly created credential object. - * @param username The username to authenticate with - * @return 0 for success or an error code for failure - */ -GIT_EXTERN(int) git_credential_username_new(git_credential **out, const char *username); - -/** - * Create a new passphrase-protected ssh key credential object. - * The supplied credential parameter will be internally duplicated. - * - * @param out The newly created credential object. - * @param username username to use to authenticate - * @param publickey The path to the public key of the credential. - * @param privatekey The path to the private key of the credential. - * @param passphrase The passphrase of the credential. - * @return 0 for success or an error code for failure - */ -GIT_EXTERN(int) git_credential_ssh_key_new( - git_credential **out, - const char *username, - const char *publickey, - const char *privatekey, - const char *passphrase); - -/** - * Create a new ssh key credential object reading the keys from memory. - * - * @param out The newly created credential object. - * @param username username to use to authenticate. - * @param publickey The public key of the credential. - * @param privatekey The private key of the credential. - * @param passphrase The passphrase of the credential. - * @return 0 for success or an error code for failure - */ -GIT_EXTERN(int) git_credential_ssh_key_memory_new( - git_credential **out, - const char *username, - const char *publickey, - const char *privatekey, - const char *passphrase); - -/* - * If the user hasn't included libssh2.h before git2.h, we need to - * define a few types for the callback signatures. - */ -#ifndef LIBSSH2_VERSION -typedef struct _LIBSSH2_SESSION LIBSSH2_SESSION; -typedef struct _LIBSSH2_USERAUTH_KBDINT_PROMPT LIBSSH2_USERAUTH_KBDINT_PROMPT; -typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE LIBSSH2_USERAUTH_KBDINT_RESPONSE; -#endif - -typedef void GIT_CALLBACK(git_credential_ssh_interactive_cb)( - const char *name, - int name_len, - const char *instruction, int instruction_len, - int num_prompts, const LIBSSH2_USERAUTH_KBDINT_PROMPT *prompts, - LIBSSH2_USERAUTH_KBDINT_RESPONSE *responses, - void **abstract); - - -/** - * Create a new ssh keyboard-interactive based credential object. - * The supplied credential parameter will be internally duplicated. - * - * @param out The newly created credential object. - * @param username Username to use to authenticate. - * @param prompt_callback The callback method used for prompts. - * @param payload Additional data to pass to the callback. - * @return 0 for success or an error code for failure. - */ -GIT_EXTERN(int) git_credential_ssh_interactive_new( - git_credential **out, - const char *username, - git_credential_ssh_interactive_cb prompt_callback, - void *payload); - -/** - * Create a new ssh key credential object used for querying an ssh-agent. - * The supplied credential parameter will be internally duplicated. - * - * @param out The newly created credential object. - * @param username username to use to authenticate - * @return 0 for success or an error code for failure - */ -GIT_EXTERN(int) git_credential_ssh_key_from_agent( - git_credential **out, - const char *username); - -typedef int GIT_CALLBACK(git_credential_sign_cb)( - LIBSSH2_SESSION *session, - unsigned char **sig, size_t *sig_len, - const unsigned char *data, size_t data_len, - void **abstract); - -/** - * Create an ssh key credential with a custom signing function. - * - * This lets you use your own function to sign the challenge. - * - * This function and its credential type is provided for completeness - * and wraps `libssh2_userauth_publickey()`, which is undocumented. - * - * The supplied credential parameter will be internally duplicated. - * - * @param out The newly created credential object. - * @param username username to use to authenticate - * @param publickey The bytes of the public key. - * @param publickey_len The length of the public key in bytes. - * @param sign_callback The callback method to sign the data during the challenge. - * @param payload Additional data to pass to the callback. - * @return 0 for success or an error code for failure - */ -GIT_EXTERN(int) git_credential_ssh_custom_new( - git_credential **out, - const char *username, - const char *publickey, - size_t publickey_len, - git_credential_sign_cb sign_callback, - void *payload); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_credential_h__ +#define INCLUDE_git_credential_h__ + +#include "common.h" + +/** + * @file git2/credential.h + * @brief Git authentication & credential management + * @defgroup git_credential Authentication & credential management + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Supported credential types + * + * This represents the various types of authentication methods supported by + * the library. + */ +typedef enum { + /** + * A vanilla user/password request + * @see git_credential_userpass_plaintext_new + */ + GIT_CREDENTIAL_USERPASS_PLAINTEXT = (1u << 0), + + /** + * An SSH key-based authentication request + * @see git_credential_ssh_key_new + */ + GIT_CREDENTIAL_SSH_KEY = (1u << 1), + + /** + * An SSH key-based authentication request, with a custom signature + * @see git_credential_ssh_custom_new + */ + GIT_CREDENTIAL_SSH_CUSTOM = (1u << 2), + + /** + * An NTLM/Negotiate-based authentication request. + * @see git_credential_default + */ + GIT_CREDENTIAL_DEFAULT = (1u << 3), + + /** + * An SSH interactive authentication request + * @see git_credential_ssh_interactive_new + */ + GIT_CREDENTIAL_SSH_INTERACTIVE = (1u << 4), + + /** + * Username-only authentication request + * + * Used as a pre-authentication step if the underlying transport + * (eg. SSH, with no username in its URL) does not know which username + * to use. + * + * @see git_credential_username_new + */ + GIT_CREDENTIAL_USERNAME = (1u << 5), + + /** + * An SSH key-based authentication request + * + * Allows credentials to be read from memory instead of files. + * Note that because of differences in crypto backend support, it might + * not be functional. + * + * @see git_credential_ssh_key_memory_new + */ + GIT_CREDENTIAL_SSH_MEMORY = (1u << 6) +} git_credential_t; + +/** + * The base structure for all credential types + */ +typedef struct git_credential git_credential; + +typedef struct git_credential_userpass_plaintext git_credential_userpass_plaintext; + +/** Username-only credential information */ +typedef struct git_credential_username git_credential_username; + +/** A key for NTLM/Kerberos "default" credentials */ +typedef struct git_credential git_credential_default; + +/** + * A ssh key from disk + */ +typedef struct git_credential_ssh_key git_credential_ssh_key; + +/** + * Keyboard-interactive based ssh authentication + */ +typedef struct git_credential_ssh_interactive git_credential_ssh_interactive; + +/** + * A key with a custom signature function + */ +typedef struct git_credential_ssh_custom git_credential_ssh_custom; + +/** + * Credential acquisition callback. + * + * This callback is usually involved any time another system might need + * authentication. As such, you are expected to provide a valid + * git_credential object back, depending on allowed_types (a + * git_credential_t bitmask). + * + * Note that most authentication details are your responsibility - this + * callback will be called until the authentication succeeds, or you report + * an error. As such, it's easy to get in a loop if you fail to stop providing + * the same incorrect credentials. + * + * @param out The newly created credential object. + * @param url The resource for which we are demanding a credential. + * @param username_from_url The username that was embedded in a "user\@host" + * remote url, or NULL if not included. + * @param allowed_types A bitmask stating which credential types are OK to return. + * @param payload The payload provided when specifying this callback. + * @return 0 for success, < 0 to indicate an error, > 0 to indicate + * no credential was acquired + */ +typedef int GIT_CALLBACK(git_credential_acquire_cb)( + git_credential **out, + const char *url, + const char *username_from_url, + unsigned int allowed_types, + void *payload); + +/** + * Free a credential. + * + * This is only necessary if you own the object; that is, if you are a + * transport. + * + * @param cred the object to free + */ +GIT_EXTERN(void) git_credential_free(git_credential *cred); + +/** + * Check whether a credential object contains username information. + * + * @param cred object to check + * @return 1 if the credential object has non-NULL username, 0 otherwise + */ +GIT_EXTERN(int) git_credential_has_username(git_credential *cred); + +/** + * Return the username associated with a credential object. + * + * @param cred object to check + * @return the credential username, or NULL if not applicable + */ +GIT_EXTERN(const char *) git_credential_get_username(git_credential *cred); + +/** + * Create a new plain-text username and password credential object. + * The supplied credential parameter will be internally duplicated. + * + * @param out The newly created credential object. + * @param username The username of the credential. + * @param password The password of the credential. + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_credential_userpass_plaintext_new( + git_credential **out, + const char *username, + const char *password); + +/** + * Create a "default" credential usable for Negotiate mechanisms like NTLM + * or Kerberos authentication. + * + * @param out The newly created credential object. + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_credential_default_new(git_credential **out); + +/** + * Create a credential to specify a username. + * + * This is used with ssh authentication to query for the username if + * none is specified in the url. + * + * @param out The newly created credential object. + * @param username The username to authenticate with + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_credential_username_new(git_credential **out, const char *username); + +/** + * Create a new passphrase-protected ssh key credential object. + * The supplied credential parameter will be internally duplicated. + * + * @param out The newly created credential object. + * @param username username to use to authenticate + * @param publickey The path to the public key of the credential. + * @param privatekey The path to the private key of the credential. + * @param passphrase The passphrase of the credential. + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_credential_ssh_key_new( + git_credential **out, + const char *username, + const char *publickey, + const char *privatekey, + const char *passphrase); + +/** + * Create a new ssh key credential object reading the keys from memory. + * + * @param out The newly created credential object. + * @param username username to use to authenticate. + * @param publickey The public key of the credential. + * @param privatekey The private key of the credential. + * @param passphrase The passphrase of the credential. + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_credential_ssh_key_memory_new( + git_credential **out, + const char *username, + const char *publickey, + const char *privatekey, + const char *passphrase); + +/* + * If the user hasn't included libssh2.h before git2.h, we need to + * define a few types for the callback signatures. + */ +#ifndef LIBSSH2_VERSION +typedef struct _LIBSSH2_SESSION LIBSSH2_SESSION; +typedef struct _LIBSSH2_USERAUTH_KBDINT_PROMPT LIBSSH2_USERAUTH_KBDINT_PROMPT; +typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE LIBSSH2_USERAUTH_KBDINT_RESPONSE; +#endif + +typedef void GIT_CALLBACK(git_credential_ssh_interactive_cb)( + const char *name, + int name_len, + const char *instruction, int instruction_len, + int num_prompts, const LIBSSH2_USERAUTH_KBDINT_PROMPT *prompts, + LIBSSH2_USERAUTH_KBDINT_RESPONSE *responses, + void **abstract); + + +/** + * Create a new ssh keyboard-interactive based credential object. + * The supplied credential parameter will be internally duplicated. + * + * @param out The newly created credential object. + * @param username Username to use to authenticate. + * @param prompt_callback The callback method used for prompts. + * @param payload Additional data to pass to the callback. + * @return 0 for success or an error code for failure. + */ +GIT_EXTERN(int) git_credential_ssh_interactive_new( + git_credential **out, + const char *username, + git_credential_ssh_interactive_cb prompt_callback, + void *payload); + +/** + * Create a new ssh key credential object used for querying an ssh-agent. + * The supplied credential parameter will be internally duplicated. + * + * @param out The newly created credential object. + * @param username username to use to authenticate + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_credential_ssh_key_from_agent( + git_credential **out, + const char *username); + +typedef int GIT_CALLBACK(git_credential_sign_cb)( + LIBSSH2_SESSION *session, + unsigned char **sig, size_t *sig_len, + const unsigned char *data, size_t data_len, + void **abstract); + +/** + * Create an ssh key credential with a custom signing function. + * + * This lets you use your own function to sign the challenge. + * + * This function and its credential type is provided for completeness + * and wraps `libssh2_userauth_publickey()`, which is undocumented. + * + * The supplied credential parameter will be internally duplicated. + * + * @param out The newly created credential object. + * @param username username to use to authenticate + * @param publickey The bytes of the public key. + * @param publickey_len The length of the public key in bytes. + * @param sign_callback The callback method to sign the data during the challenge. + * @param payload Additional data to pass to the callback. + * @return 0 for success or an error code for failure + */ +GIT_EXTERN(int) git_credential_ssh_custom_new( + git_credential **out, + const char *username, + const char *publickey, + size_t publickey_len, + git_credential_sign_cb sign_callback, + void *payload); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/credential_helpers.h b/3rdparty/libgit2/include/git2/credential_helpers.h index f0fb070..36b342a 100644 --- a/3rdparty/libgit2/include/git2/credential_helpers.h +++ b/3rdparty/libgit2/include/git2/credential_helpers.h @@ -1,53 +1,53 @@ -/* - * 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_credential_helpers_h__ -#define INCLUDE_git_credential_helpers_h__ - -#include "transport.h" - -/** - * @file git2/credential_helpers.h - * @brief Utility functions for credential management - * @defgroup git_credential_helpers credential management helpers - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Payload for git_credential_userpass_plaintext. - */ -typedef struct git_credential_userpass_payload { - const char *username; - const char *password; -} git_credential_userpass_payload; - - -/** - * Stock callback usable as a git_credential_acquire_cb. This calls - * git_cred_userpass_plaintext_new unless the protocol has not specified - * `GIT_CREDENTIAL_USERPASS_PLAINTEXT` as an allowed type. - * - * @param out The newly created credential object. - * @param url The resource for which we are demanding a credential. - * @param user_from_url The username that was embedded in a "user\@host" - * remote url, or NULL if not included. - * @param allowed_types A bitmask stating which credential types are OK to return. - * @param payload The payload provided when specifying this callback. (This is - * interpreted as a `git_credential_userpass_payload*`.) - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_credential_userpass( - git_credential **out, - const char *url, - const char *user_from_url, - unsigned int allowed_types, - void *payload); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_credential_helpers_h__ +#define INCLUDE_git_credential_helpers_h__ + +#include "transport.h" + +/** + * @file git2/credential_helpers.h + * @brief Utility functions for credential management + * @defgroup git_credential_helpers credential management helpers + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Payload for git_credential_userpass_plaintext. + */ +typedef struct git_credential_userpass_payload { + const char *username; + const char *password; +} git_credential_userpass_payload; + + +/** + * Stock callback usable as a git_credential_acquire_cb. This calls + * git_cred_userpass_plaintext_new unless the protocol has not specified + * `GIT_CREDENTIAL_USERPASS_PLAINTEXT` as an allowed type. + * + * @param out The newly created credential object. + * @param url The resource for which we are demanding a credential. + * @param user_from_url The username that was embedded in a "user\@host" + * remote url, or NULL if not included. + * @param allowed_types A bitmask stating which credential types are OK to return. + * @param payload The payload provided when specifying this callback. (This is + * interpreted as a `git_credential_userpass_payload*`.) + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_credential_userpass( + git_credential **out, + const char *url, + const char *user_from_url, + unsigned int allowed_types, + void *payload); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/deprecated.h b/3rdparty/libgit2/include/git2/deprecated.h index 52864eb..15f34a0 100644 --- a/3rdparty/libgit2/include/git2/deprecated.h +++ b/3rdparty/libgit2/include/git2/deprecated.h @@ -1,939 +1,939 @@ -/* - * 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_deprecated_h__ -#define INCLUDE_git_deprecated_h__ - -#include "attr.h" -#include "config.h" -#include "common.h" -#include "blame.h" -#include "buffer.h" -#include "checkout.h" -#include "cherrypick.h" -#include "clone.h" -#include "describe.h" -#include "diff.h" -#include "errors.h" -#include "filter.h" -#include "index.h" -#include "indexer.h" -#include "merge.h" -#include "object.h" -#include "proxy.h" -#include "refs.h" -#include "rebase.h" -#include "remote.h" -#include "trace.h" -#include "repository.h" -#include "revert.h" -#include "revparse.h" -#include "stash.h" -#include "status.h" -#include "submodule.h" -#include "worktree.h" -#include "credential.h" -#include "credential_helpers.h" - -/* - * Users can avoid deprecated functions by defining `GIT_DEPRECATE_HARD`. - */ -#ifndef GIT_DEPRECATE_HARD - -/* - * The credential structures are now opaque by default, and their - * definition has moved into the `sys/credential.h` header; include - * them here for backward compatibility. - */ -#include "sys/credential.h" - -/** - * @file git2/deprecated.h - * @brief libgit2 deprecated functions and values - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** @name Deprecated Attribute Constants - * - * These enumeration values are retained for backward compatibility. - * The newer versions of these functions should be preferred in all - * new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -#define GIT_ATTR_UNSPECIFIED_T GIT_ATTR_VALUE_UNSPECIFIED -#define GIT_ATTR_TRUE_T GIT_ATTR_VALUE_TRUE -#define GIT_ATTR_FALSE_T GIT_ATTR_VALUE_FALSE -#define GIT_ATTR_VALUE_T GIT_ATTR_VALUE_STRING - -#define GIT_ATTR_TRUE(attr) GIT_ATTR_IS_TRUE(attr) -#define GIT_ATTR_FALSE(attr) GIT_ATTR_IS_FALSE(attr) -#define GIT_ATTR_UNSPECIFIED(attr) GIT_ATTR_IS_UNSPECIFIED(attr) - -typedef git_attr_value_t git_attr_t; - -/**@}*/ - -/** @name Deprecated Blob Functions and Constants - * - * These functions and enumeration values are retained for backward - * compatibility. The newer versions of these functions and values - * should be preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -#define GIT_BLOB_FILTER_ATTTRIBUTES_FROM_HEAD GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD - -GIT_EXTERN(int) git_blob_create_fromworkdir(git_oid *id, git_repository *repo, const char *relative_path); -GIT_EXTERN(int) git_blob_create_fromdisk(git_oid *id, git_repository *repo, const char *path); -GIT_EXTERN(int) git_blob_create_fromstream( - git_writestream **out, - git_repository *repo, - const char *hintpath); -GIT_EXTERN(int) git_blob_create_fromstream_commit( - git_oid *out, - git_writestream *stream); -GIT_EXTERN(int) git_blob_create_frombuffer( - git_oid *id, git_repository *repo, const void *buffer, size_t len); - -/** Deprecated in favor of `git_blob_filter`. - * - * @deprecated Use git_blob_filter - * @see git_blob_filter - */ -GIT_EXTERN(int) git_blob_filtered_content( - git_buf *out, - git_blob *blob, - const char *as_path, - int check_for_binary_data); - -/**@}*/ - -/** @name Deprecated Filter Functions - * - * These functions are retained for backward compatibility. The - * newer versions of these functions should be preferred in all - * new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -/** Deprecated in favor of `git_filter_list_stream_buffer`. - * - * @deprecated Use git_filter_list_stream_buffer - * @see Use git_filter_list_stream_buffer - */ -GIT_EXTERN(int) git_filter_list_stream_data( - git_filter_list *filters, - git_buf *data, - git_writestream *target); - -/** Deprecated in favor of `git_filter_list_apply_to_buffer`. - * - * @deprecated Use git_filter_list_apply_to_buffer - * @see Use git_filter_list_apply_to_buffer - */ -GIT_EXTERN(int) git_filter_list_apply_to_data( - git_buf *out, - git_filter_list *filters, - git_buf *in); - -/**@}*/ - -/** @name Deprecated Tree Functions - * - * These functions are retained for backward compatibility. The - * newer versions of these functions and values should be preferred - * in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -/** - * Write the contents of the tree builder as a tree object. - * This is an alias of `git_treebuilder_write` and is preserved - * for backward compatibility. - * - * This function is deprecated, but there is no plan to remove this - * function at this time. - * - * @deprecated Use git_treebuilder_write - * @see git_treebuilder_write - */ -GIT_EXTERN(int) git_treebuilder_write_with_buffer( - git_oid *oid, git_treebuilder *bld, git_buf *tree); - -/**@}*/ - -/** @name Deprecated Buffer Functions - * - * These functions and enumeration values are retained for backward - * compatibility. The newer versions of these functions should be - * preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -/** - * Static initializer for git_buf from static buffer - */ -#define GIT_BUF_INIT_CONST(STR,LEN) { (char *)(STR), 0, (size_t)(LEN) } - -/** - * Resize the buffer allocation to make more space. - * - * This will attempt to grow the buffer to accommodate the target size. - * - * If the buffer refers to memory that was not allocated by libgit2 (i.e. - * the `asize` field is zero), then `ptr` will be replaced with a newly - * allocated block of data. Be careful so that memory allocated by the - * caller is not lost. As a special variant, if you pass `target_size` as - * 0 and the memory is not allocated by libgit2, this will allocate a new - * buffer of size `size` and copy the external data into it. - * - * Currently, this will never shrink a buffer, only expand it. - * - * If the allocation fails, this will return an error and the buffer will be - * marked as invalid for future operations, invaliding the contents. - * - * @param buffer The buffer to be resized; may or may not be allocated yet - * @param target_size The desired available size - * @return 0 on success, -1 on allocation failure - */ -GIT_EXTERN(int) git_buf_grow(git_buf *buffer, size_t target_size); - -/** - * Set buffer to a copy of some raw data. - * - * @param buffer The buffer to set - * @param data The data to copy into the buffer - * @param datalen The length of the data to copy into the buffer - * @return 0 on success, -1 on allocation failure - */ -GIT_EXTERN(int) git_buf_set( - git_buf *buffer, const void *data, size_t datalen); - -/** -* Check quickly if buffer looks like it contains binary data -* -* @param buf Buffer to check -* @return 1 if buffer looks like non-text data -*/ -GIT_EXTERN(int) git_buf_is_binary(const git_buf *buf); - -/** -* Check quickly if buffer contains a NUL byte -* -* @param buf Buffer to check -* @return 1 if buffer contains a NUL byte -*/ -GIT_EXTERN(int) git_buf_contains_nul(const git_buf *buf); - -/** - * Free the memory referred to by the git_buf. This is an alias of - * `git_buf_dispose` and is preserved for backward compatibility. - * - * This function is deprecated, but there is no plan to remove this - * function at this time. - * - * @deprecated Use git_buf_dispose - * @see git_buf_dispose - */ -GIT_EXTERN(void) git_buf_free(git_buf *buffer); - -/**@}*/ - -/** @name Deprecated Commit Definitions - */ -/**@{*/ - -/** - * Provide a commit signature during commit creation. - * - * Callers should instead define a `git_commit_create_cb` that - * generates a commit buffer using `git_commit_create_buffer`, sign - * that buffer and call `git_commit_create_with_signature`. - * - * @deprecated use a `git_commit_create_cb` instead - */ -typedef int (*git_commit_signing_cb)( - git_buf *signature, - git_buf *signature_field, - const char *commit_content, - void *payload); - -/**@}*/ - -/** @name Deprecated Config Functions and Constants - */ -/**@{*/ - -#define GIT_CVAR_FALSE GIT_CONFIGMAP_FALSE -#define GIT_CVAR_TRUE GIT_CONFIGMAP_TRUE -#define GIT_CVAR_INT32 GIT_CONFIGMAP_INT32 -#define GIT_CVAR_STRING GIT_CONFIGMAP_STRING - -typedef git_configmap git_cvar_map; - -/**@}*/ - -/** @name Deprecated Diff Functions and Constants - * - * These functions and enumeration values are retained for backward - * compatibility. The newer versions of these functions and values - * should be preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -/** - * Formatting options for diff e-mail generation - */ -typedef enum { - /** Normal patch, the default */ - GIT_DIFF_FORMAT_EMAIL_NONE = 0, - - /** Don't insert "[PATCH]" in the subject header*/ - GIT_DIFF_FORMAT_EMAIL_EXCLUDE_SUBJECT_PATCH_MARKER = (1 << 0) - -} git_diff_format_email_flags_t; - -/** - * Options for controlling the formatting of the generated e-mail. - */ -typedef struct { - unsigned int version; - - /** see `git_diff_format_email_flags_t` above */ - uint32_t flags; - - /** This patch number */ - size_t patch_no; - - /** Total number of patches in this series */ - size_t total_patches; - - /** id to use for the commit */ - const git_oid *id; - - /** Summary of the change */ - const char *summary; - - /** Commit message's body */ - const char *body; - - /** Author of the change */ - const git_signature *author; -} git_diff_format_email_options; - -#define GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION 1 -#define GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT {GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION, 0, 1, 1, NULL, NULL, NULL, NULL} - -/** - * Create an e-mail ready patch from a diff. - * - * @deprecated git_email_create_from_diff - * @see git_email_create_from_diff - */ -GIT_EXTERN(int) git_diff_format_email( - git_buf *out, - git_diff *diff, - const git_diff_format_email_options *opts); - -/** - * Create an e-mail ready patch for a commit. - * - * @deprecated git_email_create_from_commit - * @see git_email_create_from_commit - */ -GIT_EXTERN(int) git_diff_commit_as_email( - git_buf *out, - git_repository *repo, - git_commit *commit, - size_t patch_no, - size_t total_patches, - uint32_t flags, - const git_diff_options *diff_opts); - -/** - * Initialize git_diff_format_email_options structure - * - * Initializes a `git_diff_format_email_options` with default values. Equivalent - * to creating an instance with GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT. - * - * @param opts The `git_blame_options` struct to initialize. - * @param version The struct version; pass `GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_diff_format_email_options_init( - git_diff_format_email_options *opts, - unsigned int version); - -/**@}*/ - -/** @name Deprecated Error Functions and Constants - * - * These functions and enumeration values are retained for backward - * compatibility. The newer versions of these functions and values - * should be preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -#define GITERR_NONE GIT_ERROR_NONE -#define GITERR_NOMEMORY GIT_ERROR_NOMEMORY -#define GITERR_OS GIT_ERROR_OS -#define GITERR_INVALID GIT_ERROR_INVALID -#define GITERR_REFERENCE GIT_ERROR_REFERENCE -#define GITERR_ZLIB GIT_ERROR_ZLIB -#define GITERR_REPOSITORY GIT_ERROR_REPOSITORY -#define GITERR_CONFIG GIT_ERROR_CONFIG -#define GITERR_REGEX GIT_ERROR_REGEX -#define GITERR_ODB GIT_ERROR_ODB -#define GITERR_INDEX GIT_ERROR_INDEX -#define GITERR_OBJECT GIT_ERROR_OBJECT -#define GITERR_NET GIT_ERROR_NET -#define GITERR_TAG GIT_ERROR_TAG -#define GITERR_TREE GIT_ERROR_TREE -#define GITERR_INDEXER GIT_ERROR_INDEXER -#define GITERR_SSL GIT_ERROR_SSL -#define GITERR_SUBMODULE GIT_ERROR_SUBMODULE -#define GITERR_THREAD GIT_ERROR_THREAD -#define GITERR_STASH GIT_ERROR_STASH -#define GITERR_CHECKOUT GIT_ERROR_CHECKOUT -#define GITERR_FETCHHEAD GIT_ERROR_FETCHHEAD -#define GITERR_MERGE GIT_ERROR_MERGE -#define GITERR_SSH GIT_ERROR_SSH -#define GITERR_FILTER GIT_ERROR_FILTER -#define GITERR_REVERT GIT_ERROR_REVERT -#define GITERR_CALLBACK GIT_ERROR_CALLBACK -#define GITERR_CHERRYPICK GIT_ERROR_CHERRYPICK -#define GITERR_DESCRIBE GIT_ERROR_DESCRIBE -#define GITERR_REBASE GIT_ERROR_REBASE -#define GITERR_FILESYSTEM GIT_ERROR_FILESYSTEM -#define GITERR_PATCH GIT_ERROR_PATCH -#define GITERR_WORKTREE GIT_ERROR_WORKTREE -#define GITERR_SHA1 GIT_ERROR_SHA1 - -#define GIT_ERROR_SHA1 GIT_ERROR_SHA - -/** - * Return the last `git_error` object that was generated for the - * current thread. This is an alias of `git_error_last` and is - * preserved for backward compatibility. - * - * This function is deprecated, but there is no plan to remove this - * function at this time. - * - * @deprecated Use git_error_last - * @see git_error_last - */ -GIT_EXTERN(const git_error *) giterr_last(void); - -/** - * Clear the last error. This is an alias of `git_error_last` and is - * preserved for backward compatibility. - * - * This function is deprecated, but there is no plan to remove this - * function at this time. - * - * @deprecated Use git_error_clear - * @see git_error_clear - */ -GIT_EXTERN(void) giterr_clear(void); - -/** - * Sets the error message to the given string. This is an alias of - * `git_error_set_str` and is preserved for backward compatibility. - * - * This function is deprecated, but there is no plan to remove this - * function at this time. - * - * @deprecated Use git_error_set_str - * @see git_error_set_str - */ -GIT_EXTERN(void) giterr_set_str(int error_class, const char *string); - -/** - * Indicates that an out-of-memory situation occurred. This is an alias - * of `git_error_set_oom` and is preserved for backward compatibility. - * - * This function is deprecated, but there is no plan to remove this - * function at this time. - * - * @deprecated Use git_error_set_oom - * @see git_error_set_oom - */ -GIT_EXTERN(void) giterr_set_oom(void); - -/**@}*/ - -/** @name Deprecated Index Functions and Constants - * - * These functions and enumeration values are retained for backward - * compatibility. The newer versions of these values should be - * preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -#define GIT_IDXENTRY_NAMEMASK GIT_INDEX_ENTRY_NAMEMASK -#define GIT_IDXENTRY_STAGEMASK GIT_INDEX_ENTRY_STAGEMASK -#define GIT_IDXENTRY_STAGESHIFT GIT_INDEX_ENTRY_STAGESHIFT - -/* The git_indxentry_flag_t enum */ -#define GIT_IDXENTRY_EXTENDED GIT_INDEX_ENTRY_EXTENDED -#define GIT_IDXENTRY_VALID GIT_INDEX_ENTRY_VALID - -#define GIT_IDXENTRY_STAGE(E) GIT_INDEX_ENTRY_STAGE(E) -#define GIT_IDXENTRY_STAGE_SET(E,S) GIT_INDEX_ENTRY_STAGE_SET(E,S) - -/* The git_idxentry_extended_flag_t enum */ -#define GIT_IDXENTRY_INTENT_TO_ADD GIT_INDEX_ENTRY_INTENT_TO_ADD -#define GIT_IDXENTRY_SKIP_WORKTREE GIT_INDEX_ENTRY_SKIP_WORKTREE -#define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_INDEX_ENTRY_INTENT_TO_ADD | GIT_INDEX_ENTRY_SKIP_WORKTREE) -#define GIT_IDXENTRY_EXTENDED2 (1 << 15) -#define GIT_IDXENTRY_UPDATE (1 << 0) -#define GIT_IDXENTRY_REMOVE (1 << 1) -#define GIT_IDXENTRY_UPTODATE (1 << 2) -#define GIT_IDXENTRY_ADDED (1 << 3) -#define GIT_IDXENTRY_HASHED (1 << 4) -#define GIT_IDXENTRY_UNHASHED (1 << 5) -#define GIT_IDXENTRY_WT_REMOVE (1 << 6) -#define GIT_IDXENTRY_CONFLICTED (1 << 7) -#define GIT_IDXENTRY_UNPACKED (1 << 8) -#define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9) - -/* The git_index_capability_t enum */ -#define GIT_INDEXCAP_IGNORE_CASE GIT_INDEX_CAPABILITY_IGNORE_CASE -#define GIT_INDEXCAP_NO_FILEMODE GIT_INDEX_CAPABILITY_NO_FILEMODE -#define GIT_INDEXCAP_NO_SYMLINKS GIT_INDEX_CAPABILITY_NO_SYMLINKS -#define GIT_INDEXCAP_FROM_OWNER GIT_INDEX_CAPABILITY_FROM_OWNER - -GIT_EXTERN(int) git_index_add_frombuffer( - git_index *index, - const git_index_entry *entry, - const void *buffer, size_t len); - -/**@}*/ - -/** @name Deprecated Object Constants - * - * These enumeration values are retained for backward compatibility. The - * newer versions of these values should be preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -#define git_otype git_object_t - -#define GIT_OBJ_ANY GIT_OBJECT_ANY -#define GIT_OBJ_BAD GIT_OBJECT_INVALID -#define GIT_OBJ__EXT1 0 -#define GIT_OBJ_COMMIT GIT_OBJECT_COMMIT -#define GIT_OBJ_TREE GIT_OBJECT_TREE -#define GIT_OBJ_BLOB GIT_OBJECT_BLOB -#define GIT_OBJ_TAG GIT_OBJECT_TAG -#define GIT_OBJ__EXT2 5 -#define GIT_OBJ_OFS_DELTA GIT_OBJECT_OFS_DELTA -#define GIT_OBJ_REF_DELTA GIT_OBJECT_REF_DELTA - -/** - * Get the size in bytes for the structure which - * acts as an in-memory representation of any given - * object type. - * - * For all the core types, this would the equivalent - * of calling `sizeof(git_commit)` if the core types - * were not opaque on the external API. - * - * @param type object type to get its size - * @return size in bytes of the object - */ -GIT_EXTERN(size_t) git_object__size(git_object_t type); - -/**@}*/ - -/** @name Deprecated Remote Functions - * - * These functions are retained for backward compatibility. The newer - * versions of these functions should be preferred in all new code. - * - * There is no plan to remove these backward compatibility functions at - * this time. - */ -/**@{*/ - -/** - * Ensure the remote name is well-formed. - * - * @deprecated Use git_remote_name_is_valid - * @param remote_name name to be checked. - * @return 1 if the reference name is acceptable; 0 if it isn't - */ -GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name); - -/**@}*/ - -/** @name Deprecated Reference Functions and Constants - * - * These functions and enumeration values are retained for backward - * compatibility. The newer versions of these values should be - * preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - - /** Basic type of any Git reference. */ -#define git_ref_t git_reference_t -#define git_reference_normalize_t git_reference_format_t - -#define GIT_REF_INVALID GIT_REFERENCE_INVALID -#define GIT_REF_OID GIT_REFERENCE_DIRECT -#define GIT_REF_SYMBOLIC GIT_REFERENCE_SYMBOLIC -#define GIT_REF_LISTALL GIT_REFERENCE_ALL - -#define GIT_REF_FORMAT_NORMAL GIT_REFERENCE_FORMAT_NORMAL -#define GIT_REF_FORMAT_ALLOW_ONELEVEL GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL -#define GIT_REF_FORMAT_REFSPEC_PATTERN GIT_REFERENCE_FORMAT_REFSPEC_PATTERN -#define GIT_REF_FORMAT_REFSPEC_SHORTHAND GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND - -/** - * Ensure the reference name is well-formed. - * - * Valid reference names must follow one of two patterns: - * - * 1. Top-level names must contain only capital letters and underscores, - * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). - * 2. Names prefixed with "refs/" can be almost anything. You must avoid - * the characters '~', '^', ':', '\\', '?', '[', and '*', and the - * sequences ".." and "@{" which have special meaning to revparse. - * - * @deprecated Use git_reference_name_is_valid - * @param refname name to be checked. - * @return 1 if the reference name is acceptable; 0 if it isn't - */ -GIT_EXTERN(int) git_reference_is_valid_name(const char *refname); - -GIT_EXTERN(int) git_tag_create_frombuffer( - git_oid *oid, - git_repository *repo, - const char *buffer, - int force); - -/**@}*/ - -/** @name Deprecated Revspec Constants - * - * These enumeration values are retained for backward compatibility. - * The newer versions of these values should be preferred in all new - * code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -typedef git_revspec_t git_revparse_mode_t; - -#define GIT_REVPARSE_SINGLE GIT_REVSPEC_SINGLE -#define GIT_REVPARSE_RANGE GIT_REVSPEC_RANGE -#define GIT_REVPARSE_MERGE_BASE GIT_REVSPEC_MERGE_BASE - -/**@}*/ - -/** @name Deprecated Credential Types - * - * These types are retained for backward compatibility. The newer - * versions of these values should be preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -typedef git_credential git_cred; -typedef git_credential_userpass_plaintext git_cred_userpass_plaintext; -typedef git_credential_username git_cred_username; -typedef git_credential_default git_cred_default; -typedef git_credential_ssh_key git_cred_ssh_key; -typedef git_credential_ssh_interactive git_cred_ssh_interactive; -typedef git_credential_ssh_custom git_cred_ssh_custom; - -typedef git_credential_acquire_cb git_cred_acquire_cb; -typedef git_credential_sign_cb git_cred_sign_callback; -typedef git_credential_sign_cb git_cred_sign_cb; -typedef git_credential_ssh_interactive_cb git_cred_ssh_interactive_callback; -typedef git_credential_ssh_interactive_cb git_cred_ssh_interactive_cb; - -#define git_credtype_t git_credential_t - -#define GIT_CREDTYPE_USERPASS_PLAINTEXT GIT_CREDENTIAL_USERPASS_PLAINTEXT -#define GIT_CREDTYPE_SSH_KEY GIT_CREDENTIAL_SSH_KEY -#define GIT_CREDTYPE_SSH_CUSTOM GIT_CREDENTIAL_SSH_CUSTOM -#define GIT_CREDTYPE_DEFAULT GIT_CREDENTIAL_DEFAULT -#define GIT_CREDTYPE_SSH_INTERACTIVE GIT_CREDENTIAL_SSH_INTERACTIVE -#define GIT_CREDTYPE_USERNAME GIT_CREDENTIAL_USERNAME -#define GIT_CREDTYPE_SSH_MEMORY GIT_CREDENTIAL_SSH_MEMORY - -GIT_EXTERN(void) git_cred_free(git_credential *cred); -GIT_EXTERN(int) git_cred_has_username(git_credential *cred); -GIT_EXTERN(const char *) git_cred_get_username(git_credential *cred); -GIT_EXTERN(int) git_cred_userpass_plaintext_new( - git_credential **out, - const char *username, - const char *password); -GIT_EXTERN(int) git_cred_default_new(git_credential **out); -GIT_EXTERN(int) git_cred_username_new(git_credential **out, const char *username); -GIT_EXTERN(int) git_cred_ssh_key_new( - git_credential **out, - const char *username, - const char *publickey, - const char *privatekey, - const char *passphrase); -GIT_EXTERN(int) git_cred_ssh_key_memory_new( - git_credential **out, - const char *username, - const char *publickey, - const char *privatekey, - const char *passphrase); -GIT_EXTERN(int) git_cred_ssh_interactive_new( - git_credential **out, - const char *username, - git_credential_ssh_interactive_cb prompt_callback, - void *payload); -GIT_EXTERN(int) git_cred_ssh_key_from_agent( - git_credential **out, - const char *username); -GIT_EXTERN(int) git_cred_ssh_custom_new( - git_credential **out, - const char *username, - const char *publickey, - size_t publickey_len, - git_credential_sign_cb sign_callback, - void *payload); - -/* Deprecated Credential Helper Types */ - -typedef git_credential_userpass_payload git_cred_userpass_payload; - -GIT_EXTERN(int) git_cred_userpass( - git_credential **out, - const char *url, - const char *user_from_url, - unsigned int allowed_types, - void *payload); - -/**@}*/ - -/** @name Deprecated Trace Callback Types - * - * These types are retained for backward compatibility. The newer - * versions of these values should be preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -typedef git_trace_cb git_trace_callback; - -/**@}*/ - -/** @name Deprecated Object ID Types - * - * These types are retained for backward compatibility. The newer - * versions of these values should be preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -#ifndef GIT_EXPERIMENTAL_SHA256 -# define GIT_OID_RAWSZ GIT_OID_SHA1_SIZE -# define GIT_OID_HEXSZ GIT_OID_SHA1_HEXSIZE -# define GIT_OID_HEX_ZERO GIT_OID_SHA1_HEXZERO -#endif - -GIT_EXTERN(int) git_oid_iszero(const git_oid *id); - -/**@}*/ - -/** @name Deprecated OID Array Functions - * - * These types are retained for backward compatibility. The newer - * versions of these values should be preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -/** - * Free the memory referred to by the git_oidarray. This is an alias of - * `git_oidarray_dispose` and is preserved for backward compatibility. - * - * This function is deprecated, but there is no plan to remove this - * function at this time. - * - * @deprecated Use git_oidarray_dispose - * @see git_oidarray_dispose - */ -GIT_EXTERN(void) git_oidarray_free(git_oidarray *array); - -/**@}*/ - -/** @name Deprecated Transfer Progress Types - * - * These types are retained for backward compatibility. The newer - * versions of these values should be preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -/** - * This structure is used to provide callers information about the - * progress of indexing a packfile. - * - * This type is deprecated, but there is no plan to remove this - * type definition at this time. - */ -typedef git_indexer_progress git_transfer_progress; - -/** - * Type definition for progress callbacks during indexing. - * - * This type is deprecated, but there is no plan to remove this - * type definition at this time. - */ -typedef git_indexer_progress_cb git_transfer_progress_cb; - -/** - * Type definition for push transfer progress callbacks. - * - * This type is deprecated, but there is no plan to remove this - * type definition at this time. - */ -typedef git_push_transfer_progress_cb git_push_transfer_progress; - - /** The type of a remote completion event */ -#define git_remote_completion_type git_remote_completion_t - -/** - * Callback for listing the remote heads - */ -typedef int GIT_CALLBACK(git_headlist_cb)(git_remote_head *rhead, void *payload); - -/**@}*/ - -/** @name Deprecated String Array Functions - * - * These types are retained for backward compatibility. The newer - * versions of these values should be preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -/** - * Copy a string array object from source to target. - * - * This function is deprecated, but there is no plan to remove this - * function at this time. - * - * @param tgt target - * @param src source - * @return 0 on success, < 0 on allocation failure - */ -GIT_EXTERN(int) git_strarray_copy(git_strarray *tgt, const git_strarray *src); - -/** - * Free the memory referred to by the git_strarray. This is an alias of - * `git_strarray_dispose` and is preserved for backward compatibility. - * - * This function is deprecated, but there is no plan to remove this - * function at this time. - * - * @deprecated Use git_strarray_dispose - * @see git_strarray_dispose - */ -GIT_EXTERN(void) git_strarray_free(git_strarray *array); - -/**@}*/ - -/** @name Deprecated Options Initialization Functions - * - * These functions are retained for backward compatibility. The newer - * versions of these functions should be preferred in all new code. - * - * There is no plan to remove these backward compatibility functions at - * this time. - */ -/**@{*/ - -GIT_EXTERN(int) git_blame_init_options(git_blame_options *opts, unsigned int version); -GIT_EXTERN(int) git_checkout_init_options(git_checkout_options *opts, unsigned int version); -GIT_EXTERN(int) git_cherrypick_init_options(git_cherrypick_options *opts, unsigned int version); -GIT_EXTERN(int) git_clone_init_options(git_clone_options *opts, unsigned int version); -GIT_EXTERN(int) git_describe_init_options(git_describe_options *opts, unsigned int version); -GIT_EXTERN(int) git_describe_init_format_options(git_describe_format_options *opts, unsigned int version); -GIT_EXTERN(int) git_diff_init_options(git_diff_options *opts, unsigned int version); -GIT_EXTERN(int) git_diff_find_init_options(git_diff_find_options *opts, unsigned int version); -GIT_EXTERN(int) git_diff_format_email_init_options(git_diff_format_email_options *opts, unsigned int version); -GIT_EXTERN(int) git_diff_patchid_init_options(git_diff_patchid_options *opts, unsigned int version); -GIT_EXTERN(int) git_fetch_init_options(git_fetch_options *opts, unsigned int version); -GIT_EXTERN(int) git_indexer_init_options(git_indexer_options *opts, unsigned int version); -GIT_EXTERN(int) git_merge_init_options(git_merge_options *opts, unsigned int version); -GIT_EXTERN(int) git_merge_file_init_input(git_merge_file_input *input, unsigned int version); -GIT_EXTERN(int) git_merge_file_init_options(git_merge_file_options *opts, unsigned int version); -GIT_EXTERN(int) git_proxy_init_options(git_proxy_options *opts, unsigned int version); -GIT_EXTERN(int) git_push_init_options(git_push_options *opts, unsigned int version); -GIT_EXTERN(int) git_rebase_init_options(git_rebase_options *opts, unsigned int version); -GIT_EXTERN(int) git_remote_create_init_options(git_remote_create_options *opts, unsigned int version); -GIT_EXTERN(int) git_repository_init_init_options(git_repository_init_options *opts, unsigned int version); -GIT_EXTERN(int) git_revert_init_options(git_revert_options *opts, unsigned int version); -GIT_EXTERN(int) git_stash_apply_init_options(git_stash_apply_options *opts, unsigned int version); -GIT_EXTERN(int) git_status_init_options(git_status_options *opts, unsigned int version); -GIT_EXTERN(int) git_submodule_update_init_options(git_submodule_update_options *opts, unsigned int version); -GIT_EXTERN(int) git_worktree_add_init_options(git_worktree_add_options *opts, unsigned int version); -GIT_EXTERN(int) git_worktree_prune_init_options(git_worktree_prune_options *opts, unsigned int version); - -/**@}*/ - -/** @} */ -GIT_END_DECL - -#endif - -#endif +/* + * 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_deprecated_h__ +#define INCLUDE_git_deprecated_h__ + +#include "attr.h" +#include "config.h" +#include "common.h" +#include "blame.h" +#include "buffer.h" +#include "checkout.h" +#include "cherrypick.h" +#include "clone.h" +#include "describe.h" +#include "diff.h" +#include "errors.h" +#include "filter.h" +#include "index.h" +#include "indexer.h" +#include "merge.h" +#include "object.h" +#include "proxy.h" +#include "refs.h" +#include "rebase.h" +#include "remote.h" +#include "trace.h" +#include "repository.h" +#include "revert.h" +#include "revparse.h" +#include "stash.h" +#include "status.h" +#include "submodule.h" +#include "worktree.h" +#include "credential.h" +#include "credential_helpers.h" + +/* + * Users can avoid deprecated functions by defining `GIT_DEPRECATE_HARD`. + */ +#ifndef GIT_DEPRECATE_HARD + +/* + * The credential structures are now opaque by default, and their + * definition has moved into the `sys/credential.h` header; include + * them here for backward compatibility. + */ +#include "sys/credential.h" + +/** + * @file git2/deprecated.h + * @brief libgit2 deprecated functions and values + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** @name Deprecated Attribute Constants + * + * These enumeration values are retained for backward compatibility. + * The newer versions of these functions should be preferred in all + * new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +#define GIT_ATTR_UNSPECIFIED_T GIT_ATTR_VALUE_UNSPECIFIED +#define GIT_ATTR_TRUE_T GIT_ATTR_VALUE_TRUE +#define GIT_ATTR_FALSE_T GIT_ATTR_VALUE_FALSE +#define GIT_ATTR_VALUE_T GIT_ATTR_VALUE_STRING + +#define GIT_ATTR_TRUE(attr) GIT_ATTR_IS_TRUE(attr) +#define GIT_ATTR_FALSE(attr) GIT_ATTR_IS_FALSE(attr) +#define GIT_ATTR_UNSPECIFIED(attr) GIT_ATTR_IS_UNSPECIFIED(attr) + +typedef git_attr_value_t git_attr_t; + +/**@}*/ + +/** @name Deprecated Blob Functions and Constants + * + * These functions and enumeration values are retained for backward + * compatibility. The newer versions of these functions and values + * should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +#define GIT_BLOB_FILTER_ATTTRIBUTES_FROM_HEAD GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD + +GIT_EXTERN(int) git_blob_create_fromworkdir(git_oid *id, git_repository *repo, const char *relative_path); +GIT_EXTERN(int) git_blob_create_fromdisk(git_oid *id, git_repository *repo, const char *path); +GIT_EXTERN(int) git_blob_create_fromstream( + git_writestream **out, + git_repository *repo, + const char *hintpath); +GIT_EXTERN(int) git_blob_create_fromstream_commit( + git_oid *out, + git_writestream *stream); +GIT_EXTERN(int) git_blob_create_frombuffer( + git_oid *id, git_repository *repo, const void *buffer, size_t len); + +/** Deprecated in favor of `git_blob_filter`. + * + * @deprecated Use git_blob_filter + * @see git_blob_filter + */ +GIT_EXTERN(int) git_blob_filtered_content( + git_buf *out, + git_blob *blob, + const char *as_path, + int check_for_binary_data); + +/**@}*/ + +/** @name Deprecated Filter Functions + * + * These functions are retained for backward compatibility. The + * newer versions of these functions should be preferred in all + * new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** Deprecated in favor of `git_filter_list_stream_buffer`. + * + * @deprecated Use git_filter_list_stream_buffer + * @see Use git_filter_list_stream_buffer + */ +GIT_EXTERN(int) git_filter_list_stream_data( + git_filter_list *filters, + git_buf *data, + git_writestream *target); + +/** Deprecated in favor of `git_filter_list_apply_to_buffer`. + * + * @deprecated Use git_filter_list_apply_to_buffer + * @see Use git_filter_list_apply_to_buffer + */ +GIT_EXTERN(int) git_filter_list_apply_to_data( + git_buf *out, + git_filter_list *filters, + git_buf *in); + +/**@}*/ + +/** @name Deprecated Tree Functions + * + * These functions are retained for backward compatibility. The + * newer versions of these functions and values should be preferred + * in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** + * Write the contents of the tree builder as a tree object. + * This is an alias of `git_treebuilder_write` and is preserved + * for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Use git_treebuilder_write + * @see git_treebuilder_write + */ +GIT_EXTERN(int) git_treebuilder_write_with_buffer( + git_oid *oid, git_treebuilder *bld, git_buf *tree); + +/**@}*/ + +/** @name Deprecated Buffer Functions + * + * These functions and enumeration values are retained for backward + * compatibility. The newer versions of these functions should be + * preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** + * Static initializer for git_buf from static buffer + */ +#define GIT_BUF_INIT_CONST(STR,LEN) { (char *)(STR), 0, (size_t)(LEN) } + +/** + * Resize the buffer allocation to make more space. + * + * This will attempt to grow the buffer to accommodate the target size. + * + * If the buffer refers to memory that was not allocated by libgit2 (i.e. + * the `asize` field is zero), then `ptr` will be replaced with a newly + * allocated block of data. Be careful so that memory allocated by the + * caller is not lost. As a special variant, if you pass `target_size` as + * 0 and the memory is not allocated by libgit2, this will allocate a new + * buffer of size `size` and copy the external data into it. + * + * Currently, this will never shrink a buffer, only expand it. + * + * If the allocation fails, this will return an error and the buffer will be + * marked as invalid for future operations, invaliding the contents. + * + * @param buffer The buffer to be resized; may or may not be allocated yet + * @param target_size The desired available size + * @return 0 on success, -1 on allocation failure + */ +GIT_EXTERN(int) git_buf_grow(git_buf *buffer, size_t target_size); + +/** + * Set buffer to a copy of some raw data. + * + * @param buffer The buffer to set + * @param data The data to copy into the buffer + * @param datalen The length of the data to copy into the buffer + * @return 0 on success, -1 on allocation failure + */ +GIT_EXTERN(int) git_buf_set( + git_buf *buffer, const void *data, size_t datalen); + +/** +* Check quickly if buffer looks like it contains binary data +* +* @param buf Buffer to check +* @return 1 if buffer looks like non-text data +*/ +GIT_EXTERN(int) git_buf_is_binary(const git_buf *buf); + +/** +* Check quickly if buffer contains a NUL byte +* +* @param buf Buffer to check +* @return 1 if buffer contains a NUL byte +*/ +GIT_EXTERN(int) git_buf_contains_nul(const git_buf *buf); + +/** + * Free the memory referred to by the git_buf. This is an alias of + * `git_buf_dispose` and is preserved for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Use git_buf_dispose + * @see git_buf_dispose + */ +GIT_EXTERN(void) git_buf_free(git_buf *buffer); + +/**@}*/ + +/** @name Deprecated Commit Definitions + */ +/**@{*/ + +/** + * Provide a commit signature during commit creation. + * + * Callers should instead define a `git_commit_create_cb` that + * generates a commit buffer using `git_commit_create_buffer`, sign + * that buffer and call `git_commit_create_with_signature`. + * + * @deprecated use a `git_commit_create_cb` instead + */ +typedef int (*git_commit_signing_cb)( + git_buf *signature, + git_buf *signature_field, + const char *commit_content, + void *payload); + +/**@}*/ + +/** @name Deprecated Config Functions and Constants + */ +/**@{*/ + +#define GIT_CVAR_FALSE GIT_CONFIGMAP_FALSE +#define GIT_CVAR_TRUE GIT_CONFIGMAP_TRUE +#define GIT_CVAR_INT32 GIT_CONFIGMAP_INT32 +#define GIT_CVAR_STRING GIT_CONFIGMAP_STRING + +typedef git_configmap git_cvar_map; + +/**@}*/ + +/** @name Deprecated Diff Functions and Constants + * + * These functions and enumeration values are retained for backward + * compatibility. The newer versions of these functions and values + * should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** + * Formatting options for diff e-mail generation + */ +typedef enum { + /** Normal patch, the default */ + GIT_DIFF_FORMAT_EMAIL_NONE = 0, + + /** Don't insert "[PATCH]" in the subject header*/ + GIT_DIFF_FORMAT_EMAIL_EXCLUDE_SUBJECT_PATCH_MARKER = (1 << 0) + +} git_diff_format_email_flags_t; + +/** + * Options for controlling the formatting of the generated e-mail. + */ +typedef struct { + unsigned int version; + + /** see `git_diff_format_email_flags_t` above */ + uint32_t flags; + + /** This patch number */ + size_t patch_no; + + /** Total number of patches in this series */ + size_t total_patches; + + /** id to use for the commit */ + const git_oid *id; + + /** Summary of the change */ + const char *summary; + + /** Commit message's body */ + const char *body; + + /** Author of the change */ + const git_signature *author; +} git_diff_format_email_options; + +#define GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION 1 +#define GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT {GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION, 0, 1, 1, NULL, NULL, NULL, NULL} + +/** + * Create an e-mail ready patch from a diff. + * + * @deprecated git_email_create_from_diff + * @see git_email_create_from_diff + */ +GIT_EXTERN(int) git_diff_format_email( + git_buf *out, + git_diff *diff, + const git_diff_format_email_options *opts); + +/** + * Create an e-mail ready patch for a commit. + * + * @deprecated git_email_create_from_commit + * @see git_email_create_from_commit + */ +GIT_EXTERN(int) git_diff_commit_as_email( + git_buf *out, + git_repository *repo, + git_commit *commit, + size_t patch_no, + size_t total_patches, + uint32_t flags, + const git_diff_options *diff_opts); + +/** + * Initialize git_diff_format_email_options structure + * + * Initializes a `git_diff_format_email_options` with default values. Equivalent + * to creating an instance with GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT. + * + * @param opts The `git_blame_options` struct to initialize. + * @param version The struct version; pass `GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_diff_format_email_options_init( + git_diff_format_email_options *opts, + unsigned int version); + +/**@}*/ + +/** @name Deprecated Error Functions and Constants + * + * These functions and enumeration values are retained for backward + * compatibility. The newer versions of these functions and values + * should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +#define GITERR_NONE GIT_ERROR_NONE +#define GITERR_NOMEMORY GIT_ERROR_NOMEMORY +#define GITERR_OS GIT_ERROR_OS +#define GITERR_INVALID GIT_ERROR_INVALID +#define GITERR_REFERENCE GIT_ERROR_REFERENCE +#define GITERR_ZLIB GIT_ERROR_ZLIB +#define GITERR_REPOSITORY GIT_ERROR_REPOSITORY +#define GITERR_CONFIG GIT_ERROR_CONFIG +#define GITERR_REGEX GIT_ERROR_REGEX +#define GITERR_ODB GIT_ERROR_ODB +#define GITERR_INDEX GIT_ERROR_INDEX +#define GITERR_OBJECT GIT_ERROR_OBJECT +#define GITERR_NET GIT_ERROR_NET +#define GITERR_TAG GIT_ERROR_TAG +#define GITERR_TREE GIT_ERROR_TREE +#define GITERR_INDEXER GIT_ERROR_INDEXER +#define GITERR_SSL GIT_ERROR_SSL +#define GITERR_SUBMODULE GIT_ERROR_SUBMODULE +#define GITERR_THREAD GIT_ERROR_THREAD +#define GITERR_STASH GIT_ERROR_STASH +#define GITERR_CHECKOUT GIT_ERROR_CHECKOUT +#define GITERR_FETCHHEAD GIT_ERROR_FETCHHEAD +#define GITERR_MERGE GIT_ERROR_MERGE +#define GITERR_SSH GIT_ERROR_SSH +#define GITERR_FILTER GIT_ERROR_FILTER +#define GITERR_REVERT GIT_ERROR_REVERT +#define GITERR_CALLBACK GIT_ERROR_CALLBACK +#define GITERR_CHERRYPICK GIT_ERROR_CHERRYPICK +#define GITERR_DESCRIBE GIT_ERROR_DESCRIBE +#define GITERR_REBASE GIT_ERROR_REBASE +#define GITERR_FILESYSTEM GIT_ERROR_FILESYSTEM +#define GITERR_PATCH GIT_ERROR_PATCH +#define GITERR_WORKTREE GIT_ERROR_WORKTREE +#define GITERR_SHA1 GIT_ERROR_SHA1 + +#define GIT_ERROR_SHA1 GIT_ERROR_SHA + +/** + * Return the last `git_error` object that was generated for the + * current thread. This is an alias of `git_error_last` and is + * preserved for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Use git_error_last + * @see git_error_last + */ +GIT_EXTERN(const git_error *) giterr_last(void); + +/** + * Clear the last error. This is an alias of `git_error_last` and is + * preserved for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Use git_error_clear + * @see git_error_clear + */ +GIT_EXTERN(void) giterr_clear(void); + +/** + * Sets the error message to the given string. This is an alias of + * `git_error_set_str` and is preserved for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Use git_error_set_str + * @see git_error_set_str + */ +GIT_EXTERN(void) giterr_set_str(int error_class, const char *string); + +/** + * Indicates that an out-of-memory situation occurred. This is an alias + * of `git_error_set_oom` and is preserved for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Use git_error_set_oom + * @see git_error_set_oom + */ +GIT_EXTERN(void) giterr_set_oom(void); + +/**@}*/ + +/** @name Deprecated Index Functions and Constants + * + * These functions and enumeration values are retained for backward + * compatibility. The newer versions of these values should be + * preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +#define GIT_IDXENTRY_NAMEMASK GIT_INDEX_ENTRY_NAMEMASK +#define GIT_IDXENTRY_STAGEMASK GIT_INDEX_ENTRY_STAGEMASK +#define GIT_IDXENTRY_STAGESHIFT GIT_INDEX_ENTRY_STAGESHIFT + +/* The git_indxentry_flag_t enum */ +#define GIT_IDXENTRY_EXTENDED GIT_INDEX_ENTRY_EXTENDED +#define GIT_IDXENTRY_VALID GIT_INDEX_ENTRY_VALID + +#define GIT_IDXENTRY_STAGE(E) GIT_INDEX_ENTRY_STAGE(E) +#define GIT_IDXENTRY_STAGE_SET(E,S) GIT_INDEX_ENTRY_STAGE_SET(E,S) + +/* The git_idxentry_extended_flag_t enum */ +#define GIT_IDXENTRY_INTENT_TO_ADD GIT_INDEX_ENTRY_INTENT_TO_ADD +#define GIT_IDXENTRY_SKIP_WORKTREE GIT_INDEX_ENTRY_SKIP_WORKTREE +#define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_INDEX_ENTRY_INTENT_TO_ADD | GIT_INDEX_ENTRY_SKIP_WORKTREE) +#define GIT_IDXENTRY_EXTENDED2 (1 << 15) +#define GIT_IDXENTRY_UPDATE (1 << 0) +#define GIT_IDXENTRY_REMOVE (1 << 1) +#define GIT_IDXENTRY_UPTODATE (1 << 2) +#define GIT_IDXENTRY_ADDED (1 << 3) +#define GIT_IDXENTRY_HASHED (1 << 4) +#define GIT_IDXENTRY_UNHASHED (1 << 5) +#define GIT_IDXENTRY_WT_REMOVE (1 << 6) +#define GIT_IDXENTRY_CONFLICTED (1 << 7) +#define GIT_IDXENTRY_UNPACKED (1 << 8) +#define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9) + +/* The git_index_capability_t enum */ +#define GIT_INDEXCAP_IGNORE_CASE GIT_INDEX_CAPABILITY_IGNORE_CASE +#define GIT_INDEXCAP_NO_FILEMODE GIT_INDEX_CAPABILITY_NO_FILEMODE +#define GIT_INDEXCAP_NO_SYMLINKS GIT_INDEX_CAPABILITY_NO_SYMLINKS +#define GIT_INDEXCAP_FROM_OWNER GIT_INDEX_CAPABILITY_FROM_OWNER + +GIT_EXTERN(int) git_index_add_frombuffer( + git_index *index, + const git_index_entry *entry, + const void *buffer, size_t len); + +/**@}*/ + +/** @name Deprecated Object Constants + * + * These enumeration values are retained for backward compatibility. The + * newer versions of these values should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +#define git_otype git_object_t + +#define GIT_OBJ_ANY GIT_OBJECT_ANY +#define GIT_OBJ_BAD GIT_OBJECT_INVALID +#define GIT_OBJ__EXT1 0 +#define GIT_OBJ_COMMIT GIT_OBJECT_COMMIT +#define GIT_OBJ_TREE GIT_OBJECT_TREE +#define GIT_OBJ_BLOB GIT_OBJECT_BLOB +#define GIT_OBJ_TAG GIT_OBJECT_TAG +#define GIT_OBJ__EXT2 5 +#define GIT_OBJ_OFS_DELTA GIT_OBJECT_OFS_DELTA +#define GIT_OBJ_REF_DELTA GIT_OBJECT_REF_DELTA + +/** + * Get the size in bytes for the structure which + * acts as an in-memory representation of any given + * object type. + * + * For all the core types, this would the equivalent + * of calling `sizeof(git_commit)` if the core types + * were not opaque on the external API. + * + * @param type object type to get its size + * @return size in bytes of the object + */ +GIT_EXTERN(size_t) git_object__size(git_object_t type); + +/**@}*/ + +/** @name Deprecated Remote Functions + * + * These functions are retained for backward compatibility. The newer + * versions of these functions should be preferred in all new code. + * + * There is no plan to remove these backward compatibility functions at + * this time. + */ +/**@{*/ + +/** + * Ensure the remote name is well-formed. + * + * @deprecated Use git_remote_name_is_valid + * @param remote_name name to be checked. + * @return 1 if the reference name is acceptable; 0 if it isn't + */ +GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name); + +/**@}*/ + +/** @name Deprecated Reference Functions and Constants + * + * These functions and enumeration values are retained for backward + * compatibility. The newer versions of these values should be + * preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + + /** Basic type of any Git reference. */ +#define git_ref_t git_reference_t +#define git_reference_normalize_t git_reference_format_t + +#define GIT_REF_INVALID GIT_REFERENCE_INVALID +#define GIT_REF_OID GIT_REFERENCE_DIRECT +#define GIT_REF_SYMBOLIC GIT_REFERENCE_SYMBOLIC +#define GIT_REF_LISTALL GIT_REFERENCE_ALL + +#define GIT_REF_FORMAT_NORMAL GIT_REFERENCE_FORMAT_NORMAL +#define GIT_REF_FORMAT_ALLOW_ONELEVEL GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL +#define GIT_REF_FORMAT_REFSPEC_PATTERN GIT_REFERENCE_FORMAT_REFSPEC_PATTERN +#define GIT_REF_FORMAT_REFSPEC_SHORTHAND GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND + +/** + * Ensure the reference name is well-formed. + * + * Valid reference names must follow one of two patterns: + * + * 1. Top-level names must contain only capital letters and underscores, + * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). + * 2. Names prefixed with "refs/" can be almost anything. You must avoid + * the characters '~', '^', ':', '\\', '?', '[', and '*', and the + * sequences ".." and "@{" which have special meaning to revparse. + * + * @deprecated Use git_reference_name_is_valid + * @param refname name to be checked. + * @return 1 if the reference name is acceptable; 0 if it isn't + */ +GIT_EXTERN(int) git_reference_is_valid_name(const char *refname); + +GIT_EXTERN(int) git_tag_create_frombuffer( + git_oid *oid, + git_repository *repo, + const char *buffer, + int force); + +/**@}*/ + +/** @name Deprecated Revspec Constants + * + * These enumeration values are retained for backward compatibility. + * The newer versions of these values should be preferred in all new + * code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +typedef git_revspec_t git_revparse_mode_t; + +#define GIT_REVPARSE_SINGLE GIT_REVSPEC_SINGLE +#define GIT_REVPARSE_RANGE GIT_REVSPEC_RANGE +#define GIT_REVPARSE_MERGE_BASE GIT_REVSPEC_MERGE_BASE + +/**@}*/ + +/** @name Deprecated Credential Types + * + * These types are retained for backward compatibility. The newer + * versions of these values should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +typedef git_credential git_cred; +typedef git_credential_userpass_plaintext git_cred_userpass_plaintext; +typedef git_credential_username git_cred_username; +typedef git_credential_default git_cred_default; +typedef git_credential_ssh_key git_cred_ssh_key; +typedef git_credential_ssh_interactive git_cred_ssh_interactive; +typedef git_credential_ssh_custom git_cred_ssh_custom; + +typedef git_credential_acquire_cb git_cred_acquire_cb; +typedef git_credential_sign_cb git_cred_sign_callback; +typedef git_credential_sign_cb git_cred_sign_cb; +typedef git_credential_ssh_interactive_cb git_cred_ssh_interactive_callback; +typedef git_credential_ssh_interactive_cb git_cred_ssh_interactive_cb; + +#define git_credtype_t git_credential_t + +#define GIT_CREDTYPE_USERPASS_PLAINTEXT GIT_CREDENTIAL_USERPASS_PLAINTEXT +#define GIT_CREDTYPE_SSH_KEY GIT_CREDENTIAL_SSH_KEY +#define GIT_CREDTYPE_SSH_CUSTOM GIT_CREDENTIAL_SSH_CUSTOM +#define GIT_CREDTYPE_DEFAULT GIT_CREDENTIAL_DEFAULT +#define GIT_CREDTYPE_SSH_INTERACTIVE GIT_CREDENTIAL_SSH_INTERACTIVE +#define GIT_CREDTYPE_USERNAME GIT_CREDENTIAL_USERNAME +#define GIT_CREDTYPE_SSH_MEMORY GIT_CREDENTIAL_SSH_MEMORY + +GIT_EXTERN(void) git_cred_free(git_credential *cred); +GIT_EXTERN(int) git_cred_has_username(git_credential *cred); +GIT_EXTERN(const char *) git_cred_get_username(git_credential *cred); +GIT_EXTERN(int) git_cred_userpass_plaintext_new( + git_credential **out, + const char *username, + const char *password); +GIT_EXTERN(int) git_cred_default_new(git_credential **out); +GIT_EXTERN(int) git_cred_username_new(git_credential **out, const char *username); +GIT_EXTERN(int) git_cred_ssh_key_new( + git_credential **out, + const char *username, + const char *publickey, + const char *privatekey, + const char *passphrase); +GIT_EXTERN(int) git_cred_ssh_key_memory_new( + git_credential **out, + const char *username, + const char *publickey, + const char *privatekey, + const char *passphrase); +GIT_EXTERN(int) git_cred_ssh_interactive_new( + git_credential **out, + const char *username, + git_credential_ssh_interactive_cb prompt_callback, + void *payload); +GIT_EXTERN(int) git_cred_ssh_key_from_agent( + git_credential **out, + const char *username); +GIT_EXTERN(int) git_cred_ssh_custom_new( + git_credential **out, + const char *username, + const char *publickey, + size_t publickey_len, + git_credential_sign_cb sign_callback, + void *payload); + +/* Deprecated Credential Helper Types */ + +typedef git_credential_userpass_payload git_cred_userpass_payload; + +GIT_EXTERN(int) git_cred_userpass( + git_credential **out, + const char *url, + const char *user_from_url, + unsigned int allowed_types, + void *payload); + +/**@}*/ + +/** @name Deprecated Trace Callback Types + * + * These types are retained for backward compatibility. The newer + * versions of these values should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +typedef git_trace_cb git_trace_callback; + +/**@}*/ + +/** @name Deprecated Object ID Types + * + * These types are retained for backward compatibility. The newer + * versions of these values should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +#ifndef GIT_EXPERIMENTAL_SHA256 +# define GIT_OID_RAWSZ GIT_OID_SHA1_SIZE +# define GIT_OID_HEXSZ GIT_OID_SHA1_HEXSIZE +# define GIT_OID_HEX_ZERO GIT_OID_SHA1_HEXZERO +#endif + +GIT_EXTERN(int) git_oid_iszero(const git_oid *id); + +/**@}*/ + +/** @name Deprecated OID Array Functions + * + * These types are retained for backward compatibility. The newer + * versions of these values should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** + * Free the memory referred to by the git_oidarray. This is an alias of + * `git_oidarray_dispose` and is preserved for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Use git_oidarray_dispose + * @see git_oidarray_dispose + */ +GIT_EXTERN(void) git_oidarray_free(git_oidarray *array); + +/**@}*/ + +/** @name Deprecated Transfer Progress Types + * + * These types are retained for backward compatibility. The newer + * versions of these values should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** + * This structure is used to provide callers information about the + * progress of indexing a packfile. + * + * This type is deprecated, but there is no plan to remove this + * type definition at this time. + */ +typedef git_indexer_progress git_transfer_progress; + +/** + * Type definition for progress callbacks during indexing. + * + * This type is deprecated, but there is no plan to remove this + * type definition at this time. + */ +typedef git_indexer_progress_cb git_transfer_progress_cb; + +/** + * Type definition for push transfer progress callbacks. + * + * This type is deprecated, but there is no plan to remove this + * type definition at this time. + */ +typedef git_push_transfer_progress_cb git_push_transfer_progress; + + /** The type of a remote completion event */ +#define git_remote_completion_type git_remote_completion_t + +/** + * Callback for listing the remote heads + */ +typedef int GIT_CALLBACK(git_headlist_cb)(git_remote_head *rhead, void *payload); + +/**@}*/ + +/** @name Deprecated String Array Functions + * + * These types are retained for backward compatibility. The newer + * versions of these values should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** + * Copy a string array object from source to target. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @param tgt target + * @param src source + * @return 0 on success, < 0 on allocation failure + */ +GIT_EXTERN(int) git_strarray_copy(git_strarray *tgt, const git_strarray *src); + +/** + * Free the memory referred to by the git_strarray. This is an alias of + * `git_strarray_dispose` and is preserved for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Use git_strarray_dispose + * @see git_strarray_dispose + */ +GIT_EXTERN(void) git_strarray_free(git_strarray *array); + +/**@}*/ + +/** @name Deprecated Options Initialization Functions + * + * These functions are retained for backward compatibility. The newer + * versions of these functions should be preferred in all new code. + * + * There is no plan to remove these backward compatibility functions at + * this time. + */ +/**@{*/ + +GIT_EXTERN(int) git_blame_init_options(git_blame_options *opts, unsigned int version); +GIT_EXTERN(int) git_checkout_init_options(git_checkout_options *opts, unsigned int version); +GIT_EXTERN(int) git_cherrypick_init_options(git_cherrypick_options *opts, unsigned int version); +GIT_EXTERN(int) git_clone_init_options(git_clone_options *opts, unsigned int version); +GIT_EXTERN(int) git_describe_init_options(git_describe_options *opts, unsigned int version); +GIT_EXTERN(int) git_describe_init_format_options(git_describe_format_options *opts, unsigned int version); +GIT_EXTERN(int) git_diff_init_options(git_diff_options *opts, unsigned int version); +GIT_EXTERN(int) git_diff_find_init_options(git_diff_find_options *opts, unsigned int version); +GIT_EXTERN(int) git_diff_format_email_init_options(git_diff_format_email_options *opts, unsigned int version); +GIT_EXTERN(int) git_diff_patchid_init_options(git_diff_patchid_options *opts, unsigned int version); +GIT_EXTERN(int) git_fetch_init_options(git_fetch_options *opts, unsigned int version); +GIT_EXTERN(int) git_indexer_init_options(git_indexer_options *opts, unsigned int version); +GIT_EXTERN(int) git_merge_init_options(git_merge_options *opts, unsigned int version); +GIT_EXTERN(int) git_merge_file_init_input(git_merge_file_input *input, unsigned int version); +GIT_EXTERN(int) git_merge_file_init_options(git_merge_file_options *opts, unsigned int version); +GIT_EXTERN(int) git_proxy_init_options(git_proxy_options *opts, unsigned int version); +GIT_EXTERN(int) git_push_init_options(git_push_options *opts, unsigned int version); +GIT_EXTERN(int) git_rebase_init_options(git_rebase_options *opts, unsigned int version); +GIT_EXTERN(int) git_remote_create_init_options(git_remote_create_options *opts, unsigned int version); +GIT_EXTERN(int) git_repository_init_init_options(git_repository_init_options *opts, unsigned int version); +GIT_EXTERN(int) git_revert_init_options(git_revert_options *opts, unsigned int version); +GIT_EXTERN(int) git_stash_apply_init_options(git_stash_apply_options *opts, unsigned int version); +GIT_EXTERN(int) git_status_init_options(git_status_options *opts, unsigned int version); +GIT_EXTERN(int) git_submodule_update_init_options(git_submodule_update_options *opts, unsigned int version); +GIT_EXTERN(int) git_worktree_add_init_options(git_worktree_add_options *opts, unsigned int version); +GIT_EXTERN(int) git_worktree_prune_init_options(git_worktree_prune_options *opts, unsigned int version); + +/**@}*/ + +/** @} */ +GIT_END_DECL + +#endif + +#endif diff --git a/3rdparty/libgit2/include/git2/describe.h b/3rdparty/libgit2/include/git2/describe.h index 7a796f1..01a82b3 100644 --- a/3rdparty/libgit2/include/git2/describe.h +++ b/3rdparty/libgit2/include/git2/describe.h @@ -1,194 +1,194 @@ -/* - * 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_describe_h__ -#define INCLUDE_git_describe_h__ - -#include "common.h" -#include "types.h" -#include "buffer.h" - -/** - * @file git2/describe.h - * @brief Git describing routines - * @defgroup git_describe Git describing routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Reference lookup strategy - * - * These behave like the --tags and --all options to git-describe, - * namely they say to look for any reference in either refs/tags/ or - * refs/ respectively. - */ -typedef enum { - GIT_DESCRIBE_DEFAULT, - GIT_DESCRIBE_TAGS, - GIT_DESCRIBE_ALL -} git_describe_strategy_t; - -/** - * Describe options structure - * - * Initialize with `GIT_DESCRIBE_OPTIONS_INIT`. Alternatively, you can - * use `git_describe_options_init`. - * - */ -typedef struct git_describe_options { - unsigned int version; - - unsigned int max_candidates_tags; /**< default: 10 */ - unsigned int describe_strategy; /**< default: GIT_DESCRIBE_DEFAULT */ - const char *pattern; - /** - * When calculating the distance from the matching tag or - * reference, only walk down the first-parent ancestry. - */ - int only_follow_first_parent; - /** - * If no matching tag or reference is found, the describe - * operation would normally fail. If this option is set, it - * will instead fall back to showing the full id of the - * commit. - */ - int show_commit_oid_as_fallback; -} git_describe_options; - -#define GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS 10 -#define GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE 7 - -#define GIT_DESCRIBE_OPTIONS_VERSION 1 -#define GIT_DESCRIBE_OPTIONS_INIT { \ - GIT_DESCRIBE_OPTIONS_VERSION, \ - GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \ -} - -/** - * Initialize git_describe_options structure - * - * Initializes a `git_describe_options` with default values. Equivalent to creating - * an instance with GIT_DESCRIBE_OPTIONS_INIT. - * - * @param opts The `git_describe_options` struct to initialize. - * @param version The struct version; pass `GIT_DESCRIBE_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_describe_options_init(git_describe_options *opts, unsigned int version); - -/** - * Describe format options structure - * - * Initialize with `GIT_DESCRIBE_FORMAT_OPTIONS_INIT`. Alternatively, you can - * use `git_describe_format_options_init`. - * - */ -typedef struct { - unsigned int version; - - /** - * Size of the abbreviated commit id to use. This value is the - * lower bound for the length of the abbreviated string. The - * default is 7. - */ - unsigned int abbreviated_size; - - /** - * Set to use the long format even when a shorter name could be used. - */ - int always_use_long_format; - - /** - * If the workdir is dirty and this is set, this string will - * be appended to the description string. - */ - const char *dirty_suffix; -} git_describe_format_options; - -#define GIT_DESCRIBE_FORMAT_OPTIONS_VERSION 1 -#define GIT_DESCRIBE_FORMAT_OPTIONS_INIT { \ - GIT_DESCRIBE_FORMAT_OPTIONS_VERSION, \ - GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \ - } - -/** - * Initialize git_describe_format_options structure - * - * Initializes a `git_describe_format_options` with default values. Equivalent to creating - * an instance with GIT_DESCRIBE_FORMAT_OPTIONS_INIT. - * - * @param opts The `git_describe_format_options` struct to initialize. - * @param version The struct version; pass `GIT_DESCRIBE_FORMAT_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_describe_format_options_init(git_describe_format_options *opts, unsigned int version); - -/** - * A struct that stores the result of a describe operation. - */ -typedef struct git_describe_result git_describe_result; - -/** - * Describe a commit - * - * Perform the describe operation on the given committish object. - * - * @param result pointer to store the result. You must free this once - * you're done with it. - * @param committish a committish to describe - * @param opts the lookup options (or NULL for defaults) - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_describe_commit( - git_describe_result **result, - git_object *committish, - git_describe_options *opts); - -/** - * Describe a commit - * - * Perform the describe operation on the current commit and the - * worktree. After performing describe on HEAD, a status is run and the - * description is considered to be dirty if there are. - * - * @param out pointer to store the result. You must free this once - * you're done with it. - * @param repo the repository in which to perform the describe - * @param opts the lookup options (or NULL for defaults) - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_describe_workdir( - git_describe_result **out, - git_repository *repo, - git_describe_options *opts); - -/** - * Print the describe result to a buffer - * - * @param out The buffer to store the result - * @param result the result from `git_describe_commit()` or - * `git_describe_workdir()`. - * @param opts the formatting options (or NULL for defaults) - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_describe_format( - git_buf *out, - const git_describe_result *result, - const git_describe_format_options *opts); - -/** - * Free the describe result. - * - * @param result The result to free. - */ -GIT_EXTERN(void) git_describe_result_free(git_describe_result *result); - -/** @} */ -GIT_END_DECL - -#endif +/* + * 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_describe_h__ +#define INCLUDE_git_describe_h__ + +#include "common.h" +#include "types.h" +#include "buffer.h" + +/** + * @file git2/describe.h + * @brief Git describing routines + * @defgroup git_describe Git describing routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Reference lookup strategy + * + * These behave like the --tags and --all options to git-describe, + * namely they say to look for any reference in either refs/tags/ or + * refs/ respectively. + */ +typedef enum { + GIT_DESCRIBE_DEFAULT, + GIT_DESCRIBE_TAGS, + GIT_DESCRIBE_ALL +} git_describe_strategy_t; + +/** + * Describe options structure + * + * Initialize with `GIT_DESCRIBE_OPTIONS_INIT`. Alternatively, you can + * use `git_describe_options_init`. + * + */ +typedef struct git_describe_options { + unsigned int version; + + unsigned int max_candidates_tags; /**< default: 10 */ + unsigned int describe_strategy; /**< default: GIT_DESCRIBE_DEFAULT */ + const char *pattern; + /** + * When calculating the distance from the matching tag or + * reference, only walk down the first-parent ancestry. + */ + int only_follow_first_parent; + /** + * If no matching tag or reference is found, the describe + * operation would normally fail. If this option is set, it + * will instead fall back to showing the full id of the + * commit. + */ + int show_commit_oid_as_fallback; +} git_describe_options; + +#define GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS 10 +#define GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE 7 + +#define GIT_DESCRIBE_OPTIONS_VERSION 1 +#define GIT_DESCRIBE_OPTIONS_INIT { \ + GIT_DESCRIBE_OPTIONS_VERSION, \ + GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \ +} + +/** + * Initialize git_describe_options structure + * + * Initializes a `git_describe_options` with default values. Equivalent to creating + * an instance with GIT_DESCRIBE_OPTIONS_INIT. + * + * @param opts The `git_describe_options` struct to initialize. + * @param version The struct version; pass `GIT_DESCRIBE_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_describe_options_init(git_describe_options *opts, unsigned int version); + +/** + * Describe format options structure + * + * Initialize with `GIT_DESCRIBE_FORMAT_OPTIONS_INIT`. Alternatively, you can + * use `git_describe_format_options_init`. + * + */ +typedef struct { + unsigned int version; + + /** + * Size of the abbreviated commit id to use. This value is the + * lower bound for the length of the abbreviated string. The + * default is 7. + */ + unsigned int abbreviated_size; + + /** + * Set to use the long format even when a shorter name could be used. + */ + int always_use_long_format; + + /** + * If the workdir is dirty and this is set, this string will + * be appended to the description string. + */ + const char *dirty_suffix; +} git_describe_format_options; + +#define GIT_DESCRIBE_FORMAT_OPTIONS_VERSION 1 +#define GIT_DESCRIBE_FORMAT_OPTIONS_INIT { \ + GIT_DESCRIBE_FORMAT_OPTIONS_VERSION, \ + GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \ + } + +/** + * Initialize git_describe_format_options structure + * + * Initializes a `git_describe_format_options` with default values. Equivalent to creating + * an instance with GIT_DESCRIBE_FORMAT_OPTIONS_INIT. + * + * @param opts The `git_describe_format_options` struct to initialize. + * @param version The struct version; pass `GIT_DESCRIBE_FORMAT_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_describe_format_options_init(git_describe_format_options *opts, unsigned int version); + +/** + * A struct that stores the result of a describe operation. + */ +typedef struct git_describe_result git_describe_result; + +/** + * Describe a commit + * + * Perform the describe operation on the given committish object. + * + * @param result pointer to store the result. You must free this once + * you're done with it. + * @param committish a committish to describe + * @param opts the lookup options (or NULL for defaults) + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_describe_commit( + git_describe_result **result, + git_object *committish, + git_describe_options *opts); + +/** + * Describe a commit + * + * Perform the describe operation on the current commit and the + * worktree. After performing describe on HEAD, a status is run and the + * description is considered to be dirty if there are. + * + * @param out pointer to store the result. You must free this once + * you're done with it. + * @param repo the repository in which to perform the describe + * @param opts the lookup options (or NULL for defaults) + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_describe_workdir( + git_describe_result **out, + git_repository *repo, + git_describe_options *opts); + +/** + * Print the describe result to a buffer + * + * @param out The buffer to store the result + * @param result the result from `git_describe_commit()` or + * `git_describe_workdir()`. + * @param opts the formatting options (or NULL for defaults) + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_describe_format( + git_buf *out, + const git_describe_result *result, + const git_describe_format_options *opts); + +/** + * Free the describe result. + * + * @param result The result to free. + */ +GIT_EXTERN(void) git_describe_result_free(git_describe_result *result); + +/** @} */ +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/diff.h b/3rdparty/libgit2/include/git2/diff.h index 384b6e7..82add75 100644 --- a/3rdparty/libgit2/include/git2/diff.h +++ b/3rdparty/libgit2/include/git2/diff.h @@ -1,1477 +1,1477 @@ -/* - * 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_diff_h__ -#define INCLUDE_git_diff_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "tree.h" -#include "refs.h" - -/** - * @file git2/diff.h - * @brief Git tree and file differencing routines. - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Flags for diff options. A combination of these flags can be passed - * in via the `flags` value in the `git_diff_options`. - */ -typedef enum { - /** Normal diff, the default */ - GIT_DIFF_NORMAL = 0, - - /* - * Options controlling which files will be in the diff - */ - - /** Reverse the sides of the diff */ - GIT_DIFF_REVERSE = (1u << 0), - - /** Include ignored files in the diff */ - GIT_DIFF_INCLUDE_IGNORED = (1u << 1), - - /** Even with GIT_DIFF_INCLUDE_IGNORED, an entire ignored directory - * will be marked with only a single entry in the diff; this flag - * adds all files under the directory as IGNORED entries, too. - */ - GIT_DIFF_RECURSE_IGNORED_DIRS = (1u << 2), - - /** Include untracked files in the diff */ - GIT_DIFF_INCLUDE_UNTRACKED = (1u << 3), - - /** Even with GIT_DIFF_INCLUDE_UNTRACKED, an entire untracked - * directory will be marked with only a single entry in the diff - * (a la what core Git does in `git status`); this flag adds *all* - * files under untracked directories as UNTRACKED entries, too. - */ - GIT_DIFF_RECURSE_UNTRACKED_DIRS = (1u << 4), - - /** Include unmodified files in the diff */ - GIT_DIFF_INCLUDE_UNMODIFIED = (1u << 5), - - /** Normally, a type change between files will be converted into a - * DELETED record for the old and an ADDED record for the new; this - * options enabled the generation of TYPECHANGE delta records. - */ - GIT_DIFF_INCLUDE_TYPECHANGE = (1u << 6), - - /** Even with GIT_DIFF_INCLUDE_TYPECHANGE, blob->tree changes still - * generally show as a DELETED blob. This flag tries to correctly - * label blob->tree transitions as TYPECHANGE records with new_file's - * mode set to tree. Note: the tree SHA will not be available. - */ - GIT_DIFF_INCLUDE_TYPECHANGE_TREES = (1u << 7), - - /** Ignore file mode changes */ - GIT_DIFF_IGNORE_FILEMODE = (1u << 8), - - /** Treat all submodules as unmodified */ - GIT_DIFF_IGNORE_SUBMODULES = (1u << 9), - - /** Use case insensitive filename comparisons */ - GIT_DIFF_IGNORE_CASE = (1u << 10), - - /** May be combined with `GIT_DIFF_IGNORE_CASE` to specify that a file - * that has changed case will be returned as an add/delete pair. - */ - GIT_DIFF_INCLUDE_CASECHANGE = (1u << 11), - - /** If the pathspec is set in the diff options, this flags indicates - * that the paths will be treated as literal paths instead of - * fnmatch patterns. Each path in the list must either be a full - * path to a file or a directory. (A trailing slash indicates that - * the path will _only_ match a directory). If a directory is - * specified, all children will be included. - */ - GIT_DIFF_DISABLE_PATHSPEC_MATCH = (1u << 12), - - /** Disable updating of the `binary` flag in delta records. This is - * useful when iterating over a diff if you don't need hunk and data - * callbacks and want to avoid having to load file completely. - */ - GIT_DIFF_SKIP_BINARY_CHECK = (1u << 13), - - /** When diff finds an untracked directory, to match the behavior of - * core Git, it scans the contents for IGNORED and UNTRACKED files. - * If *all* contents are IGNORED, then the directory is IGNORED; if - * any contents are not IGNORED, then the directory is UNTRACKED. - * This is extra work that may not matter in many cases. This flag - * turns off that scan and immediately labels an untracked directory - * as UNTRACKED (changing the behavior to not match core Git). - */ - GIT_DIFF_ENABLE_FAST_UNTRACKED_DIRS = (1u << 14), - - /** When diff finds a file in the working directory with stat - * information different from the index, but the OID ends up being the - * same, write the correct stat information into the index. Note: - * without this flag, diff will always leave the index untouched. - */ - GIT_DIFF_UPDATE_INDEX = (1u << 15), - - /** Include unreadable files in the diff */ - GIT_DIFF_INCLUDE_UNREADABLE = (1u << 16), - - /** Include unreadable files in the diff */ - GIT_DIFF_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 17), - - /* - * Options controlling how output will be generated - */ - - /** Use a heuristic that takes indentation and whitespace into account - * which generally can produce better diffs when dealing with ambiguous - * diff hunks. - */ - GIT_DIFF_INDENT_HEURISTIC = (1u << 18), - - /** Ignore blank lines */ - GIT_DIFF_IGNORE_BLANK_LINES = (1u << 19), - - /** Treat all files as text, disabling binary attributes & detection */ - GIT_DIFF_FORCE_TEXT = (1u << 20), - /** Treat all files as binary, disabling text diffs */ - GIT_DIFF_FORCE_BINARY = (1u << 21), - - /** Ignore all whitespace */ - GIT_DIFF_IGNORE_WHITESPACE = (1u << 22), - /** Ignore changes in amount of whitespace */ - GIT_DIFF_IGNORE_WHITESPACE_CHANGE = (1u << 23), - /** Ignore whitespace at end of line */ - GIT_DIFF_IGNORE_WHITESPACE_EOL = (1u << 24), - - /** When generating patch text, include the content of untracked - * files. This automatically turns on GIT_DIFF_INCLUDE_UNTRACKED but - * it does not turn on GIT_DIFF_RECURSE_UNTRACKED_DIRS. Add that - * flag if you want the content of every single UNTRACKED file. - */ - GIT_DIFF_SHOW_UNTRACKED_CONTENT = (1u << 25), - - /** When generating output, include the names of unmodified files if - * they are included in the git_diff. Normally these are skipped in - * the formats that list files (e.g. name-only, name-status, raw). - * Even with this, these will not be included in patch format. - */ - GIT_DIFF_SHOW_UNMODIFIED = (1u << 26), - - /** Use the "patience diff" algorithm */ - GIT_DIFF_PATIENCE = (1u << 28), - /** Take extra time to find minimal diff */ - GIT_DIFF_MINIMAL = (1u << 29), - - /** Include the necessary deflate / delta information so that `git-apply` - * can apply given diff information to binary files. - */ - GIT_DIFF_SHOW_BINARY = (1u << 30) -} git_diff_option_t; - -/** - * The diff object that contains all individual file deltas. - * - * A `diff` represents the cumulative list of differences between two - * snapshots of a repository (possibly filtered by a set of file name - * patterns). - * - * Calculating diffs is generally done in two phases: building a list of - * diffs then traversing it. This makes is easier to share logic across - * the various types of diffs (tree vs tree, workdir vs index, etc.), and - * also allows you to insert optional diff post-processing phases, - * such as rename detection, in between the steps. When you are done with - * a diff object, it must be freed. - * - * This is an opaque structure which will be allocated by one of the diff - * generator functions below (such as `git_diff_tree_to_tree`). You are - * responsible for releasing the object memory when done, using the - * `git_diff_free()` function. - * - */ -typedef struct git_diff git_diff; - -/** - * Flags for the delta object and the file objects on each side. - * - * These flags are used for both the `flags` value of the `git_diff_delta` - * and the flags for the `git_diff_file` objects representing the old and - * new sides of the delta. Values outside of this public range should be - * considered reserved for internal or future use. - */ -typedef enum { - GIT_DIFF_FLAG_BINARY = (1u << 0), /**< file(s) treated as binary data */ - GIT_DIFF_FLAG_NOT_BINARY = (1u << 1), /**< file(s) treated as text data */ - GIT_DIFF_FLAG_VALID_ID = (1u << 2), /**< `id` value is known correct */ - GIT_DIFF_FLAG_EXISTS = (1u << 3), /**< file exists at this side of the delta */ - GIT_DIFF_FLAG_VALID_SIZE = (1u << 4) /**< file size value is known correct */ -} git_diff_flag_t; - -/** - * What type of change is described by a git_diff_delta? - * - * `GIT_DELTA_RENAMED` and `GIT_DELTA_COPIED` will only show up if you run - * `git_diff_find_similar()` on the diff object. - * - * `GIT_DELTA_TYPECHANGE` only shows up given `GIT_DIFF_INCLUDE_TYPECHANGE` - * in the option flags (otherwise type changes will be split into ADDED / - * DELETED pairs). - */ -typedef enum { - GIT_DELTA_UNMODIFIED = 0, /**< no changes */ - GIT_DELTA_ADDED = 1, /**< entry does not exist in old version */ - GIT_DELTA_DELETED = 2, /**< entry does not exist in new version */ - GIT_DELTA_MODIFIED = 3, /**< entry content changed between old and new */ - GIT_DELTA_RENAMED = 4, /**< entry was renamed between old and new */ - GIT_DELTA_COPIED = 5, /**< entry was copied from another old entry */ - GIT_DELTA_IGNORED = 6, /**< entry is ignored item in workdir */ - GIT_DELTA_UNTRACKED = 7, /**< entry is untracked item in workdir */ - GIT_DELTA_TYPECHANGE = 8, /**< type of entry changed between old and new */ - GIT_DELTA_UNREADABLE = 9, /**< entry is unreadable */ - GIT_DELTA_CONFLICTED = 10 /**< entry in the index is conflicted */ -} git_delta_t; - -/** - * Description of one side of a delta. - * - * Although this is called a "file", it could represent a file, a symbolic - * link, a submodule commit id, or even a tree (although that only if you - * are tracking type changes or ignored/untracked directories). - */ -typedef struct { - /** - * The `git_oid` of the item. If the entry represents an - * absent side of a diff (e.g. the `old_file` of a `GIT_DELTA_ADDED` delta), - * then the oid will be zeroes. - */ - git_oid id; - - /** - * The NUL-terminated path to the entry relative to the working - * directory of the repository. - */ - const char *path; - - /** - * The size of the entry in bytes. - */ - git_object_size_t size; - - /** - * A combination of the `git_diff_flag_t` types - */ - uint32_t flags; - - /** - * Roughly, the stat() `st_mode` value for the item. This will - * be restricted to one of the `git_filemode_t` values. - */ - uint16_t mode; - - /** - * Represents the known length of the `id` field, when - * converted to a hex string. It is generally `GIT_OID_SHA1_HEXSIZE`, unless this - * delta was created from reading a patch file, in which case it may be - * abbreviated to something reasonable, like 7 characters. - */ - uint16_t id_abbrev; -} git_diff_file; - -/** - * Description of changes to one entry. - * - * A `delta` is a file pair with an old and new revision. The old version - * may be absent if the file was just created and the new version may be - * absent if the file was deleted. A diff is mostly just a list of deltas. - * - * When iterating over a diff, this will be passed to most callbacks and - * you can use the contents to understand exactly what has changed. - * - * The `old_file` represents the "from" side of the diff and the `new_file` - * represents to "to" side of the diff. What those means depend on the - * function that was used to generate the diff and will be documented below. - * You can also use the `GIT_DIFF_REVERSE` flag to flip it around. - * - * Although the two sides of the delta are named "old_file" and "new_file", - * they actually may correspond to entries that represent a file, a symbolic - * link, a submodule commit id, or even a tree (if you are tracking type - * changes or ignored/untracked directories). - * - * Under some circumstances, in the name of efficiency, not all fields will - * be filled in, but we generally try to fill in as much as possible. One - * example is that the "flags" field may not have either the `BINARY` or the - * `NOT_BINARY` flag set to avoid examining file contents if you do not pass - * in hunk and/or line callbacks to the diff foreach iteration function. It - * will just use the git attributes for those files. - * - * The similarity score is zero unless you call `git_diff_find_similar()` - * which does a similarity analysis of files in the diff. Use that - * function to do rename and copy detection, and to split heavily modified - * files in add/delete pairs. After that call, deltas with a status of - * GIT_DELTA_RENAMED or GIT_DELTA_COPIED will have a similarity score - * between 0 and 100 indicating how similar the old and new sides are. - * - * If you ask `git_diff_find_similar` to find heavily modified files to - * break, but to not *actually* break the records, then GIT_DELTA_MODIFIED - * records may have a non-zero similarity score if the self-similarity is - * below the split threshold. To display this value like core Git, invert - * the score (a la `printf("M%03d", 100 - delta->similarity)`). - */ -typedef struct { - git_delta_t status; - uint32_t flags; /**< git_diff_flag_t values */ - uint16_t similarity; /**< for RENAMED and COPIED, value 0-100 */ - uint16_t nfiles; /**< number of files in this delta */ - git_diff_file old_file; - git_diff_file new_file; -} git_diff_delta; - -/** - * Diff notification callback function. - * - * The callback will be called for each file, just before the `git_diff_delta` - * gets inserted into the diff. - * - * When the callback: - * - returns < 0, the diff process will be aborted. - * - returns > 0, the delta will not be inserted into the diff, but the - * diff process continues. - * - returns 0, the delta is inserted into the diff, and the diff process - * continues. - */ -typedef int GIT_CALLBACK(git_diff_notify_cb)( - const git_diff *diff_so_far, - const git_diff_delta *delta_to_add, - const char *matched_pathspec, - void *payload); - -/** - * Diff progress callback. - * - * Called before each file comparison. - * - * @param diff_so_far The diff being generated. - * @param old_path The path to the old file or NULL. - * @param new_path The path to the new file or NULL. - * @return Non-zero to abort the diff. - */ -typedef int GIT_CALLBACK(git_diff_progress_cb)( - const git_diff *diff_so_far, - const char *old_path, - const char *new_path, - void *payload); - -/** - * Structure describing options about how the diff should be executed. - * - * Setting all values of the structure to zero will yield the default - * values. Similarly, passing NULL for the options structure will - * give the defaults. The default values are marked below. - * - */ -typedef struct { - unsigned int version; /**< version for the struct */ - - /** - * A combination of `git_diff_option_t` values above. - * Defaults to GIT_DIFF_NORMAL - */ - uint32_t flags; - - /* options controlling which files are in the diff */ - - /** Overrides the submodule ignore setting for all submodules in the diff. */ - git_submodule_ignore_t ignore_submodules; - - /** - * An array of paths / fnmatch patterns to constrain diff. - * All paths are included by default. - */ - git_strarray pathspec; - - /** - * An optional callback function, notifying the consumer of changes to - * the diff as new deltas are added. - */ - git_diff_notify_cb notify_cb; - - /** - * An optional callback function, notifying the consumer of which files - * are being examined as the diff is generated. - */ - git_diff_progress_cb progress_cb; - - /** The payload to pass to the callback functions. */ - void *payload; - - /* options controlling how to diff text is generated */ - - /** - * The number of unchanged lines that define the boundary of a hunk - * (and to display before and after). Defaults to 3. - */ - uint32_t context_lines; - /** - * The maximum number of unchanged lines between hunk boundaries before - * the hunks will be merged into one. Defaults to 0. - */ - uint32_t interhunk_lines; - - /** - * The object ID type to emit in diffs; this is used by functions - * that operate without a repository - namely `git_diff_buffers`, - * or `git_diff_blobs` and `git_diff_blob_to_buffer` when one blob - * is `NULL`. - * - * This may be omitted (set to `0`). If a repository is available, - * the object ID format of the repository will be used. If no - * repository is available then the default is `GIT_OID_SHA`. - * - * If this is specified and a repository is available, then the - * specified `oid_type` must match the repository's object ID - * format. - */ - git_oid_t oid_type; - - /** - * The abbreviation length to use when formatting object ids. - * Defaults to the value of 'core.abbrev' from the config, or 7 if unset. - */ - uint16_t id_abbrev; - - /** - * A size (in bytes) above which a blob will be marked as binary - * automatically; pass a negative value to disable. - * Defaults to 512MB. - */ - git_off_t max_size; - - /** - * The virtual "directory" prefix for old file names in hunk headers. - * Default is "a". - */ - const char *old_prefix; - - /** - * The virtual "directory" prefix for new file names in hunk headers. - * Defaults to "b". - */ - const char *new_prefix; -} git_diff_options; - -/* The current version of the diff options structure */ -#define GIT_DIFF_OPTIONS_VERSION 1 - -/* Stack initializer for diff options. Alternatively use - * `git_diff_options_init` programmatic initialization. - */ -#define GIT_DIFF_OPTIONS_INIT \ - {GIT_DIFF_OPTIONS_VERSION, 0, GIT_SUBMODULE_IGNORE_UNSPECIFIED, {NULL,0}, NULL, NULL, NULL, 3} - -/** - * Initialize git_diff_options structure - * - * Initializes a `git_diff_options` with default values. Equivalent to creating - * an instance with GIT_DIFF_OPTIONS_INIT. - * - * @param opts The `git_diff_options` struct to initialize. - * @param version The struct version; pass `GIT_DIFF_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_diff_options_init( - git_diff_options *opts, - unsigned int version); - -/** - * When iterating over a diff, callback that will be made per file. - * - * @param delta A pointer to the delta data for the file - * @param progress Goes from 0 to 1 over the diff - * @param payload User-specified pointer from foreach function - */ -typedef int GIT_CALLBACK(git_diff_file_cb)( - const git_diff_delta *delta, - float progress, - void *payload); - -#define GIT_DIFF_HUNK_HEADER_SIZE 128 - -/** - * When producing a binary diff, the binary data returned will be - * either the deflated full ("literal") contents of the file, or - * the deflated binary delta between the two sides (whichever is - * smaller). - */ -typedef enum { - /** There is no binary delta. */ - GIT_DIFF_BINARY_NONE, - - /** The binary data is the literal contents of the file. */ - GIT_DIFF_BINARY_LITERAL, - - /** The binary data is the delta from one side to the other. */ - GIT_DIFF_BINARY_DELTA -} git_diff_binary_t; - -/** The contents of one of the files in a binary diff. */ -typedef struct { - /** The type of binary data for this file. */ - git_diff_binary_t type; - - /** The binary data, deflated. */ - const char *data; - - /** The length of the binary data. */ - size_t datalen; - - /** The length of the binary data after inflation. */ - size_t inflatedlen; -} git_diff_binary_file; - -/** - * Structure describing the binary contents of a diff. - * - * A `binary` file / delta is a file (or pair) for which no text diffs - * should be generated. A diff can contain delta entries that are - * binary, but no diff content will be output for those files. There is - * a base heuristic for binary detection and you can further tune the - * behavior with git attributes or diff flags and option settings. - */ -typedef struct { - /** - * Whether there is data in this binary structure or not. - * - * If this is `1`, then this was produced and included binary content. - * If this is `0` then this was generated knowing only that a binary - * file changed but without providing the data, probably from a patch - * that said `Binary files a/file.txt and b/file.txt differ`. - */ - unsigned int contains_data; - git_diff_binary_file old_file; /**< The contents of the old file. */ - git_diff_binary_file new_file; /**< The contents of the new file. */ -} git_diff_binary; - -/** - * When iterating over a diff, callback that will be made for - * binary content within the diff. - */ -typedef int GIT_CALLBACK(git_diff_binary_cb)( - const git_diff_delta *delta, - const git_diff_binary *binary, - void *payload); - -/** - * Structure describing a hunk of a diff. - * - * A `hunk` is a span of modified lines in a delta along with some stable - * surrounding context. You can configure the amount of context and other - * properties of how hunks are generated. Each hunk also comes with a - * header that described where it starts and ends in both the old and new - * versions in the delta. - */ -typedef struct { - int old_start; /**< Starting line number in old_file */ - int old_lines; /**< Number of lines in old_file */ - int new_start; /**< Starting line number in new_file */ - int new_lines; /**< Number of lines in new_file */ - size_t header_len; /**< Number of bytes in header text */ - char header[GIT_DIFF_HUNK_HEADER_SIZE]; /**< Header text, NUL-byte terminated */ -} git_diff_hunk; - -/** - * When iterating over a diff, callback that will be made per hunk. - */ -typedef int GIT_CALLBACK(git_diff_hunk_cb)( - const git_diff_delta *delta, - const git_diff_hunk *hunk, - void *payload); - -/** - * Line origin constants. - * - * These values describe where a line came from and will be passed to - * the git_diff_line_cb when iterating over a diff. There are some - * special origin constants at the end that are used for the text - * output callbacks to demarcate lines that are actually part of - * the file or hunk headers. - */ -typedef enum { - /* These values will be sent to `git_diff_line_cb` along with the line */ - GIT_DIFF_LINE_CONTEXT = ' ', - GIT_DIFF_LINE_ADDITION = '+', - GIT_DIFF_LINE_DELETION = '-', - - GIT_DIFF_LINE_CONTEXT_EOFNL = '=', /**< Both files have no LF at end */ - GIT_DIFF_LINE_ADD_EOFNL = '>', /**< Old has no LF at end, new does */ - GIT_DIFF_LINE_DEL_EOFNL = '<', /**< Old has LF at end, new does not */ - - /* The following values will only be sent to a `git_diff_line_cb` when - * the content of a diff is being formatted through `git_diff_print`. - */ - GIT_DIFF_LINE_FILE_HDR = 'F', - GIT_DIFF_LINE_HUNK_HDR = 'H', - GIT_DIFF_LINE_BINARY = 'B' /**< For "Binary files x and y differ" */ -} git_diff_line_t; - -/** - * Structure describing a line (or data span) of a diff. - * - * A `line` is a range of characters inside a hunk. It could be a context - * line (i.e. in both old and new versions), an added line (i.e. only in - * the new version), or a removed line (i.e. only in the old version). - * Unfortunately, we don't know anything about the encoding of data in the - * file being diffed, so we cannot tell you much about the line content. - * Line data will not be NUL-byte terminated, however, because it will be - * just a span of bytes inside the larger file. - */ -typedef struct { - char origin; /**< A git_diff_line_t value */ - int old_lineno; /**< Line number in old file or -1 for added line */ - int new_lineno; /**< Line number in new file or -1 for deleted line */ - int num_lines; /**< Number of newline characters in content */ - size_t content_len; /**< Number of bytes of data */ - git_off_t content_offset; /**< Offset in the original file to the content */ - const char *content; /**< Pointer to diff text, not NUL-byte terminated */ -} git_diff_line; - -/** - * When iterating over a diff, callback that will be made per text diff - * line. In this context, the provided range will be NULL. - * - * When printing a diff, callback that will be made to output each line - * of text. This uses some extra GIT_DIFF_LINE_... constants for output - * of lines of file and hunk headers. - */ -typedef int GIT_CALLBACK(git_diff_line_cb)( - const git_diff_delta *delta, /**< delta that contains this data */ - const git_diff_hunk *hunk, /**< hunk containing this data */ - const git_diff_line *line, /**< line data */ - void *payload); /**< user reference data */ - -/** - * Flags to control the behavior of diff rename/copy detection. - */ -typedef enum { - /** Obey `diff.renames`. Overridden by any other GIT_DIFF_FIND_... flag. */ - GIT_DIFF_FIND_BY_CONFIG = 0, - - /** Look for renames? (`--find-renames`) */ - GIT_DIFF_FIND_RENAMES = (1u << 0), - - /** Consider old side of MODIFIED for renames? (`--break-rewrites=N`) */ - GIT_DIFF_FIND_RENAMES_FROM_REWRITES = (1u << 1), - - /** Look for copies? (a la `--find-copies`). */ - GIT_DIFF_FIND_COPIES = (1u << 2), - - /** Consider UNMODIFIED as copy sources? (`--find-copies-harder`). - * - * For this to work correctly, use GIT_DIFF_INCLUDE_UNMODIFIED when - * the initial `git_diff` is being generated. - */ - GIT_DIFF_FIND_COPIES_FROM_UNMODIFIED = (1u << 3), - - /** Mark significant rewrites for split (`--break-rewrites=/M`) */ - GIT_DIFF_FIND_REWRITES = (1u << 4), - /** Actually split large rewrites into delete/add pairs */ - GIT_DIFF_BREAK_REWRITES = (1u << 5), - /** Mark rewrites for split and break into delete/add pairs */ - GIT_DIFF_FIND_AND_BREAK_REWRITES = - (GIT_DIFF_FIND_REWRITES | GIT_DIFF_BREAK_REWRITES), - - /** Find renames/copies for UNTRACKED items in working directory. - * - * For this to work correctly, use GIT_DIFF_INCLUDE_UNTRACKED when the - * initial `git_diff` is being generated (and obviously the diff must - * be against the working directory for this to make sense). - */ - GIT_DIFF_FIND_FOR_UNTRACKED = (1u << 6), - - /** Turn on all finding features. */ - GIT_DIFF_FIND_ALL = (0x0ff), - - /** Measure similarity ignoring leading whitespace (default) */ - GIT_DIFF_FIND_IGNORE_LEADING_WHITESPACE = 0, - /** Measure similarity ignoring all whitespace */ - GIT_DIFF_FIND_IGNORE_WHITESPACE = (1u << 12), - /** Measure similarity including all data */ - GIT_DIFF_FIND_DONT_IGNORE_WHITESPACE = (1u << 13), - /** Measure similarity only by comparing SHAs (fast and cheap) */ - GIT_DIFF_FIND_EXACT_MATCH_ONLY = (1u << 14), - - /** Do not break rewrites unless they contribute to a rename. - * - * Normally, GIT_DIFF_FIND_AND_BREAK_REWRITES will measure the self- - * similarity of modified files and split the ones that have changed a - * lot into a DELETE / ADD pair. Then the sides of that pair will be - * considered candidates for rename and copy detection. - * - * If you add this flag in and the split pair is *not* used for an - * actual rename or copy, then the modified record will be restored to - * a regular MODIFIED record instead of being split. - */ - GIT_DIFF_BREAK_REWRITES_FOR_RENAMES_ONLY = (1u << 15), - - /** Remove any UNMODIFIED deltas after find_similar is done. - * - * Using GIT_DIFF_FIND_COPIES_FROM_UNMODIFIED to emulate the - * --find-copies-harder behavior requires building a diff with the - * GIT_DIFF_INCLUDE_UNMODIFIED flag. If you do not want UNMODIFIED - * records in the final result, pass this flag to have them removed. - */ - GIT_DIFF_FIND_REMOVE_UNMODIFIED = (1u << 16) -} git_diff_find_t; - -/** - * Pluggable similarity metric - */ -typedef struct { - int GIT_CALLBACK(file_signature)( - void **out, const git_diff_file *file, - const char *fullpath, void *payload); - int GIT_CALLBACK(buffer_signature)( - void **out, const git_diff_file *file, - const char *buf, size_t buflen, void *payload); - void GIT_CALLBACK(free_signature)(void *sig, void *payload); - int GIT_CALLBACK(similarity)(int *score, void *siga, void *sigb, void *payload); - void *payload; -} git_diff_similarity_metric; - -/** - * Control behavior of rename and copy detection - * - * These options mostly mimic parameters that can be passed to git-diff. - */ -typedef struct { - unsigned int version; - - /** - * Combination of git_diff_find_t values (default GIT_DIFF_FIND_BY_CONFIG). - * NOTE: if you don't explicitly set this, `diff.renames` could be set - * to false, resulting in `git_diff_find_similar` doing nothing. - */ - uint32_t flags; - - /** - * Threshold above which similar files will be considered renames. - * This is equivalent to the -M option. Defaults to 50. - */ - uint16_t rename_threshold; - - /** - * Threshold below which similar files will be eligible to be a rename source. - * This is equivalent to the first part of the -B option. Defaults to 50. - */ - uint16_t rename_from_rewrite_threshold; - - /** - * Threshold above which similar files will be considered copies. - * This is equivalent to the -C option. Defaults to 50. - */ - uint16_t copy_threshold; - - /** - * Threshold below which similar files will be split into a delete/add pair. - * This is equivalent to the last part of the -B option. Defaults to 60. - */ - uint16_t break_rewrite_threshold; - - /** - * Maximum number of matches to consider for a particular file. - * - * This is a little different from the `-l` option from Git because we - * will still process up to this many matches before abandoning the search. - * Defaults to 1000. - */ - size_t rename_limit; - - /** - * The `metric` option allows you to plug in a custom similarity metric. - * - * Set it to NULL to use the default internal metric. - * - * The default metric is based on sampling hashes of ranges of data in - * the file, which is a pretty good similarity approximation that should - * work fairly well for both text and binary data while still being - * pretty fast with a fixed memory overhead. - */ - git_diff_similarity_metric *metric; -} git_diff_find_options; - -#define GIT_DIFF_FIND_OPTIONS_VERSION 1 -#define GIT_DIFF_FIND_OPTIONS_INIT {GIT_DIFF_FIND_OPTIONS_VERSION} - -/** - * Initialize git_diff_find_options structure - * - * Initializes a `git_diff_find_options` with default values. Equivalent to creating - * an instance with GIT_DIFF_FIND_OPTIONS_INIT. - * - * @param opts The `git_diff_find_options` struct to initialize. - * @param version The struct version; pass `GIT_DIFF_FIND_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_diff_find_options_init( - git_diff_find_options *opts, - unsigned int version); - -/** @name Diff Generator Functions - * - * These are the functions you would use to create (or destroy) a - * git_diff from various objects in a repository. - */ -/**@{*/ - -/** - * Deallocate a diff. - * - * @param diff The previously created diff; cannot be used after free. - */ -GIT_EXTERN(void) git_diff_free(git_diff *diff); - -/** - * Create a diff with the difference between two tree objects. - * - * This is equivalent to `git diff ` - * - * The first tree will be used for the "old_file" side of the delta and the - * second tree will be used for the "new_file" side of the delta. You can - * pass NULL to indicate an empty tree, although it is an error to pass - * NULL for both the `old_tree` and `new_tree`. - * - * @param diff Output pointer to a git_diff pointer to be allocated. - * @param repo The repository containing the trees. - * @param old_tree A git_tree object to diff from, or NULL for empty tree. - * @param new_tree A git_tree object to diff to, or NULL for empty tree. - * @param opts Structure with options to influence diff or NULL for defaults. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_diff_tree_to_tree( - git_diff **diff, - git_repository *repo, - git_tree *old_tree, - git_tree *new_tree, - const git_diff_options *opts); - -/** - * Create a diff between a tree and repository index. - * - * This is equivalent to `git diff --cached ` or if you pass - * the HEAD tree, then like `git diff --cached`. - * - * The tree you pass will be used for the "old_file" side of the delta, and - * the index will be used for the "new_file" side of the delta. - * - * If you pass NULL for the index, then the existing index of the `repo` - * will be used. In this case, the index will be refreshed from disk - * (if it has changed) before the diff is generated. - * - * @param diff Output pointer to a git_diff pointer to be allocated. - * @param repo The repository containing the tree and index. - * @param old_tree A git_tree object to diff from, or NULL for empty tree. - * @param index The index to diff with; repo index used if NULL. - * @param opts Structure with options to influence diff or NULL for defaults. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_diff_tree_to_index( - git_diff **diff, - git_repository *repo, - git_tree *old_tree, - git_index *index, - const git_diff_options *opts); - -/** - * Create a diff between the repository index and the workdir directory. - * - * This matches the `git diff` command. See the note below on - * `git_diff_tree_to_workdir` for a discussion of the difference between - * `git diff` and `git diff HEAD` and how to emulate a `git diff ` - * using libgit2. - * - * The index will be used for the "old_file" side of the delta, and the - * working directory will be used for the "new_file" side of the delta. - * - * If you pass NULL for the index, then the existing index of the `repo` - * will be used. In this case, the index will be refreshed from disk - * (if it has changed) before the diff is generated. - * - * @param diff Output pointer to a git_diff pointer to be allocated. - * @param repo The repository. - * @param index The index to diff from; repo index used if NULL. - * @param opts Structure with options to influence diff or NULL for defaults. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_diff_index_to_workdir( - git_diff **diff, - git_repository *repo, - git_index *index, - const git_diff_options *opts); - -/** - * Create a diff between a tree and the working directory. - * - * The tree you provide will be used for the "old_file" side of the delta, - * and the working directory will be used for the "new_file" side. - * - * This is not the same as `git diff ` or `git diff-index - * `. Those commands use information from the index, whereas this - * function strictly returns the differences between the tree and the files - * in the working directory, regardless of the state of the index. Use - * `git_diff_tree_to_workdir_with_index` to emulate those commands. - * - * To see difference between this and `git_diff_tree_to_workdir_with_index`, - * consider the example of a staged file deletion where the file has then - * been put back into the working dir and further modified. The - * tree-to-workdir diff for that file is 'modified', but `git diff` would - * show status 'deleted' since there is a staged delete. - * - * @param diff A pointer to a git_diff pointer that will be allocated. - * @param repo The repository containing the tree. - * @param old_tree A git_tree object to diff from, or NULL for empty tree. - * @param opts Structure with options to influence diff or NULL for defaults. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_diff_tree_to_workdir( - git_diff **diff, - git_repository *repo, - git_tree *old_tree, - const git_diff_options *opts); - -/** - * Create a diff between a tree and the working directory using index data - * to account for staged deletes, tracked files, etc. - * - * This emulates `git diff ` by diffing the tree to the index and - * the index to the working directory and blending the results into a - * single diff that includes staged deleted, etc. - * - * @param diff A pointer to a git_diff pointer that will be allocated. - * @param repo The repository containing the tree. - * @param old_tree A git_tree object to diff from, or NULL for empty tree. - * @param opts Structure with options to influence diff or NULL for defaults. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_diff_tree_to_workdir_with_index( - git_diff **diff, - git_repository *repo, - git_tree *old_tree, - const git_diff_options *opts); - -/** - * Create a diff with the difference between two index objects. - * - * The first index will be used for the "old_file" side of the delta and the - * second index will be used for the "new_file" side of the delta. - * - * @param diff Output pointer to a git_diff pointer to be allocated. - * @param repo The repository containing the indexes. - * @param old_index A git_index object to diff from. - * @param new_index A git_index object to diff to. - * @param opts Structure with options to influence diff or NULL for defaults. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_diff_index_to_index( - git_diff **diff, - git_repository *repo, - git_index *old_index, - git_index *new_index, - const git_diff_options *opts); - -/** - * Merge one diff into another. - * - * This merges items from the "from" list into the "onto" list. The - * resulting diff will have all items that appear in either list. - * If an item appears in both lists, then it will be "merged" to appear - * as if the old version was from the "onto" list and the new version - * is from the "from" list (with the exception that if the item has a - * pending DELETE in the middle, then it will show as deleted). - * - * @param onto Diff to merge into. - * @param from Diff to merge. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_diff_merge( - git_diff *onto, - const git_diff *from); - -/** - * Transform a diff marking file renames, copies, etc. - * - * This modifies a diff in place, replacing old entries that look - * like renames or copies with new entries reflecting those changes. - * This also will, if requested, break modified files into add/remove - * pairs if the amount of change is above a threshold. - * - * @param diff diff to run detection algorithms on - * @param options Control how detection should be run, NULL for defaults - * @return 0 on success, -1 on failure - */ -GIT_EXTERN(int) git_diff_find_similar( - git_diff *diff, - const git_diff_find_options *options); - -/**@}*/ - - -/** @name Diff Processor Functions - * - * These are the functions you apply to a diff to process it - * or read it in some way. - */ -/**@{*/ - -/** - * Query how many diff records are there in a diff. - * - * @param diff A git_diff generated by one of the above functions - * @return Count of number of deltas in the list - */ -GIT_EXTERN(size_t) git_diff_num_deltas(const git_diff *diff); - -/** - * Query how many diff deltas are there in a diff filtered by type. - * - * This works just like `git_diff_num_deltas()` with an extra parameter - * that is a `git_delta_t` and returns just the count of how many deltas - * match that particular type. - * - * @param diff A git_diff generated by one of the above functions - * @param type A git_delta_t value to filter the count - * @return Count of number of deltas matching delta_t type - */ -GIT_EXTERN(size_t) git_diff_num_deltas_of_type( - const git_diff *diff, git_delta_t type); - -/** - * Return the diff delta for an entry in the diff list. - * - * The `git_diff_delta` pointer points to internal data and you do not - * have to release it when you are done with it. It will go away when - * the * `git_diff` (or any associated `git_patch`) goes away. - * - * Note that the flags on the delta related to whether it has binary - * content or not may not be set if there are no attributes set for the - * file and there has been no reason to load the file data at this point. - * For now, if you need those flags to be up to date, your only option is - * to either use `git_diff_foreach` or create a `git_patch`. - * - * @param diff Diff list object - * @param idx Index into diff list - * @return Pointer to git_diff_delta (or NULL if `idx` out of range) - */ -GIT_EXTERN(const git_diff_delta *) git_diff_get_delta( - const git_diff *diff, size_t idx); - -/** - * Check if deltas are sorted case sensitively or insensitively. - * - * @param diff diff to check - * @return 0 if case sensitive, 1 if case is ignored - */ -GIT_EXTERN(int) git_diff_is_sorted_icase(const git_diff *diff); - -/** - * Loop over all deltas in a diff issuing callbacks. - * - * This will iterate through all of the files described in a diff. You - * should provide a file callback to learn about each file. - * - * The "hunk" and "line" callbacks are optional, and the text diff of the - * files will only be calculated if they are not NULL. Of course, these - * callbacks will not be invoked for binary files on the diff or for - * files whose only changed is a file mode change. - * - * Returning a non-zero value from any of the callbacks will terminate - * the iteration and return the value to the user. - * - * @param diff A git_diff generated by one of the above functions. - * @param file_cb Callback function to make per file in the diff. - * @param binary_cb Optional callback to make for binary files. - * @param hunk_cb Optional callback to make per hunk of text diff. This - * callback is called to describe a range of lines in the - * diff. It will not be issued for binary files. - * @param line_cb Optional callback to make per line of diff text. This - * same callback will be made for context lines, added, and - * removed lines, and even for a deleted trailing newline. - * @param payload Reference pointer that will be passed to your callbacks. - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_diff_foreach( - git_diff *diff, - git_diff_file_cb file_cb, - git_diff_binary_cb binary_cb, - git_diff_hunk_cb hunk_cb, - git_diff_line_cb line_cb, - void *payload); - -/** - * Look up the single character abbreviation for a delta status code. - * - * When you run `git diff --name-status` it uses single letter codes in - * the output such as 'A' for added, 'D' for deleted, 'M' for modified, - * etc. This function converts a git_delta_t value into these letters for - * your own purposes. GIT_DELTA_UNTRACKED will return a space (i.e. ' '). - * - * @param status The git_delta_t value to look up - * @return The single character label for that code - */ -GIT_EXTERN(char) git_diff_status_char(git_delta_t status); - -/** - * Possible output formats for diff data - */ -typedef enum { - GIT_DIFF_FORMAT_PATCH = 1u, /**< full git diff */ - GIT_DIFF_FORMAT_PATCH_HEADER = 2u, /**< just the file headers of patch */ - GIT_DIFF_FORMAT_RAW = 3u, /**< like git diff --raw */ - GIT_DIFF_FORMAT_NAME_ONLY = 4u, /**< like git diff --name-only */ - GIT_DIFF_FORMAT_NAME_STATUS = 5u, /**< like git diff --name-status */ - GIT_DIFF_FORMAT_PATCH_ID = 6u /**< git diff as used by git patch-id */ -} git_diff_format_t; - -/** - * Iterate over a diff generating formatted text output. - * - * Returning a non-zero value from the callbacks will terminate the - * iteration and return the non-zero value to the caller. - * - * @param diff A git_diff generated by one of the above functions. - * @param format A git_diff_format_t value to pick the text format. - * @param print_cb Callback to make per line of diff text. - * @param payload Reference pointer that will be passed to your callback. - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_diff_print( - git_diff *diff, - git_diff_format_t format, - git_diff_line_cb print_cb, - void *payload); - -/** - * Produce the complete formatted text output from a diff into a - * buffer. - * - * @param out A pointer to a user-allocated git_buf that will - * contain the diff text - * @param diff A git_diff generated by one of the above functions. - * @param format A git_diff_format_t value to pick the text format. - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_diff_to_buf( - git_buf *out, - git_diff *diff, - git_diff_format_t format); - -/**@}*/ - -/* - * Low-level file comparison, invoking callbacks per difference. - */ - -/** - * Directly run a diff on two blobs. - * - * Compared to a file, a blob lacks some contextual information. As such, - * the `git_diff_file` given to the callback will have some fake data; i.e. - * `mode` will be 0 and `path` will be NULL. - * - * NULL is allowed for either `old_blob` or `new_blob` and will be treated - * as an empty blob, with the `oid` set to NULL in the `git_diff_file` data. - * Passing NULL for both blobs is a noop; no callbacks will be made at all. - * - * We do run a binary content check on the blob content and if either blob - * looks like binary data, the `git_diff_delta` binary attribute will be set - * to 1 and no call to the hunk_cb nor line_cb will be made (unless you pass - * `GIT_DIFF_FORCE_TEXT` of course). - * - * @param old_blob Blob for old side of diff, or NULL for empty blob - * @param old_as_path Treat old blob as if it had this filename; can be NULL - * @param new_blob Blob for new side of diff, or NULL for empty blob - * @param new_as_path Treat new blob as if it had this filename; can be NULL - * @param options Options for diff, or NULL for default options - * @param file_cb Callback for "file"; made once if there is a diff; can be NULL - * @param binary_cb Callback for binary files; can be NULL - * @param hunk_cb Callback for each hunk in diff; can be NULL - * @param line_cb Callback for each line in diff; can be NULL - * @param payload Payload passed to each callback function - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_diff_blobs( - const git_blob *old_blob, - const char *old_as_path, - const git_blob *new_blob, - const char *new_as_path, - const git_diff_options *options, - git_diff_file_cb file_cb, - git_diff_binary_cb binary_cb, - git_diff_hunk_cb hunk_cb, - git_diff_line_cb line_cb, - void *payload); - -/** - * Directly run a diff between a blob and a buffer. - * - * As with `git_diff_blobs`, comparing a blob and buffer lacks some context, - * so the `git_diff_file` parameters to the callbacks will be faked a la the - * rules for `git_diff_blobs()`. - * - * Passing NULL for `old_blob` will be treated as an empty blob (i.e. the - * `file_cb` will be invoked with GIT_DELTA_ADDED and the diff will be the - * entire content of the buffer added). Passing NULL to the buffer will do - * the reverse, with GIT_DELTA_REMOVED and blob content removed. - * - * @param old_blob Blob for old side of diff, or NULL for empty blob - * @param old_as_path Treat old blob as if it had this filename; can be NULL - * @param buffer Raw data for new side of diff, or NULL for empty - * @param buffer_len Length of raw data for new side of diff - * @param buffer_as_path Treat buffer as if it had this filename; can be NULL - * @param options Options for diff, or NULL for default options - * @param file_cb Callback for "file"; made once if there is a diff; can be NULL - * @param binary_cb Callback for binary files; can be NULL - * @param hunk_cb Callback for each hunk in diff; can be NULL - * @param line_cb Callback for each line in diff; can be NULL - * @param payload Payload passed to each callback function - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_diff_blob_to_buffer( - const git_blob *old_blob, - const char *old_as_path, - const char *buffer, - size_t buffer_len, - const char *buffer_as_path, - const git_diff_options *options, - git_diff_file_cb file_cb, - git_diff_binary_cb binary_cb, - git_diff_hunk_cb hunk_cb, - git_diff_line_cb line_cb, - void *payload); - -/** - * Directly run a diff between two buffers. - * - * Even more than with `git_diff_blobs`, comparing two buffer lacks - * context, so the `git_diff_file` parameters to the callbacks will be - * faked a la the rules for `git_diff_blobs()`. - * - * @param old_buffer Raw data for old side of diff, or NULL for empty - * @param old_len Length of the raw data for old side of the diff - * @param old_as_path Treat old buffer as if it had this filename; can be NULL - * @param new_buffer Raw data for new side of diff, or NULL for empty - * @param new_len Length of raw data for new side of diff - * @param new_as_path Treat buffer as if it had this filename; can be NULL - * @param options Options for diff, or NULL for default options - * @param file_cb Callback for "file"; made once if there is a diff; can be NULL - * @param binary_cb Callback for binary files; can be NULL - * @param hunk_cb Callback for each hunk in diff; can be NULL - * @param line_cb Callback for each line in diff; can be NULL - * @param payload Payload passed to each callback function - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_diff_buffers( - const void *old_buffer, - size_t old_len, - const char *old_as_path, - const void *new_buffer, - size_t new_len, - const char *new_as_path, - const git_diff_options *options, - git_diff_file_cb file_cb, - git_diff_binary_cb binary_cb, - git_diff_hunk_cb hunk_cb, - git_diff_line_cb line_cb, - void *payload); - -/* Patch file parsing. */ - -/** - * Options for parsing a diff / patch file. - */ -typedef struct { - unsigned int version; - git_oid_t oid_type; -} git_diff_parse_options; - -/* The current version of the diff parse options structure */ -#define GIT_DIFF_PARSE_OPTIONS_VERSION 1 - -/* Stack initializer for diff parse options. Alternatively use - * `git_diff_parse_options_init` programmatic initialization. - */ -#define GIT_DIFF_PARSE_OPTIONS_INIT \ - { GIT_DIFF_PARSE_OPTIONS_VERSION, GIT_OID_DEFAULT } - -/** - * Read the contents of a git patch file into a `git_diff` object. - * - * The diff object produced is similar to the one that would be - * produced if you actually produced it computationally by comparing - * two trees, however there may be subtle differences. For example, - * a patch file likely contains abbreviated object IDs, so the - * object IDs in a `git_diff_delta` produced by this function will - * also be abbreviated. - * - * This function will only read patch files created by a git - * implementation, it will not read unified diffs produced by - * the `diff` program, nor any other types of patch files. - * - * @param out A pointer to a git_diff pointer that will be allocated. - * @param content The contents of a patch file - * @param content_len The length of the patch file contents - * @return 0 or an error code - */ -GIT_EXTERN(int) git_diff_from_buffer( - git_diff **out, - const char *content, - size_t content_len -#ifdef GIT_EXPERIMENTAL_SHA256 - , git_diff_parse_options *opts -#endif - ); - -/** - * This is an opaque structure which is allocated by `git_diff_get_stats`. - * You are responsible for releasing the object memory when done, using the - * `git_diff_stats_free()` function. - */ -typedef struct git_diff_stats git_diff_stats; - -/** - * Formatting options for diff stats - */ -typedef enum { - /** No stats*/ - GIT_DIFF_STATS_NONE = 0, - - /** Full statistics, equivalent of `--stat` */ - GIT_DIFF_STATS_FULL = (1u << 0), - - /** Short statistics, equivalent of `--shortstat` */ - GIT_DIFF_STATS_SHORT = (1u << 1), - - /** Number statistics, equivalent of `--numstat` */ - GIT_DIFF_STATS_NUMBER = (1u << 2), - - /** Extended header information such as creations, renames and mode changes, equivalent of `--summary` */ - GIT_DIFF_STATS_INCLUDE_SUMMARY = (1u << 3) -} git_diff_stats_format_t; - -/** - * Accumulate diff statistics for all patches. - * - * @param out Structure containing the diff statistics. - * @param diff A git_diff generated by one of the above functions. - * @return 0 on success; non-zero on error - */ -GIT_EXTERN(int) git_diff_get_stats( - git_diff_stats **out, - git_diff *diff); - -/** - * Get the total number of files changed in a diff - * - * @param stats A `git_diff_stats` generated by one of the above functions. - * @return total number of files changed in the diff - */ -GIT_EXTERN(size_t) git_diff_stats_files_changed( - const git_diff_stats *stats); - -/** - * Get the total number of insertions in a diff - * - * @param stats A `git_diff_stats` generated by one of the above functions. - * @return total number of insertions in the diff - */ -GIT_EXTERN(size_t) git_diff_stats_insertions( - const git_diff_stats *stats); - -/** - * Get the total number of deletions in a diff - * - * @param stats A `git_diff_stats` generated by one of the above functions. - * @return total number of deletions in the diff - */ -GIT_EXTERN(size_t) git_diff_stats_deletions( - const git_diff_stats *stats); - -/** - * Print diff statistics to a `git_buf`. - * - * @param out buffer to store the formatted diff statistics in. - * @param stats A `git_diff_stats` generated by one of the above functions. - * @param format Formatting option. - * @param width Target width for output (only affects GIT_DIFF_STATS_FULL) - * @return 0 on success; non-zero on error - */ -GIT_EXTERN(int) git_diff_stats_to_buf( - git_buf *out, - const git_diff_stats *stats, - git_diff_stats_format_t format, - size_t width); - -/** - * Deallocate a `git_diff_stats`. - * - * @param stats The previously created statistics object; - * cannot be used after free. - */ -GIT_EXTERN(void) git_diff_stats_free(git_diff_stats *stats); - -/** - * Patch ID options structure - * - * Initialize with `GIT_PATCHID_OPTIONS_INIT`. Alternatively, you can - * use `git_diff_patchid_options_init`. - * - */ -typedef struct git_diff_patchid_options { - unsigned int version; -} git_diff_patchid_options; - -#define GIT_DIFF_PATCHID_OPTIONS_VERSION 1 -#define GIT_DIFF_PATCHID_OPTIONS_INIT { GIT_DIFF_PATCHID_OPTIONS_VERSION } - -/** - * Initialize git_diff_patchid_options structure - * - * Initializes a `git_diff_patchid_options` with default values. Equivalent to - * creating an instance with `GIT_DIFF_PATCHID_OPTIONS_INIT`. - * - * @param opts The `git_diff_patchid_options` struct to initialize. - * @param version The struct version; pass `GIT_DIFF_PATCHID_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_diff_patchid_options_init( - git_diff_patchid_options *opts, - unsigned int version); - -/** - * Calculate the patch ID for the given patch. - * - * Calculate a stable patch ID for the given patch by summing the - * hash of the file diffs, ignoring whitespace and line numbers. - * This can be used to derive whether two diffs are the same with - * a high probability. - * - * Currently, this function only calculates stable patch IDs, as - * defined in git-patch-id(1), and should in fact generate the - * same IDs as the upstream git project does. - * - * @param out Pointer where the calculated patch ID should be stored - * @param diff The diff to calculate the ID for - * @param opts Options for how to calculate the patch ID. This is - * intended for future changes, as currently no options are - * available. - * @return 0 on success, an error code otherwise. - */ -GIT_EXTERN(int) git_diff_patchid(git_oid *out, git_diff *diff, git_diff_patchid_options *opts); - -GIT_END_DECL - -/** @} */ - -#endif +/* + * 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_diff_h__ +#define INCLUDE_git_diff_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "tree.h" +#include "refs.h" + +/** + * @file git2/diff.h + * @brief Git tree and file differencing routines. + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Flags for diff options. A combination of these flags can be passed + * in via the `flags` value in the `git_diff_options`. + */ +typedef enum { + /** Normal diff, the default */ + GIT_DIFF_NORMAL = 0, + + /* + * Options controlling which files will be in the diff + */ + + /** Reverse the sides of the diff */ + GIT_DIFF_REVERSE = (1u << 0), + + /** Include ignored files in the diff */ + GIT_DIFF_INCLUDE_IGNORED = (1u << 1), + + /** Even with GIT_DIFF_INCLUDE_IGNORED, an entire ignored directory + * will be marked with only a single entry in the diff; this flag + * adds all files under the directory as IGNORED entries, too. + */ + GIT_DIFF_RECURSE_IGNORED_DIRS = (1u << 2), + + /** Include untracked files in the diff */ + GIT_DIFF_INCLUDE_UNTRACKED = (1u << 3), + + /** Even with GIT_DIFF_INCLUDE_UNTRACKED, an entire untracked + * directory will be marked with only a single entry in the diff + * (a la what core Git does in `git status`); this flag adds *all* + * files under untracked directories as UNTRACKED entries, too. + */ + GIT_DIFF_RECURSE_UNTRACKED_DIRS = (1u << 4), + + /** Include unmodified files in the diff */ + GIT_DIFF_INCLUDE_UNMODIFIED = (1u << 5), + + /** Normally, a type change between files will be converted into a + * DELETED record for the old and an ADDED record for the new; this + * options enabled the generation of TYPECHANGE delta records. + */ + GIT_DIFF_INCLUDE_TYPECHANGE = (1u << 6), + + /** Even with GIT_DIFF_INCLUDE_TYPECHANGE, blob->tree changes still + * generally show as a DELETED blob. This flag tries to correctly + * label blob->tree transitions as TYPECHANGE records with new_file's + * mode set to tree. Note: the tree SHA will not be available. + */ + GIT_DIFF_INCLUDE_TYPECHANGE_TREES = (1u << 7), + + /** Ignore file mode changes */ + GIT_DIFF_IGNORE_FILEMODE = (1u << 8), + + /** Treat all submodules as unmodified */ + GIT_DIFF_IGNORE_SUBMODULES = (1u << 9), + + /** Use case insensitive filename comparisons */ + GIT_DIFF_IGNORE_CASE = (1u << 10), + + /** May be combined with `GIT_DIFF_IGNORE_CASE` to specify that a file + * that has changed case will be returned as an add/delete pair. + */ + GIT_DIFF_INCLUDE_CASECHANGE = (1u << 11), + + /** If the pathspec is set in the diff options, this flags indicates + * that the paths will be treated as literal paths instead of + * fnmatch patterns. Each path in the list must either be a full + * path to a file or a directory. (A trailing slash indicates that + * the path will _only_ match a directory). If a directory is + * specified, all children will be included. + */ + GIT_DIFF_DISABLE_PATHSPEC_MATCH = (1u << 12), + + /** Disable updating of the `binary` flag in delta records. This is + * useful when iterating over a diff if you don't need hunk and data + * callbacks and want to avoid having to load file completely. + */ + GIT_DIFF_SKIP_BINARY_CHECK = (1u << 13), + + /** When diff finds an untracked directory, to match the behavior of + * core Git, it scans the contents for IGNORED and UNTRACKED files. + * If *all* contents are IGNORED, then the directory is IGNORED; if + * any contents are not IGNORED, then the directory is UNTRACKED. + * This is extra work that may not matter in many cases. This flag + * turns off that scan and immediately labels an untracked directory + * as UNTRACKED (changing the behavior to not match core Git). + */ + GIT_DIFF_ENABLE_FAST_UNTRACKED_DIRS = (1u << 14), + + /** When diff finds a file in the working directory with stat + * information different from the index, but the OID ends up being the + * same, write the correct stat information into the index. Note: + * without this flag, diff will always leave the index untouched. + */ + GIT_DIFF_UPDATE_INDEX = (1u << 15), + + /** Include unreadable files in the diff */ + GIT_DIFF_INCLUDE_UNREADABLE = (1u << 16), + + /** Include unreadable files in the diff */ + GIT_DIFF_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 17), + + /* + * Options controlling how output will be generated + */ + + /** Use a heuristic that takes indentation and whitespace into account + * which generally can produce better diffs when dealing with ambiguous + * diff hunks. + */ + GIT_DIFF_INDENT_HEURISTIC = (1u << 18), + + /** Ignore blank lines */ + GIT_DIFF_IGNORE_BLANK_LINES = (1u << 19), + + /** Treat all files as text, disabling binary attributes & detection */ + GIT_DIFF_FORCE_TEXT = (1u << 20), + /** Treat all files as binary, disabling text diffs */ + GIT_DIFF_FORCE_BINARY = (1u << 21), + + /** Ignore all whitespace */ + GIT_DIFF_IGNORE_WHITESPACE = (1u << 22), + /** Ignore changes in amount of whitespace */ + GIT_DIFF_IGNORE_WHITESPACE_CHANGE = (1u << 23), + /** Ignore whitespace at end of line */ + GIT_DIFF_IGNORE_WHITESPACE_EOL = (1u << 24), + + /** When generating patch text, include the content of untracked + * files. This automatically turns on GIT_DIFF_INCLUDE_UNTRACKED but + * it does not turn on GIT_DIFF_RECURSE_UNTRACKED_DIRS. Add that + * flag if you want the content of every single UNTRACKED file. + */ + GIT_DIFF_SHOW_UNTRACKED_CONTENT = (1u << 25), + + /** When generating output, include the names of unmodified files if + * they are included in the git_diff. Normally these are skipped in + * the formats that list files (e.g. name-only, name-status, raw). + * Even with this, these will not be included in patch format. + */ + GIT_DIFF_SHOW_UNMODIFIED = (1u << 26), + + /** Use the "patience diff" algorithm */ + GIT_DIFF_PATIENCE = (1u << 28), + /** Take extra time to find minimal diff */ + GIT_DIFF_MINIMAL = (1u << 29), + + /** Include the necessary deflate / delta information so that `git-apply` + * can apply given diff information to binary files. + */ + GIT_DIFF_SHOW_BINARY = (1u << 30) +} git_diff_option_t; + +/** + * The diff object that contains all individual file deltas. + * + * A `diff` represents the cumulative list of differences between two + * snapshots of a repository (possibly filtered by a set of file name + * patterns). + * + * Calculating diffs is generally done in two phases: building a list of + * diffs then traversing it. This makes is easier to share logic across + * the various types of diffs (tree vs tree, workdir vs index, etc.), and + * also allows you to insert optional diff post-processing phases, + * such as rename detection, in between the steps. When you are done with + * a diff object, it must be freed. + * + * This is an opaque structure which will be allocated by one of the diff + * generator functions below (such as `git_diff_tree_to_tree`). You are + * responsible for releasing the object memory when done, using the + * `git_diff_free()` function. + * + */ +typedef struct git_diff git_diff; + +/** + * Flags for the delta object and the file objects on each side. + * + * These flags are used for both the `flags` value of the `git_diff_delta` + * and the flags for the `git_diff_file` objects representing the old and + * new sides of the delta. Values outside of this public range should be + * considered reserved for internal or future use. + */ +typedef enum { + GIT_DIFF_FLAG_BINARY = (1u << 0), /**< file(s) treated as binary data */ + GIT_DIFF_FLAG_NOT_BINARY = (1u << 1), /**< file(s) treated as text data */ + GIT_DIFF_FLAG_VALID_ID = (1u << 2), /**< `id` value is known correct */ + GIT_DIFF_FLAG_EXISTS = (1u << 3), /**< file exists at this side of the delta */ + GIT_DIFF_FLAG_VALID_SIZE = (1u << 4) /**< file size value is known correct */ +} git_diff_flag_t; + +/** + * What type of change is described by a git_diff_delta? + * + * `GIT_DELTA_RENAMED` and `GIT_DELTA_COPIED` will only show up if you run + * `git_diff_find_similar()` on the diff object. + * + * `GIT_DELTA_TYPECHANGE` only shows up given `GIT_DIFF_INCLUDE_TYPECHANGE` + * in the option flags (otherwise type changes will be split into ADDED / + * DELETED pairs). + */ +typedef enum { + GIT_DELTA_UNMODIFIED = 0, /**< no changes */ + GIT_DELTA_ADDED = 1, /**< entry does not exist in old version */ + GIT_DELTA_DELETED = 2, /**< entry does not exist in new version */ + GIT_DELTA_MODIFIED = 3, /**< entry content changed between old and new */ + GIT_DELTA_RENAMED = 4, /**< entry was renamed between old and new */ + GIT_DELTA_COPIED = 5, /**< entry was copied from another old entry */ + GIT_DELTA_IGNORED = 6, /**< entry is ignored item in workdir */ + GIT_DELTA_UNTRACKED = 7, /**< entry is untracked item in workdir */ + GIT_DELTA_TYPECHANGE = 8, /**< type of entry changed between old and new */ + GIT_DELTA_UNREADABLE = 9, /**< entry is unreadable */ + GIT_DELTA_CONFLICTED = 10 /**< entry in the index is conflicted */ +} git_delta_t; + +/** + * Description of one side of a delta. + * + * Although this is called a "file", it could represent a file, a symbolic + * link, a submodule commit id, or even a tree (although that only if you + * are tracking type changes or ignored/untracked directories). + */ +typedef struct { + /** + * The `git_oid` of the item. If the entry represents an + * absent side of a diff (e.g. the `old_file` of a `GIT_DELTA_ADDED` delta), + * then the oid will be zeroes. + */ + git_oid id; + + /** + * The NUL-terminated path to the entry relative to the working + * directory of the repository. + */ + const char *path; + + /** + * The size of the entry in bytes. + */ + git_object_size_t size; + + /** + * A combination of the `git_diff_flag_t` types + */ + uint32_t flags; + + /** + * Roughly, the stat() `st_mode` value for the item. This will + * be restricted to one of the `git_filemode_t` values. + */ + uint16_t mode; + + /** + * Represents the known length of the `id` field, when + * converted to a hex string. It is generally `GIT_OID_SHA1_HEXSIZE`, unless this + * delta was created from reading a patch file, in which case it may be + * abbreviated to something reasonable, like 7 characters. + */ + uint16_t id_abbrev; +} git_diff_file; + +/** + * Description of changes to one entry. + * + * A `delta` is a file pair with an old and new revision. The old version + * may be absent if the file was just created and the new version may be + * absent if the file was deleted. A diff is mostly just a list of deltas. + * + * When iterating over a diff, this will be passed to most callbacks and + * you can use the contents to understand exactly what has changed. + * + * The `old_file` represents the "from" side of the diff and the `new_file` + * represents to "to" side of the diff. What those means depend on the + * function that was used to generate the diff and will be documented below. + * You can also use the `GIT_DIFF_REVERSE` flag to flip it around. + * + * Although the two sides of the delta are named "old_file" and "new_file", + * they actually may correspond to entries that represent a file, a symbolic + * link, a submodule commit id, or even a tree (if you are tracking type + * changes or ignored/untracked directories). + * + * Under some circumstances, in the name of efficiency, not all fields will + * be filled in, but we generally try to fill in as much as possible. One + * example is that the "flags" field may not have either the `BINARY` or the + * `NOT_BINARY` flag set to avoid examining file contents if you do not pass + * in hunk and/or line callbacks to the diff foreach iteration function. It + * will just use the git attributes for those files. + * + * The similarity score is zero unless you call `git_diff_find_similar()` + * which does a similarity analysis of files in the diff. Use that + * function to do rename and copy detection, and to split heavily modified + * files in add/delete pairs. After that call, deltas with a status of + * GIT_DELTA_RENAMED or GIT_DELTA_COPIED will have a similarity score + * between 0 and 100 indicating how similar the old and new sides are. + * + * If you ask `git_diff_find_similar` to find heavily modified files to + * break, but to not *actually* break the records, then GIT_DELTA_MODIFIED + * records may have a non-zero similarity score if the self-similarity is + * below the split threshold. To display this value like core Git, invert + * the score (a la `printf("M%03d", 100 - delta->similarity)`). + */ +typedef struct { + git_delta_t status; + uint32_t flags; /**< git_diff_flag_t values */ + uint16_t similarity; /**< for RENAMED and COPIED, value 0-100 */ + uint16_t nfiles; /**< number of files in this delta */ + git_diff_file old_file; + git_diff_file new_file; +} git_diff_delta; + +/** + * Diff notification callback function. + * + * The callback will be called for each file, just before the `git_diff_delta` + * gets inserted into the diff. + * + * When the callback: + * - returns < 0, the diff process will be aborted. + * - returns > 0, the delta will not be inserted into the diff, but the + * diff process continues. + * - returns 0, the delta is inserted into the diff, and the diff process + * continues. + */ +typedef int GIT_CALLBACK(git_diff_notify_cb)( + const git_diff *diff_so_far, + const git_diff_delta *delta_to_add, + const char *matched_pathspec, + void *payload); + +/** + * Diff progress callback. + * + * Called before each file comparison. + * + * @param diff_so_far The diff being generated. + * @param old_path The path to the old file or NULL. + * @param new_path The path to the new file or NULL. + * @return Non-zero to abort the diff. + */ +typedef int GIT_CALLBACK(git_diff_progress_cb)( + const git_diff *diff_so_far, + const char *old_path, + const char *new_path, + void *payload); + +/** + * Structure describing options about how the diff should be executed. + * + * Setting all values of the structure to zero will yield the default + * values. Similarly, passing NULL for the options structure will + * give the defaults. The default values are marked below. + * + */ +typedef struct { + unsigned int version; /**< version for the struct */ + + /** + * A combination of `git_diff_option_t` values above. + * Defaults to GIT_DIFF_NORMAL + */ + uint32_t flags; + + /* options controlling which files are in the diff */ + + /** Overrides the submodule ignore setting for all submodules in the diff. */ + git_submodule_ignore_t ignore_submodules; + + /** + * An array of paths / fnmatch patterns to constrain diff. + * All paths are included by default. + */ + git_strarray pathspec; + + /** + * An optional callback function, notifying the consumer of changes to + * the diff as new deltas are added. + */ + git_diff_notify_cb notify_cb; + + /** + * An optional callback function, notifying the consumer of which files + * are being examined as the diff is generated. + */ + git_diff_progress_cb progress_cb; + + /** The payload to pass to the callback functions. */ + void *payload; + + /* options controlling how to diff text is generated */ + + /** + * The number of unchanged lines that define the boundary of a hunk + * (and to display before and after). Defaults to 3. + */ + uint32_t context_lines; + /** + * The maximum number of unchanged lines between hunk boundaries before + * the hunks will be merged into one. Defaults to 0. + */ + uint32_t interhunk_lines; + + /** + * The object ID type to emit in diffs; this is used by functions + * that operate without a repository - namely `git_diff_buffers`, + * or `git_diff_blobs` and `git_diff_blob_to_buffer` when one blob + * is `NULL`. + * + * This may be omitted (set to `0`). If a repository is available, + * the object ID format of the repository will be used. If no + * repository is available then the default is `GIT_OID_SHA`. + * + * If this is specified and a repository is available, then the + * specified `oid_type` must match the repository's object ID + * format. + */ + git_oid_t oid_type; + + /** + * The abbreviation length to use when formatting object ids. + * Defaults to the value of 'core.abbrev' from the config, or 7 if unset. + */ + uint16_t id_abbrev; + + /** + * A size (in bytes) above which a blob will be marked as binary + * automatically; pass a negative value to disable. + * Defaults to 512MB. + */ + git_off_t max_size; + + /** + * The virtual "directory" prefix for old file names in hunk headers. + * Default is "a". + */ + const char *old_prefix; + + /** + * The virtual "directory" prefix for new file names in hunk headers. + * Defaults to "b". + */ + const char *new_prefix; +} git_diff_options; + +/* The current version of the diff options structure */ +#define GIT_DIFF_OPTIONS_VERSION 1 + +/* Stack initializer for diff options. Alternatively use + * `git_diff_options_init` programmatic initialization. + */ +#define GIT_DIFF_OPTIONS_INIT \ + {GIT_DIFF_OPTIONS_VERSION, 0, GIT_SUBMODULE_IGNORE_UNSPECIFIED, {NULL,0}, NULL, NULL, NULL, 3} + +/** + * Initialize git_diff_options structure + * + * Initializes a `git_diff_options` with default values. Equivalent to creating + * an instance with GIT_DIFF_OPTIONS_INIT. + * + * @param opts The `git_diff_options` struct to initialize. + * @param version The struct version; pass `GIT_DIFF_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_diff_options_init( + git_diff_options *opts, + unsigned int version); + +/** + * When iterating over a diff, callback that will be made per file. + * + * @param delta A pointer to the delta data for the file + * @param progress Goes from 0 to 1 over the diff + * @param payload User-specified pointer from foreach function + */ +typedef int GIT_CALLBACK(git_diff_file_cb)( + const git_diff_delta *delta, + float progress, + void *payload); + +#define GIT_DIFF_HUNK_HEADER_SIZE 128 + +/** + * When producing a binary diff, the binary data returned will be + * either the deflated full ("literal") contents of the file, or + * the deflated binary delta between the two sides (whichever is + * smaller). + */ +typedef enum { + /** There is no binary delta. */ + GIT_DIFF_BINARY_NONE, + + /** The binary data is the literal contents of the file. */ + GIT_DIFF_BINARY_LITERAL, + + /** The binary data is the delta from one side to the other. */ + GIT_DIFF_BINARY_DELTA +} git_diff_binary_t; + +/** The contents of one of the files in a binary diff. */ +typedef struct { + /** The type of binary data for this file. */ + git_diff_binary_t type; + + /** The binary data, deflated. */ + const char *data; + + /** The length of the binary data. */ + size_t datalen; + + /** The length of the binary data after inflation. */ + size_t inflatedlen; +} git_diff_binary_file; + +/** + * Structure describing the binary contents of a diff. + * + * A `binary` file / delta is a file (or pair) for which no text diffs + * should be generated. A diff can contain delta entries that are + * binary, but no diff content will be output for those files. There is + * a base heuristic for binary detection and you can further tune the + * behavior with git attributes or diff flags and option settings. + */ +typedef struct { + /** + * Whether there is data in this binary structure or not. + * + * If this is `1`, then this was produced and included binary content. + * If this is `0` then this was generated knowing only that a binary + * file changed but without providing the data, probably from a patch + * that said `Binary files a/file.txt and b/file.txt differ`. + */ + unsigned int contains_data; + git_diff_binary_file old_file; /**< The contents of the old file. */ + git_diff_binary_file new_file; /**< The contents of the new file. */ +} git_diff_binary; + +/** + * When iterating over a diff, callback that will be made for + * binary content within the diff. + */ +typedef int GIT_CALLBACK(git_diff_binary_cb)( + const git_diff_delta *delta, + const git_diff_binary *binary, + void *payload); + +/** + * Structure describing a hunk of a diff. + * + * A `hunk` is a span of modified lines in a delta along with some stable + * surrounding context. You can configure the amount of context and other + * properties of how hunks are generated. Each hunk also comes with a + * header that described where it starts and ends in both the old and new + * versions in the delta. + */ +typedef struct { + int old_start; /**< Starting line number in old_file */ + int old_lines; /**< Number of lines in old_file */ + int new_start; /**< Starting line number in new_file */ + int new_lines; /**< Number of lines in new_file */ + size_t header_len; /**< Number of bytes in header text */ + char header[GIT_DIFF_HUNK_HEADER_SIZE]; /**< Header text, NUL-byte terminated */ +} git_diff_hunk; + +/** + * When iterating over a diff, callback that will be made per hunk. + */ +typedef int GIT_CALLBACK(git_diff_hunk_cb)( + const git_diff_delta *delta, + const git_diff_hunk *hunk, + void *payload); + +/** + * Line origin constants. + * + * These values describe where a line came from and will be passed to + * the git_diff_line_cb when iterating over a diff. There are some + * special origin constants at the end that are used for the text + * output callbacks to demarcate lines that are actually part of + * the file or hunk headers. + */ +typedef enum { + /* These values will be sent to `git_diff_line_cb` along with the line */ + GIT_DIFF_LINE_CONTEXT = ' ', + GIT_DIFF_LINE_ADDITION = '+', + GIT_DIFF_LINE_DELETION = '-', + + GIT_DIFF_LINE_CONTEXT_EOFNL = '=', /**< Both files have no LF at end */ + GIT_DIFF_LINE_ADD_EOFNL = '>', /**< Old has no LF at end, new does */ + GIT_DIFF_LINE_DEL_EOFNL = '<', /**< Old has LF at end, new does not */ + + /* The following values will only be sent to a `git_diff_line_cb` when + * the content of a diff is being formatted through `git_diff_print`. + */ + GIT_DIFF_LINE_FILE_HDR = 'F', + GIT_DIFF_LINE_HUNK_HDR = 'H', + GIT_DIFF_LINE_BINARY = 'B' /**< For "Binary files x and y differ" */ +} git_diff_line_t; + +/** + * Structure describing a line (or data span) of a diff. + * + * A `line` is a range of characters inside a hunk. It could be a context + * line (i.e. in both old and new versions), an added line (i.e. only in + * the new version), or a removed line (i.e. only in the old version). + * Unfortunately, we don't know anything about the encoding of data in the + * file being diffed, so we cannot tell you much about the line content. + * Line data will not be NUL-byte terminated, however, because it will be + * just a span of bytes inside the larger file. + */ +typedef struct { + char origin; /**< A git_diff_line_t value */ + int old_lineno; /**< Line number in old file or -1 for added line */ + int new_lineno; /**< Line number in new file or -1 for deleted line */ + int num_lines; /**< Number of newline characters in content */ + size_t content_len; /**< Number of bytes of data */ + git_off_t content_offset; /**< Offset in the original file to the content */ + const char *content; /**< Pointer to diff text, not NUL-byte terminated */ +} git_diff_line; + +/** + * When iterating over a diff, callback that will be made per text diff + * line. In this context, the provided range will be NULL. + * + * When printing a diff, callback that will be made to output each line + * of text. This uses some extra GIT_DIFF_LINE_... constants for output + * of lines of file and hunk headers. + */ +typedef int GIT_CALLBACK(git_diff_line_cb)( + const git_diff_delta *delta, /**< delta that contains this data */ + const git_diff_hunk *hunk, /**< hunk containing this data */ + const git_diff_line *line, /**< line data */ + void *payload); /**< user reference data */ + +/** + * Flags to control the behavior of diff rename/copy detection. + */ +typedef enum { + /** Obey `diff.renames`. Overridden by any other GIT_DIFF_FIND_... flag. */ + GIT_DIFF_FIND_BY_CONFIG = 0, + + /** Look for renames? (`--find-renames`) */ + GIT_DIFF_FIND_RENAMES = (1u << 0), + + /** Consider old side of MODIFIED for renames? (`--break-rewrites=N`) */ + GIT_DIFF_FIND_RENAMES_FROM_REWRITES = (1u << 1), + + /** Look for copies? (a la `--find-copies`). */ + GIT_DIFF_FIND_COPIES = (1u << 2), + + /** Consider UNMODIFIED as copy sources? (`--find-copies-harder`). + * + * For this to work correctly, use GIT_DIFF_INCLUDE_UNMODIFIED when + * the initial `git_diff` is being generated. + */ + GIT_DIFF_FIND_COPIES_FROM_UNMODIFIED = (1u << 3), + + /** Mark significant rewrites for split (`--break-rewrites=/M`) */ + GIT_DIFF_FIND_REWRITES = (1u << 4), + /** Actually split large rewrites into delete/add pairs */ + GIT_DIFF_BREAK_REWRITES = (1u << 5), + /** Mark rewrites for split and break into delete/add pairs */ + GIT_DIFF_FIND_AND_BREAK_REWRITES = + (GIT_DIFF_FIND_REWRITES | GIT_DIFF_BREAK_REWRITES), + + /** Find renames/copies for UNTRACKED items in working directory. + * + * For this to work correctly, use GIT_DIFF_INCLUDE_UNTRACKED when the + * initial `git_diff` is being generated (and obviously the diff must + * be against the working directory for this to make sense). + */ + GIT_DIFF_FIND_FOR_UNTRACKED = (1u << 6), + + /** Turn on all finding features. */ + GIT_DIFF_FIND_ALL = (0x0ff), + + /** Measure similarity ignoring leading whitespace (default) */ + GIT_DIFF_FIND_IGNORE_LEADING_WHITESPACE = 0, + /** Measure similarity ignoring all whitespace */ + GIT_DIFF_FIND_IGNORE_WHITESPACE = (1u << 12), + /** Measure similarity including all data */ + GIT_DIFF_FIND_DONT_IGNORE_WHITESPACE = (1u << 13), + /** Measure similarity only by comparing SHAs (fast and cheap) */ + GIT_DIFF_FIND_EXACT_MATCH_ONLY = (1u << 14), + + /** Do not break rewrites unless they contribute to a rename. + * + * Normally, GIT_DIFF_FIND_AND_BREAK_REWRITES will measure the self- + * similarity of modified files and split the ones that have changed a + * lot into a DELETE / ADD pair. Then the sides of that pair will be + * considered candidates for rename and copy detection. + * + * If you add this flag in and the split pair is *not* used for an + * actual rename or copy, then the modified record will be restored to + * a regular MODIFIED record instead of being split. + */ + GIT_DIFF_BREAK_REWRITES_FOR_RENAMES_ONLY = (1u << 15), + + /** Remove any UNMODIFIED deltas after find_similar is done. + * + * Using GIT_DIFF_FIND_COPIES_FROM_UNMODIFIED to emulate the + * --find-copies-harder behavior requires building a diff with the + * GIT_DIFF_INCLUDE_UNMODIFIED flag. If you do not want UNMODIFIED + * records in the final result, pass this flag to have them removed. + */ + GIT_DIFF_FIND_REMOVE_UNMODIFIED = (1u << 16) +} git_diff_find_t; + +/** + * Pluggable similarity metric + */ +typedef struct { + int GIT_CALLBACK(file_signature)( + void **out, const git_diff_file *file, + const char *fullpath, void *payload); + int GIT_CALLBACK(buffer_signature)( + void **out, const git_diff_file *file, + const char *buf, size_t buflen, void *payload); + void GIT_CALLBACK(free_signature)(void *sig, void *payload); + int GIT_CALLBACK(similarity)(int *score, void *siga, void *sigb, void *payload); + void *payload; +} git_diff_similarity_metric; + +/** + * Control behavior of rename and copy detection + * + * These options mostly mimic parameters that can be passed to git-diff. + */ +typedef struct { + unsigned int version; + + /** + * Combination of git_diff_find_t values (default GIT_DIFF_FIND_BY_CONFIG). + * NOTE: if you don't explicitly set this, `diff.renames` could be set + * to false, resulting in `git_diff_find_similar` doing nothing. + */ + uint32_t flags; + + /** + * Threshold above which similar files will be considered renames. + * This is equivalent to the -M option. Defaults to 50. + */ + uint16_t rename_threshold; + + /** + * Threshold below which similar files will be eligible to be a rename source. + * This is equivalent to the first part of the -B option. Defaults to 50. + */ + uint16_t rename_from_rewrite_threshold; + + /** + * Threshold above which similar files will be considered copies. + * This is equivalent to the -C option. Defaults to 50. + */ + uint16_t copy_threshold; + + /** + * Threshold below which similar files will be split into a delete/add pair. + * This is equivalent to the last part of the -B option. Defaults to 60. + */ + uint16_t break_rewrite_threshold; + + /** + * Maximum number of matches to consider for a particular file. + * + * This is a little different from the `-l` option from Git because we + * will still process up to this many matches before abandoning the search. + * Defaults to 1000. + */ + size_t rename_limit; + + /** + * The `metric` option allows you to plug in a custom similarity metric. + * + * Set it to NULL to use the default internal metric. + * + * The default metric is based on sampling hashes of ranges of data in + * the file, which is a pretty good similarity approximation that should + * work fairly well for both text and binary data while still being + * pretty fast with a fixed memory overhead. + */ + git_diff_similarity_metric *metric; +} git_diff_find_options; + +#define GIT_DIFF_FIND_OPTIONS_VERSION 1 +#define GIT_DIFF_FIND_OPTIONS_INIT {GIT_DIFF_FIND_OPTIONS_VERSION} + +/** + * Initialize git_diff_find_options structure + * + * Initializes a `git_diff_find_options` with default values. Equivalent to creating + * an instance with GIT_DIFF_FIND_OPTIONS_INIT. + * + * @param opts The `git_diff_find_options` struct to initialize. + * @param version The struct version; pass `GIT_DIFF_FIND_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_diff_find_options_init( + git_diff_find_options *opts, + unsigned int version); + +/** @name Diff Generator Functions + * + * These are the functions you would use to create (or destroy) a + * git_diff from various objects in a repository. + */ +/**@{*/ + +/** + * Deallocate a diff. + * + * @param diff The previously created diff; cannot be used after free. + */ +GIT_EXTERN(void) git_diff_free(git_diff *diff); + +/** + * Create a diff with the difference between two tree objects. + * + * This is equivalent to `git diff ` + * + * The first tree will be used for the "old_file" side of the delta and the + * second tree will be used for the "new_file" side of the delta. You can + * pass NULL to indicate an empty tree, although it is an error to pass + * NULL for both the `old_tree` and `new_tree`. + * + * @param diff Output pointer to a git_diff pointer to be allocated. + * @param repo The repository containing the trees. + * @param old_tree A git_tree object to diff from, or NULL for empty tree. + * @param new_tree A git_tree object to diff to, or NULL for empty tree. + * @param opts Structure with options to influence diff or NULL for defaults. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_diff_tree_to_tree( + git_diff **diff, + git_repository *repo, + git_tree *old_tree, + git_tree *new_tree, + const git_diff_options *opts); + +/** + * Create a diff between a tree and repository index. + * + * This is equivalent to `git diff --cached ` or if you pass + * the HEAD tree, then like `git diff --cached`. + * + * The tree you pass will be used for the "old_file" side of the delta, and + * the index will be used for the "new_file" side of the delta. + * + * If you pass NULL for the index, then the existing index of the `repo` + * will be used. In this case, the index will be refreshed from disk + * (if it has changed) before the diff is generated. + * + * @param diff Output pointer to a git_diff pointer to be allocated. + * @param repo The repository containing the tree and index. + * @param old_tree A git_tree object to diff from, or NULL for empty tree. + * @param index The index to diff with; repo index used if NULL. + * @param opts Structure with options to influence diff or NULL for defaults. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_diff_tree_to_index( + git_diff **diff, + git_repository *repo, + git_tree *old_tree, + git_index *index, + const git_diff_options *opts); + +/** + * Create a diff between the repository index and the workdir directory. + * + * This matches the `git diff` command. See the note below on + * `git_diff_tree_to_workdir` for a discussion of the difference between + * `git diff` and `git diff HEAD` and how to emulate a `git diff ` + * using libgit2. + * + * The index will be used for the "old_file" side of the delta, and the + * working directory will be used for the "new_file" side of the delta. + * + * If you pass NULL for the index, then the existing index of the `repo` + * will be used. In this case, the index will be refreshed from disk + * (if it has changed) before the diff is generated. + * + * @param diff Output pointer to a git_diff pointer to be allocated. + * @param repo The repository. + * @param index The index to diff from; repo index used if NULL. + * @param opts Structure with options to influence diff or NULL for defaults. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_diff_index_to_workdir( + git_diff **diff, + git_repository *repo, + git_index *index, + const git_diff_options *opts); + +/** + * Create a diff between a tree and the working directory. + * + * The tree you provide will be used for the "old_file" side of the delta, + * and the working directory will be used for the "new_file" side. + * + * This is not the same as `git diff ` or `git diff-index + * `. Those commands use information from the index, whereas this + * function strictly returns the differences between the tree and the files + * in the working directory, regardless of the state of the index. Use + * `git_diff_tree_to_workdir_with_index` to emulate those commands. + * + * To see difference between this and `git_diff_tree_to_workdir_with_index`, + * consider the example of a staged file deletion where the file has then + * been put back into the working dir and further modified. The + * tree-to-workdir diff for that file is 'modified', but `git diff` would + * show status 'deleted' since there is a staged delete. + * + * @param diff A pointer to a git_diff pointer that will be allocated. + * @param repo The repository containing the tree. + * @param old_tree A git_tree object to diff from, or NULL for empty tree. + * @param opts Structure with options to influence diff or NULL for defaults. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_diff_tree_to_workdir( + git_diff **diff, + git_repository *repo, + git_tree *old_tree, + const git_diff_options *opts); + +/** + * Create a diff between a tree and the working directory using index data + * to account for staged deletes, tracked files, etc. + * + * This emulates `git diff ` by diffing the tree to the index and + * the index to the working directory and blending the results into a + * single diff that includes staged deleted, etc. + * + * @param diff A pointer to a git_diff pointer that will be allocated. + * @param repo The repository containing the tree. + * @param old_tree A git_tree object to diff from, or NULL for empty tree. + * @param opts Structure with options to influence diff or NULL for defaults. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_diff_tree_to_workdir_with_index( + git_diff **diff, + git_repository *repo, + git_tree *old_tree, + const git_diff_options *opts); + +/** + * Create a diff with the difference between two index objects. + * + * The first index will be used for the "old_file" side of the delta and the + * second index will be used for the "new_file" side of the delta. + * + * @param diff Output pointer to a git_diff pointer to be allocated. + * @param repo The repository containing the indexes. + * @param old_index A git_index object to diff from. + * @param new_index A git_index object to diff to. + * @param opts Structure with options to influence diff or NULL for defaults. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_diff_index_to_index( + git_diff **diff, + git_repository *repo, + git_index *old_index, + git_index *new_index, + const git_diff_options *opts); + +/** + * Merge one diff into another. + * + * This merges items from the "from" list into the "onto" list. The + * resulting diff will have all items that appear in either list. + * If an item appears in both lists, then it will be "merged" to appear + * as if the old version was from the "onto" list and the new version + * is from the "from" list (with the exception that if the item has a + * pending DELETE in the middle, then it will show as deleted). + * + * @param onto Diff to merge into. + * @param from Diff to merge. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_diff_merge( + git_diff *onto, + const git_diff *from); + +/** + * Transform a diff marking file renames, copies, etc. + * + * This modifies a diff in place, replacing old entries that look + * like renames or copies with new entries reflecting those changes. + * This also will, if requested, break modified files into add/remove + * pairs if the amount of change is above a threshold. + * + * @param diff diff to run detection algorithms on + * @param options Control how detection should be run, NULL for defaults + * @return 0 on success, -1 on failure + */ +GIT_EXTERN(int) git_diff_find_similar( + git_diff *diff, + const git_diff_find_options *options); + +/**@}*/ + + +/** @name Diff Processor Functions + * + * These are the functions you apply to a diff to process it + * or read it in some way. + */ +/**@{*/ + +/** + * Query how many diff records are there in a diff. + * + * @param diff A git_diff generated by one of the above functions + * @return Count of number of deltas in the list + */ +GIT_EXTERN(size_t) git_diff_num_deltas(const git_diff *diff); + +/** + * Query how many diff deltas are there in a diff filtered by type. + * + * This works just like `git_diff_num_deltas()` with an extra parameter + * that is a `git_delta_t` and returns just the count of how many deltas + * match that particular type. + * + * @param diff A git_diff generated by one of the above functions + * @param type A git_delta_t value to filter the count + * @return Count of number of deltas matching delta_t type + */ +GIT_EXTERN(size_t) git_diff_num_deltas_of_type( + const git_diff *diff, git_delta_t type); + +/** + * Return the diff delta for an entry in the diff list. + * + * The `git_diff_delta` pointer points to internal data and you do not + * have to release it when you are done with it. It will go away when + * the * `git_diff` (or any associated `git_patch`) goes away. + * + * Note that the flags on the delta related to whether it has binary + * content or not may not be set if there are no attributes set for the + * file and there has been no reason to load the file data at this point. + * For now, if you need those flags to be up to date, your only option is + * to either use `git_diff_foreach` or create a `git_patch`. + * + * @param diff Diff list object + * @param idx Index into diff list + * @return Pointer to git_diff_delta (or NULL if `idx` out of range) + */ +GIT_EXTERN(const git_diff_delta *) git_diff_get_delta( + const git_diff *diff, size_t idx); + +/** + * Check if deltas are sorted case sensitively or insensitively. + * + * @param diff diff to check + * @return 0 if case sensitive, 1 if case is ignored + */ +GIT_EXTERN(int) git_diff_is_sorted_icase(const git_diff *diff); + +/** + * Loop over all deltas in a diff issuing callbacks. + * + * This will iterate through all of the files described in a diff. You + * should provide a file callback to learn about each file. + * + * The "hunk" and "line" callbacks are optional, and the text diff of the + * files will only be calculated if they are not NULL. Of course, these + * callbacks will not be invoked for binary files on the diff or for + * files whose only changed is a file mode change. + * + * Returning a non-zero value from any of the callbacks will terminate + * the iteration and return the value to the user. + * + * @param diff A git_diff generated by one of the above functions. + * @param file_cb Callback function to make per file in the diff. + * @param binary_cb Optional callback to make for binary files. + * @param hunk_cb Optional callback to make per hunk of text diff. This + * callback is called to describe a range of lines in the + * diff. It will not be issued for binary files. + * @param line_cb Optional callback to make per line of diff text. This + * same callback will be made for context lines, added, and + * removed lines, and even for a deleted trailing newline. + * @param payload Reference pointer that will be passed to your callbacks. + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_diff_foreach( + git_diff *diff, + git_diff_file_cb file_cb, + git_diff_binary_cb binary_cb, + git_diff_hunk_cb hunk_cb, + git_diff_line_cb line_cb, + void *payload); + +/** + * Look up the single character abbreviation for a delta status code. + * + * When you run `git diff --name-status` it uses single letter codes in + * the output such as 'A' for added, 'D' for deleted, 'M' for modified, + * etc. This function converts a git_delta_t value into these letters for + * your own purposes. GIT_DELTA_UNTRACKED will return a space (i.e. ' '). + * + * @param status The git_delta_t value to look up + * @return The single character label for that code + */ +GIT_EXTERN(char) git_diff_status_char(git_delta_t status); + +/** + * Possible output formats for diff data + */ +typedef enum { + GIT_DIFF_FORMAT_PATCH = 1u, /**< full git diff */ + GIT_DIFF_FORMAT_PATCH_HEADER = 2u, /**< just the file headers of patch */ + GIT_DIFF_FORMAT_RAW = 3u, /**< like git diff --raw */ + GIT_DIFF_FORMAT_NAME_ONLY = 4u, /**< like git diff --name-only */ + GIT_DIFF_FORMAT_NAME_STATUS = 5u, /**< like git diff --name-status */ + GIT_DIFF_FORMAT_PATCH_ID = 6u /**< git diff as used by git patch-id */ +} git_diff_format_t; + +/** + * Iterate over a diff generating formatted text output. + * + * Returning a non-zero value from the callbacks will terminate the + * iteration and return the non-zero value to the caller. + * + * @param diff A git_diff generated by one of the above functions. + * @param format A git_diff_format_t value to pick the text format. + * @param print_cb Callback to make per line of diff text. + * @param payload Reference pointer that will be passed to your callback. + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_diff_print( + git_diff *diff, + git_diff_format_t format, + git_diff_line_cb print_cb, + void *payload); + +/** + * Produce the complete formatted text output from a diff into a + * buffer. + * + * @param out A pointer to a user-allocated git_buf that will + * contain the diff text + * @param diff A git_diff generated by one of the above functions. + * @param format A git_diff_format_t value to pick the text format. + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_diff_to_buf( + git_buf *out, + git_diff *diff, + git_diff_format_t format); + +/**@}*/ + +/* + * Low-level file comparison, invoking callbacks per difference. + */ + +/** + * Directly run a diff on two blobs. + * + * Compared to a file, a blob lacks some contextual information. As such, + * the `git_diff_file` given to the callback will have some fake data; i.e. + * `mode` will be 0 and `path` will be NULL. + * + * NULL is allowed for either `old_blob` or `new_blob` and will be treated + * as an empty blob, with the `oid` set to NULL in the `git_diff_file` data. + * Passing NULL for both blobs is a noop; no callbacks will be made at all. + * + * We do run a binary content check on the blob content and if either blob + * looks like binary data, the `git_diff_delta` binary attribute will be set + * to 1 and no call to the hunk_cb nor line_cb will be made (unless you pass + * `GIT_DIFF_FORCE_TEXT` of course). + * + * @param old_blob Blob for old side of diff, or NULL for empty blob + * @param old_as_path Treat old blob as if it had this filename; can be NULL + * @param new_blob Blob for new side of diff, or NULL for empty blob + * @param new_as_path Treat new blob as if it had this filename; can be NULL + * @param options Options for diff, or NULL for default options + * @param file_cb Callback for "file"; made once if there is a diff; can be NULL + * @param binary_cb Callback for binary files; can be NULL + * @param hunk_cb Callback for each hunk in diff; can be NULL + * @param line_cb Callback for each line in diff; can be NULL + * @param payload Payload passed to each callback function + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_diff_blobs( + const git_blob *old_blob, + const char *old_as_path, + const git_blob *new_blob, + const char *new_as_path, + const git_diff_options *options, + git_diff_file_cb file_cb, + git_diff_binary_cb binary_cb, + git_diff_hunk_cb hunk_cb, + git_diff_line_cb line_cb, + void *payload); + +/** + * Directly run a diff between a blob and a buffer. + * + * As with `git_diff_blobs`, comparing a blob and buffer lacks some context, + * so the `git_diff_file` parameters to the callbacks will be faked a la the + * rules for `git_diff_blobs()`. + * + * Passing NULL for `old_blob` will be treated as an empty blob (i.e. the + * `file_cb` will be invoked with GIT_DELTA_ADDED and the diff will be the + * entire content of the buffer added). Passing NULL to the buffer will do + * the reverse, with GIT_DELTA_REMOVED and blob content removed. + * + * @param old_blob Blob for old side of diff, or NULL for empty blob + * @param old_as_path Treat old blob as if it had this filename; can be NULL + * @param buffer Raw data for new side of diff, or NULL for empty + * @param buffer_len Length of raw data for new side of diff + * @param buffer_as_path Treat buffer as if it had this filename; can be NULL + * @param options Options for diff, or NULL for default options + * @param file_cb Callback for "file"; made once if there is a diff; can be NULL + * @param binary_cb Callback for binary files; can be NULL + * @param hunk_cb Callback for each hunk in diff; can be NULL + * @param line_cb Callback for each line in diff; can be NULL + * @param payload Payload passed to each callback function + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_diff_blob_to_buffer( + const git_blob *old_blob, + const char *old_as_path, + const char *buffer, + size_t buffer_len, + const char *buffer_as_path, + const git_diff_options *options, + git_diff_file_cb file_cb, + git_diff_binary_cb binary_cb, + git_diff_hunk_cb hunk_cb, + git_diff_line_cb line_cb, + void *payload); + +/** + * Directly run a diff between two buffers. + * + * Even more than with `git_diff_blobs`, comparing two buffer lacks + * context, so the `git_diff_file` parameters to the callbacks will be + * faked a la the rules for `git_diff_blobs()`. + * + * @param old_buffer Raw data for old side of diff, or NULL for empty + * @param old_len Length of the raw data for old side of the diff + * @param old_as_path Treat old buffer as if it had this filename; can be NULL + * @param new_buffer Raw data for new side of diff, or NULL for empty + * @param new_len Length of raw data for new side of diff + * @param new_as_path Treat buffer as if it had this filename; can be NULL + * @param options Options for diff, or NULL for default options + * @param file_cb Callback for "file"; made once if there is a diff; can be NULL + * @param binary_cb Callback for binary files; can be NULL + * @param hunk_cb Callback for each hunk in diff; can be NULL + * @param line_cb Callback for each line in diff; can be NULL + * @param payload Payload passed to each callback function + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_diff_buffers( + const void *old_buffer, + size_t old_len, + const char *old_as_path, + const void *new_buffer, + size_t new_len, + const char *new_as_path, + const git_diff_options *options, + git_diff_file_cb file_cb, + git_diff_binary_cb binary_cb, + git_diff_hunk_cb hunk_cb, + git_diff_line_cb line_cb, + void *payload); + +/* Patch file parsing. */ + +/** + * Options for parsing a diff / patch file. + */ +typedef struct { + unsigned int version; + git_oid_t oid_type; +} git_diff_parse_options; + +/* The current version of the diff parse options structure */ +#define GIT_DIFF_PARSE_OPTIONS_VERSION 1 + +/* Stack initializer for diff parse options. Alternatively use + * `git_diff_parse_options_init` programmatic initialization. + */ +#define GIT_DIFF_PARSE_OPTIONS_INIT \ + { GIT_DIFF_PARSE_OPTIONS_VERSION, GIT_OID_DEFAULT } + +/** + * Read the contents of a git patch file into a `git_diff` object. + * + * The diff object produced is similar to the one that would be + * produced if you actually produced it computationally by comparing + * two trees, however there may be subtle differences. For example, + * a patch file likely contains abbreviated object IDs, so the + * object IDs in a `git_diff_delta` produced by this function will + * also be abbreviated. + * + * This function will only read patch files created by a git + * implementation, it will not read unified diffs produced by + * the `diff` program, nor any other types of patch files. + * + * @param out A pointer to a git_diff pointer that will be allocated. + * @param content The contents of a patch file + * @param content_len The length of the patch file contents + * @return 0 or an error code + */ +GIT_EXTERN(int) git_diff_from_buffer( + git_diff **out, + const char *content, + size_t content_len +#ifdef GIT_EXPERIMENTAL_SHA256 + , git_diff_parse_options *opts +#endif + ); + +/** + * This is an opaque structure which is allocated by `git_diff_get_stats`. + * You are responsible for releasing the object memory when done, using the + * `git_diff_stats_free()` function. + */ +typedef struct git_diff_stats git_diff_stats; + +/** + * Formatting options for diff stats + */ +typedef enum { + /** No stats*/ + GIT_DIFF_STATS_NONE = 0, + + /** Full statistics, equivalent of `--stat` */ + GIT_DIFF_STATS_FULL = (1u << 0), + + /** Short statistics, equivalent of `--shortstat` */ + GIT_DIFF_STATS_SHORT = (1u << 1), + + /** Number statistics, equivalent of `--numstat` */ + GIT_DIFF_STATS_NUMBER = (1u << 2), + + /** Extended header information such as creations, renames and mode changes, equivalent of `--summary` */ + GIT_DIFF_STATS_INCLUDE_SUMMARY = (1u << 3) +} git_diff_stats_format_t; + +/** + * Accumulate diff statistics for all patches. + * + * @param out Structure containing the diff statistics. + * @param diff A git_diff generated by one of the above functions. + * @return 0 on success; non-zero on error + */ +GIT_EXTERN(int) git_diff_get_stats( + git_diff_stats **out, + git_diff *diff); + +/** + * Get the total number of files changed in a diff + * + * @param stats A `git_diff_stats` generated by one of the above functions. + * @return total number of files changed in the diff + */ +GIT_EXTERN(size_t) git_diff_stats_files_changed( + const git_diff_stats *stats); + +/** + * Get the total number of insertions in a diff + * + * @param stats A `git_diff_stats` generated by one of the above functions. + * @return total number of insertions in the diff + */ +GIT_EXTERN(size_t) git_diff_stats_insertions( + const git_diff_stats *stats); + +/** + * Get the total number of deletions in a diff + * + * @param stats A `git_diff_stats` generated by one of the above functions. + * @return total number of deletions in the diff + */ +GIT_EXTERN(size_t) git_diff_stats_deletions( + const git_diff_stats *stats); + +/** + * Print diff statistics to a `git_buf`. + * + * @param out buffer to store the formatted diff statistics in. + * @param stats A `git_diff_stats` generated by one of the above functions. + * @param format Formatting option. + * @param width Target width for output (only affects GIT_DIFF_STATS_FULL) + * @return 0 on success; non-zero on error + */ +GIT_EXTERN(int) git_diff_stats_to_buf( + git_buf *out, + const git_diff_stats *stats, + git_diff_stats_format_t format, + size_t width); + +/** + * Deallocate a `git_diff_stats`. + * + * @param stats The previously created statistics object; + * cannot be used after free. + */ +GIT_EXTERN(void) git_diff_stats_free(git_diff_stats *stats); + +/** + * Patch ID options structure + * + * Initialize with `GIT_PATCHID_OPTIONS_INIT`. Alternatively, you can + * use `git_diff_patchid_options_init`. + * + */ +typedef struct git_diff_patchid_options { + unsigned int version; +} git_diff_patchid_options; + +#define GIT_DIFF_PATCHID_OPTIONS_VERSION 1 +#define GIT_DIFF_PATCHID_OPTIONS_INIT { GIT_DIFF_PATCHID_OPTIONS_VERSION } + +/** + * Initialize git_diff_patchid_options structure + * + * Initializes a `git_diff_patchid_options` with default values. Equivalent to + * creating an instance with `GIT_DIFF_PATCHID_OPTIONS_INIT`. + * + * @param opts The `git_diff_patchid_options` struct to initialize. + * @param version The struct version; pass `GIT_DIFF_PATCHID_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_diff_patchid_options_init( + git_diff_patchid_options *opts, + unsigned int version); + +/** + * Calculate the patch ID for the given patch. + * + * Calculate a stable patch ID for the given patch by summing the + * hash of the file diffs, ignoring whitespace and line numbers. + * This can be used to derive whether two diffs are the same with + * a high probability. + * + * Currently, this function only calculates stable patch IDs, as + * defined in git-patch-id(1), and should in fact generate the + * same IDs as the upstream git project does. + * + * @param out Pointer where the calculated patch ID should be stored + * @param diff The diff to calculate the ID for + * @param opts Options for how to calculate the patch ID. This is + * intended for future changes, as currently no options are + * available. + * @return 0 on success, an error code otherwise. + */ +GIT_EXTERN(int) git_diff_patchid(git_oid *out, git_diff *diff, git_diff_patchid_options *opts); + +GIT_END_DECL + +/** @} */ + +#endif diff --git a/3rdparty/libgit2/include/git2/email.h b/3rdparty/libgit2/include/git2/email.h index 2039365..0962818 100644 --- a/3rdparty/libgit2/include/git2/email.h +++ b/3rdparty/libgit2/include/git2/email.h @@ -1,127 +1,127 @@ -/* - * 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_email_h__ -#define INCLUDE_git_email_h__ - -#include "common.h" - -/** - * @file git2/email.h - * @brief Git email formatting and application routines. - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Formatting options for diff e-mail generation - */ -typedef enum { - /** Normal patch, the default */ - GIT_EMAIL_CREATE_DEFAULT = 0, - - /** Do not include patch numbers in the subject prefix. */ - GIT_EMAIL_CREATE_OMIT_NUMBERS = (1u << 0), - - /** - * Include numbers in the subject prefix even when the - * patch is for a single commit (1/1). - */ - GIT_EMAIL_CREATE_ALWAYS_NUMBER = (1u << 1), - - /** Do not perform rename or similarity detection. */ - GIT_EMAIL_CREATE_NO_RENAMES = (1u << 2) -} git_email_create_flags_t; - -/** - * Options for controlling the formatting of the generated e-mail. - */ -typedef struct { - unsigned int version; - - /** see `git_email_create_flags_t` above */ - uint32_t flags; - - /** Options to use when creating diffs */ - git_diff_options diff_opts; - - /** Options for finding similarities within diffs */ - git_diff_find_options diff_find_opts; - - /** - * The subject prefix, by default "PATCH". If set to an empty - * string ("") then only the patch numbers will be shown in the - * prefix. If the subject_prefix is empty and patch numbers - * are not being shown, the prefix will be omitted entirely. - */ - const char *subject_prefix; - - /** - * The starting patch number; this cannot be 0. By default, - * this is 1. - */ - size_t start_number; - - /** The "re-roll" number. By default, there is no re-roll. */ - size_t reroll_number; -} git_email_create_options; - -/* - * By default, our options include rename detection and binary - * diffs to match `git format-patch`. - */ -#define GIT_EMAIL_CREATE_OPTIONS_VERSION 1 -#define GIT_EMAIL_CREATE_OPTIONS_INIT \ -{ \ - GIT_EMAIL_CREATE_OPTIONS_VERSION, \ - GIT_EMAIL_CREATE_DEFAULT, \ - { GIT_DIFF_OPTIONS_VERSION, GIT_DIFF_SHOW_BINARY, GIT_SUBMODULE_IGNORE_UNSPECIFIED, {NULL,0}, NULL, NULL, NULL, 3 }, \ - GIT_DIFF_FIND_OPTIONS_INIT \ -} - -/** - * Create a diff for a commit in mbox format for sending via email. - * - * @param out buffer to store the e-mail patch in - * @param diff the changes to include in the email - * @param patch_idx the patch index - * @param patch_count the total number of patches that will be included - * @param commit_id the commit id for this change - * @param summary the commit message for this change - * @param body optional text to include above the diffstat - * @param author the person who authored this commit - * @param opts email creation options - */ -GIT_EXTERN(int) git_email_create_from_diff( - git_buf *out, - git_diff *diff, - size_t patch_idx, - size_t patch_count, - const git_oid *commit_id, - const char *summary, - const char *body, - const git_signature *author, - const git_email_create_options *opts); - -/** - * Create a diff for a commit in mbox format for sending via email. - * The commit must not be a merge commit. - * - * @param out buffer to store the e-mail patch in - * @param commit commit to create a patch for - * @param opts email creation options - */ -GIT_EXTERN(int) git_email_create_from_commit( - git_buf *out, - git_commit *commit, - const git_email_create_options *opts); - -GIT_END_DECL - -/** @} */ - -#endif +/* + * 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_email_h__ +#define INCLUDE_git_email_h__ + +#include "common.h" + +/** + * @file git2/email.h + * @brief Git email formatting and application routines. + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Formatting options for diff e-mail generation + */ +typedef enum { + /** Normal patch, the default */ + GIT_EMAIL_CREATE_DEFAULT = 0, + + /** Do not include patch numbers in the subject prefix. */ + GIT_EMAIL_CREATE_OMIT_NUMBERS = (1u << 0), + + /** + * Include numbers in the subject prefix even when the + * patch is for a single commit (1/1). + */ + GIT_EMAIL_CREATE_ALWAYS_NUMBER = (1u << 1), + + /** Do not perform rename or similarity detection. */ + GIT_EMAIL_CREATE_NO_RENAMES = (1u << 2) +} git_email_create_flags_t; + +/** + * Options for controlling the formatting of the generated e-mail. + */ +typedef struct { + unsigned int version; + + /** see `git_email_create_flags_t` above */ + uint32_t flags; + + /** Options to use when creating diffs */ + git_diff_options diff_opts; + + /** Options for finding similarities within diffs */ + git_diff_find_options diff_find_opts; + + /** + * The subject prefix, by default "PATCH". If set to an empty + * string ("") then only the patch numbers will be shown in the + * prefix. If the subject_prefix is empty and patch numbers + * are not being shown, the prefix will be omitted entirely. + */ + const char *subject_prefix; + + /** + * The starting patch number; this cannot be 0. By default, + * this is 1. + */ + size_t start_number; + + /** The "re-roll" number. By default, there is no re-roll. */ + size_t reroll_number; +} git_email_create_options; + +/* + * By default, our options include rename detection and binary + * diffs to match `git format-patch`. + */ +#define GIT_EMAIL_CREATE_OPTIONS_VERSION 1 +#define GIT_EMAIL_CREATE_OPTIONS_INIT \ +{ \ + GIT_EMAIL_CREATE_OPTIONS_VERSION, \ + GIT_EMAIL_CREATE_DEFAULT, \ + { GIT_DIFF_OPTIONS_VERSION, GIT_DIFF_SHOW_BINARY, GIT_SUBMODULE_IGNORE_UNSPECIFIED, {NULL,0}, NULL, NULL, NULL, 3 }, \ + GIT_DIFF_FIND_OPTIONS_INIT \ +} + +/** + * Create a diff for a commit in mbox format for sending via email. + * + * @param out buffer to store the e-mail patch in + * @param diff the changes to include in the email + * @param patch_idx the patch index + * @param patch_count the total number of patches that will be included + * @param commit_id the commit id for this change + * @param summary the commit message for this change + * @param body optional text to include above the diffstat + * @param author the person who authored this commit + * @param opts email creation options + */ +GIT_EXTERN(int) git_email_create_from_diff( + git_buf *out, + git_diff *diff, + size_t patch_idx, + size_t patch_count, + const git_oid *commit_id, + const char *summary, + const char *body, + const git_signature *author, + const git_email_create_options *opts); + +/** + * Create a diff for a commit in mbox format for sending via email. + * The commit must not be a merge commit. + * + * @param out buffer to store the e-mail patch in + * @param commit commit to create a patch for + * @param opts email creation options + */ +GIT_EXTERN(int) git_email_create_from_commit( + git_buf *out, + git_commit *commit, + const git_email_create_options *opts); + +GIT_END_DECL + +/** @} */ + +#endif diff --git a/3rdparty/libgit2/include/git2/errors.h b/3rdparty/libgit2/include/git2/errors.h index 52fa5f0..54a64a5 100644 --- a/3rdparty/libgit2/include/git2/errors.h +++ b/3rdparty/libgit2/include/git2/errors.h @@ -1,143 +1,143 @@ -/* - * 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_errors_h__ -#define INCLUDE_git_errors_h__ - -#include "common.h" - -/** - * @file git2/errors.h - * @brief Git error handling routines and variables - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** Generic return codes */ -typedef enum { - GIT_OK = 0, /**< No error */ - - GIT_ERROR = -1, /**< Generic error */ - GIT_ENOTFOUND = -3, /**< Requested object could not be found */ - GIT_EEXISTS = -4, /**< Object exists preventing operation */ - GIT_EAMBIGUOUS = -5, /**< More than one object matches */ - GIT_EBUFS = -6, /**< Output buffer too short to hold data */ - - /** - * GIT_EUSER is a special error that is never generated by libgit2 - * code. You can return it from a callback (e.g to stop an iteration) - * to know that it was generated by the callback and not by libgit2. - */ - GIT_EUSER = -7, - - GIT_EBAREREPO = -8, /**< Operation not allowed on bare repository */ - GIT_EUNBORNBRANCH = -9, /**< HEAD refers to branch with no commits */ - GIT_EUNMERGED = -10, /**< Merge in progress prevented operation */ - GIT_ENONFASTFORWARD = -11, /**< Reference was not fast-forwardable */ - GIT_EINVALIDSPEC = -12, /**< Name/ref spec was not in a valid format */ - GIT_ECONFLICT = -13, /**< Checkout conflicts prevented operation */ - GIT_ELOCKED = -14, /**< Lock file prevented operation */ - GIT_EMODIFIED = -15, /**< Reference value does not match expected */ - GIT_EAUTH = -16, /**< Authentication error */ - GIT_ECERTIFICATE = -17, /**< Server certificate is invalid */ - GIT_EAPPLIED = -18, /**< Patch/merge has already been applied */ - GIT_EPEEL = -19, /**< The requested peel operation is not possible */ - GIT_EEOF = -20, /**< Unexpected EOF */ - GIT_EINVALID = -21, /**< Invalid operation or input */ - GIT_EUNCOMMITTED = -22, /**< Uncommitted changes in index prevented operation */ - GIT_EDIRECTORY = -23, /**< The operation is not valid for a directory */ - GIT_EMERGECONFLICT = -24, /**< A merge conflict exists and cannot continue */ - - GIT_PASSTHROUGH = -30, /**< A user-configured callback refused to act */ - GIT_ITEROVER = -31, /**< Signals end of iteration with iterator */ - GIT_RETRY = -32, /**< Internal only */ - GIT_EMISMATCH = -33, /**< Hashsum mismatch in object */ - GIT_EINDEXDIRTY = -34, /**< Unsaved changes in the index would be overwritten */ - GIT_EAPPLYFAIL = -35, /**< Patch application failed */ - GIT_EOWNER = -36, /**< The object is not owned by the current user */ - GIT_TIMEOUT = -37, /**< The operation timed out */ - GIT_EUNCHANGED = -38, /**< There were no changes */ - GIT_ENOTSUPPORTED = -39, /**< An option is not supported */ - GIT_EREADONLY = -40 /**< The subject is read-only */ -} git_error_code; - -/** - * Structure to store extra details of the last error that occurred. - * - * This is kept on a per-thread basis if GIT_THREADS was defined when the - * library was build, otherwise one is kept globally for the library - */ -typedef struct { - char *message; - int klass; -} git_error; - -/** Error classes */ -typedef enum { - GIT_ERROR_NONE = 0, - GIT_ERROR_NOMEMORY, - GIT_ERROR_OS, - GIT_ERROR_INVALID, - GIT_ERROR_REFERENCE, - GIT_ERROR_ZLIB, - GIT_ERROR_REPOSITORY, - GIT_ERROR_CONFIG, - GIT_ERROR_REGEX, - GIT_ERROR_ODB, - GIT_ERROR_INDEX, - GIT_ERROR_OBJECT, - GIT_ERROR_NET, - GIT_ERROR_TAG, - GIT_ERROR_TREE, - GIT_ERROR_INDEXER, - GIT_ERROR_SSL, - GIT_ERROR_SUBMODULE, - GIT_ERROR_THREAD, - GIT_ERROR_STASH, - GIT_ERROR_CHECKOUT, - GIT_ERROR_FETCHHEAD, - GIT_ERROR_MERGE, - GIT_ERROR_SSH, - GIT_ERROR_FILTER, - GIT_ERROR_REVERT, - GIT_ERROR_CALLBACK, - GIT_ERROR_CHERRYPICK, - GIT_ERROR_DESCRIBE, - GIT_ERROR_REBASE, - GIT_ERROR_FILESYSTEM, - GIT_ERROR_PATCH, - GIT_ERROR_WORKTREE, - GIT_ERROR_SHA, - GIT_ERROR_HTTP, - GIT_ERROR_INTERNAL, - GIT_ERROR_GRAFTS -} git_error_t; - -/** - * Return the last `git_error` object that was generated for the - * current thread. - * - * This function will never return NULL. - * - * Callers should not rely on this to determine whether an error has - * occurred. For error checking, callers should examine the return - * codes of libgit2 functions. - * - * This call can only reliably report error messages when an error - * has occurred. (It may contain stale information if it is called - * after a different function that succeeds.) - * - * The memory for this object is managed by libgit2. It should not - * be freed. - * - * @return A git_error object. - */ -GIT_EXTERN(const git_error *) git_error_last(void); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_errors_h__ +#define INCLUDE_git_errors_h__ + +#include "common.h" + +/** + * @file git2/errors.h + * @brief Git error handling routines and variables + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** Generic return codes */ +typedef enum { + GIT_OK = 0, /**< No error */ + + GIT_ERROR = -1, /**< Generic error */ + GIT_ENOTFOUND = -3, /**< Requested object could not be found */ + GIT_EEXISTS = -4, /**< Object exists preventing operation */ + GIT_EAMBIGUOUS = -5, /**< More than one object matches */ + GIT_EBUFS = -6, /**< Output buffer too short to hold data */ + + /** + * GIT_EUSER is a special error that is never generated by libgit2 + * code. You can return it from a callback (e.g to stop an iteration) + * to know that it was generated by the callback and not by libgit2. + */ + GIT_EUSER = -7, + + GIT_EBAREREPO = -8, /**< Operation not allowed on bare repository */ + GIT_EUNBORNBRANCH = -9, /**< HEAD refers to branch with no commits */ + GIT_EUNMERGED = -10, /**< Merge in progress prevented operation */ + GIT_ENONFASTFORWARD = -11, /**< Reference was not fast-forwardable */ + GIT_EINVALIDSPEC = -12, /**< Name/ref spec was not in a valid format */ + GIT_ECONFLICT = -13, /**< Checkout conflicts prevented operation */ + GIT_ELOCKED = -14, /**< Lock file prevented operation */ + GIT_EMODIFIED = -15, /**< Reference value does not match expected */ + GIT_EAUTH = -16, /**< Authentication error */ + GIT_ECERTIFICATE = -17, /**< Server certificate is invalid */ + GIT_EAPPLIED = -18, /**< Patch/merge has already been applied */ + GIT_EPEEL = -19, /**< The requested peel operation is not possible */ + GIT_EEOF = -20, /**< Unexpected EOF */ + GIT_EINVALID = -21, /**< Invalid operation or input */ + GIT_EUNCOMMITTED = -22, /**< Uncommitted changes in index prevented operation */ + GIT_EDIRECTORY = -23, /**< The operation is not valid for a directory */ + GIT_EMERGECONFLICT = -24, /**< A merge conflict exists and cannot continue */ + + GIT_PASSTHROUGH = -30, /**< A user-configured callback refused to act */ + GIT_ITEROVER = -31, /**< Signals end of iteration with iterator */ + GIT_RETRY = -32, /**< Internal only */ + GIT_EMISMATCH = -33, /**< Hashsum mismatch in object */ + GIT_EINDEXDIRTY = -34, /**< Unsaved changes in the index would be overwritten */ + GIT_EAPPLYFAIL = -35, /**< Patch application failed */ + GIT_EOWNER = -36, /**< The object is not owned by the current user */ + GIT_TIMEOUT = -37, /**< The operation timed out */ + GIT_EUNCHANGED = -38, /**< There were no changes */ + GIT_ENOTSUPPORTED = -39, /**< An option is not supported */ + GIT_EREADONLY = -40 /**< The subject is read-only */ +} git_error_code; + +/** + * Structure to store extra details of the last error that occurred. + * + * This is kept on a per-thread basis if GIT_THREADS was defined when the + * library was build, otherwise one is kept globally for the library + */ +typedef struct { + char *message; + int klass; +} git_error; + +/** Error classes */ +typedef enum { + GIT_ERROR_NONE = 0, + GIT_ERROR_NOMEMORY, + GIT_ERROR_OS, + GIT_ERROR_INVALID, + GIT_ERROR_REFERENCE, + GIT_ERROR_ZLIB, + GIT_ERROR_REPOSITORY, + GIT_ERROR_CONFIG, + GIT_ERROR_REGEX, + GIT_ERROR_ODB, + GIT_ERROR_INDEX, + GIT_ERROR_OBJECT, + GIT_ERROR_NET, + GIT_ERROR_TAG, + GIT_ERROR_TREE, + GIT_ERROR_INDEXER, + GIT_ERROR_SSL, + GIT_ERROR_SUBMODULE, + GIT_ERROR_THREAD, + GIT_ERROR_STASH, + GIT_ERROR_CHECKOUT, + GIT_ERROR_FETCHHEAD, + GIT_ERROR_MERGE, + GIT_ERROR_SSH, + GIT_ERROR_FILTER, + GIT_ERROR_REVERT, + GIT_ERROR_CALLBACK, + GIT_ERROR_CHERRYPICK, + GIT_ERROR_DESCRIBE, + GIT_ERROR_REBASE, + GIT_ERROR_FILESYSTEM, + GIT_ERROR_PATCH, + GIT_ERROR_WORKTREE, + GIT_ERROR_SHA, + GIT_ERROR_HTTP, + GIT_ERROR_INTERNAL, + GIT_ERROR_GRAFTS +} git_error_t; + +/** + * Return the last `git_error` object that was generated for the + * current thread. + * + * This function will never return NULL. + * + * Callers should not rely on this to determine whether an error has + * occurred. For error checking, callers should examine the return + * codes of libgit2 functions. + * + * This call can only reliably report error messages when an error + * has occurred. (It may contain stale information if it is called + * after a different function that succeeds.) + * + * The memory for this object is managed by libgit2. It should not + * be freed. + * + * @return A git_error object. + */ +GIT_EXTERN(const git_error *) git_error_last(void); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/experimental.h b/3rdparty/libgit2/include/git2/experimental.h index 543f62f..5263670 100644 --- a/3rdparty/libgit2/include/git2/experimental.h +++ b/3rdparty/libgit2/include/git2/experimental.h @@ -1,13 +1,13 @@ -/* - * 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_experimental_h__ -#define INCLUDE_experimental_h__ - -/* #undef GIT_EXPERIMENTAL_SHA256 */ - -#endif +/* + * 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_experimental_h__ +#define INCLUDE_experimental_h__ + +/* #undef GIT_EXPERIMENTAL_SHA256 */ + +#endif diff --git a/3rdparty/libgit2/include/git2/filter.h b/3rdparty/libgit2/include/git2/filter.h index 79bf14c..901c611 100644 --- a/3rdparty/libgit2/include/git2/filter.h +++ b/3rdparty/libgit2/include/git2/filter.h @@ -1,276 +1,276 @@ -/* - * 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_filter_h__ -#define INCLUDE_git_filter_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "buffer.h" - -/** - * @file git2/filter.h - * @brief Git filter APIs - * - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Filters are applied in one of two directions: smudging - which is - * exporting a file from the Git object database to the working directory, - * and cleaning - which is importing a file from the working directory to - * the Git object database. These values control which direction of - * change is being applied. - */ -typedef enum { - GIT_FILTER_TO_WORKTREE = 0, - GIT_FILTER_SMUDGE = GIT_FILTER_TO_WORKTREE, - GIT_FILTER_TO_ODB = 1, - GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB -} git_filter_mode_t; - -/** - * Filter option flags. - */ -typedef enum { - GIT_FILTER_DEFAULT = 0u, - - /** Don't error for `safecrlf` violations, allow them to continue. */ - GIT_FILTER_ALLOW_UNSAFE = (1u << 0), - - /** Don't load `/etc/gitattributes` (or the system equivalent) */ - GIT_FILTER_NO_SYSTEM_ATTRIBUTES = (1u << 1), - - /** Load attributes from `.gitattributes` in the root of HEAD */ - GIT_FILTER_ATTRIBUTES_FROM_HEAD = (1u << 2), - - /** - * Load attributes from `.gitattributes` in a given commit. - * This can only be specified in a `git_filter_options`. - */ - GIT_FILTER_ATTRIBUTES_FROM_COMMIT = (1u << 3) -} git_filter_flag_t; - -/** - * Filtering options - */ -typedef struct { - unsigned int version; - - /** See `git_filter_flag_t` above */ - uint32_t flags; - -#ifdef GIT_DEPRECATE_HARD - void *reserved; -#else - git_oid *commit_id; -#endif - - /** - * The commit to load attributes from, when - * `GIT_FILTER_ATTRIBUTES_FROM_COMMIT` is specified. - */ - git_oid attr_commit_id; -} git_filter_options; - - #define GIT_FILTER_OPTIONS_VERSION 1 - #define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION} - -/** - * A filter that can transform file data - * - * This represents a filter that can be used to transform or even replace - * file data. Libgit2 includes one built in filter and it is possible to - * write your own (see git2/sys/filter.h for information on that). - * - * The two builtin filters are: - * - * * "crlf" which uses the complex rules with the "text", "eol", and - * "crlf" file attributes to decide how to convert between LF and CRLF - * line endings - * * "ident" which replaces "$Id$" in a blob with "$Id: $" upon - * checkout and replaced "$Id: $" with "$Id$" on checkin. - */ -typedef struct git_filter git_filter; - -/** - * List of filters to be applied - * - * This represents a list of filters to be applied to a file / blob. You - * can build the list with one call, apply it with another, and dispose it - * with a third. In typical usage, there are not many occasions where a - * git_filter_list is needed directly since the library will generally - * handle conversions for you, but it can be convenient to be able to - * build and apply the list sometimes. - */ -typedef struct git_filter_list git_filter_list; - -/** - * Load the filter list for a given path. - * - * This will return 0 (success) but set the output git_filter_list to NULL - * if no filters are requested for the given file. - * - * @param filters Output newly created git_filter_list (or NULL) - * @param repo Repository object that contains `path` - * @param blob The blob to which the filter will be applied (if known) - * @param path Relative path of the file to be filtered - * @param mode Filtering direction (WT->ODB or ODB->WT) - * @param flags Combination of `git_filter_flag_t` flags - * @return 0 on success (which could still return NULL if no filters are - * needed for the requested file), <0 on error - */ -GIT_EXTERN(int) git_filter_list_load( - git_filter_list **filters, - git_repository *repo, - git_blob *blob, /* can be NULL */ - const char *path, - git_filter_mode_t mode, - uint32_t flags); - -/** - * Load the filter list for a given path. - * - * This will return 0 (success) but set the output git_filter_list to NULL - * if no filters are requested for the given file. - * - * @param filters Output newly created git_filter_list (or NULL) - * @param repo Repository object that contains `path` - * @param blob The blob to which the filter will be applied (if known) - * @param path Relative path of the file to be filtered - * @param mode Filtering direction (WT->ODB or ODB->WT) - * @param opts The `git_filter_options` to use when loading filters - * @return 0 on success (which could still return NULL if no filters are - * needed for the requested file), <0 on error - */ -GIT_EXTERN(int) git_filter_list_load_ext( - git_filter_list **filters, - git_repository *repo, - git_blob *blob, - const char *path, - git_filter_mode_t mode, - git_filter_options *opts); - -/** - * Query the filter list to see if a given filter (by name) will run. - * The built-in filters "crlf" and "ident" can be queried, otherwise this - * is the name of the filter specified by the filter attribute. - * - * This will return 0 if the given filter is not in the list, or 1 if - * the filter will be applied. - * - * @param filters A loaded git_filter_list (or NULL) - * @param name The name of the filter to query - * @return 1 if the filter is in the list, 0 otherwise - */ -GIT_EXTERN(int) git_filter_list_contains( - git_filter_list *filters, - const char *name); - -/** - * Apply filter list to a data buffer. - * - * @param out Buffer to store the result of the filtering - * @param filters A loaded git_filter_list (or NULL) - * @param in Buffer containing the data to filter - * @param in_len The length of the input buffer - * @return 0 on success, an error code otherwise - */ -GIT_EXTERN(int) git_filter_list_apply_to_buffer( - git_buf *out, - git_filter_list *filters, - const char *in, - size_t in_len); - -/** - * Apply a filter list to the contents of a file on disk - * - * @param out buffer into which to store the filtered file - * @param filters the list of filters to apply - * @param repo the repository in which to perform the filtering - * @param path the path of the file to filter, a relative path will be - * taken as relative to the workdir - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_filter_list_apply_to_file( - git_buf *out, - git_filter_list *filters, - git_repository *repo, - const char *path); - -/** - * Apply a filter list to the contents of a blob - * - * @param out buffer into which to store the filtered file - * @param filters the list of filters to apply - * @param blob the blob to filter - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_filter_list_apply_to_blob( - git_buf *out, - git_filter_list *filters, - git_blob *blob); - -/** - * Apply a filter list to an arbitrary buffer as a stream - * - * @param filters the list of filters to apply - * @param buffer the buffer to filter - * @param len the size of the buffer - * @param target the stream into which the data will be written - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_filter_list_stream_buffer( - git_filter_list *filters, - const char *buffer, - size_t len, - git_writestream *target); - -/** - * Apply a filter list to a file as a stream - * - * @param filters the list of filters to apply - * @param repo the repository in which to perform the filtering - * @param path the path of the file to filter, a relative path will be - * taken as relative to the workdir - * @param target the stream into which the data will be written - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_filter_list_stream_file( - git_filter_list *filters, - git_repository *repo, - const char *path, - git_writestream *target); - -/** - * Apply a filter list to a blob as a stream - * - * @param filters the list of filters to apply - * @param blob the blob to filter - * @param target the stream into which the data will be written - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_filter_list_stream_blob( - git_filter_list *filters, - git_blob *blob, - git_writestream *target); - -/** - * Free a git_filter_list - * - * @param filters A git_filter_list created by `git_filter_list_load` - */ -GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters); - - -GIT_END_DECL - -/** @} */ - -#endif +/* + * 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_filter_h__ +#define INCLUDE_git_filter_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "buffer.h" + +/** + * @file git2/filter.h + * @brief Git filter APIs + * + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Filters are applied in one of two directions: smudging - which is + * exporting a file from the Git object database to the working directory, + * and cleaning - which is importing a file from the working directory to + * the Git object database. These values control which direction of + * change is being applied. + */ +typedef enum { + GIT_FILTER_TO_WORKTREE = 0, + GIT_FILTER_SMUDGE = GIT_FILTER_TO_WORKTREE, + GIT_FILTER_TO_ODB = 1, + GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB +} git_filter_mode_t; + +/** + * Filter option flags. + */ +typedef enum { + GIT_FILTER_DEFAULT = 0u, + + /** Don't error for `safecrlf` violations, allow them to continue. */ + GIT_FILTER_ALLOW_UNSAFE = (1u << 0), + + /** Don't load `/etc/gitattributes` (or the system equivalent) */ + GIT_FILTER_NO_SYSTEM_ATTRIBUTES = (1u << 1), + + /** Load attributes from `.gitattributes` in the root of HEAD */ + GIT_FILTER_ATTRIBUTES_FROM_HEAD = (1u << 2), + + /** + * Load attributes from `.gitattributes` in a given commit. + * This can only be specified in a `git_filter_options`. + */ + GIT_FILTER_ATTRIBUTES_FROM_COMMIT = (1u << 3) +} git_filter_flag_t; + +/** + * Filtering options + */ +typedef struct { + unsigned int version; + + /** See `git_filter_flag_t` above */ + uint32_t flags; + +#ifdef GIT_DEPRECATE_HARD + void *reserved; +#else + git_oid *commit_id; +#endif + + /** + * The commit to load attributes from, when + * `GIT_FILTER_ATTRIBUTES_FROM_COMMIT` is specified. + */ + git_oid attr_commit_id; +} git_filter_options; + + #define GIT_FILTER_OPTIONS_VERSION 1 + #define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION} + +/** + * A filter that can transform file data + * + * This represents a filter that can be used to transform or even replace + * file data. Libgit2 includes one built in filter and it is possible to + * write your own (see git2/sys/filter.h for information on that). + * + * The two builtin filters are: + * + * * "crlf" which uses the complex rules with the "text", "eol", and + * "crlf" file attributes to decide how to convert between LF and CRLF + * line endings + * * "ident" which replaces "$Id$" in a blob with "$Id: $" upon + * checkout and replaced "$Id: $" with "$Id$" on checkin. + */ +typedef struct git_filter git_filter; + +/** + * List of filters to be applied + * + * This represents a list of filters to be applied to a file / blob. You + * can build the list with one call, apply it with another, and dispose it + * with a third. In typical usage, there are not many occasions where a + * git_filter_list is needed directly since the library will generally + * handle conversions for you, but it can be convenient to be able to + * build and apply the list sometimes. + */ +typedef struct git_filter_list git_filter_list; + +/** + * Load the filter list for a given path. + * + * This will return 0 (success) but set the output git_filter_list to NULL + * if no filters are requested for the given file. + * + * @param filters Output newly created git_filter_list (or NULL) + * @param repo Repository object that contains `path` + * @param blob The blob to which the filter will be applied (if known) + * @param path Relative path of the file to be filtered + * @param mode Filtering direction (WT->ODB or ODB->WT) + * @param flags Combination of `git_filter_flag_t` flags + * @return 0 on success (which could still return NULL if no filters are + * needed for the requested file), <0 on error + */ +GIT_EXTERN(int) git_filter_list_load( + git_filter_list **filters, + git_repository *repo, + git_blob *blob, /* can be NULL */ + const char *path, + git_filter_mode_t mode, + uint32_t flags); + +/** + * Load the filter list for a given path. + * + * This will return 0 (success) but set the output git_filter_list to NULL + * if no filters are requested for the given file. + * + * @param filters Output newly created git_filter_list (or NULL) + * @param repo Repository object that contains `path` + * @param blob The blob to which the filter will be applied (if known) + * @param path Relative path of the file to be filtered + * @param mode Filtering direction (WT->ODB or ODB->WT) + * @param opts The `git_filter_options` to use when loading filters + * @return 0 on success (which could still return NULL if no filters are + * needed for the requested file), <0 on error + */ +GIT_EXTERN(int) git_filter_list_load_ext( + git_filter_list **filters, + git_repository *repo, + git_blob *blob, + const char *path, + git_filter_mode_t mode, + git_filter_options *opts); + +/** + * Query the filter list to see if a given filter (by name) will run. + * The built-in filters "crlf" and "ident" can be queried, otherwise this + * is the name of the filter specified by the filter attribute. + * + * This will return 0 if the given filter is not in the list, or 1 if + * the filter will be applied. + * + * @param filters A loaded git_filter_list (or NULL) + * @param name The name of the filter to query + * @return 1 if the filter is in the list, 0 otherwise + */ +GIT_EXTERN(int) git_filter_list_contains( + git_filter_list *filters, + const char *name); + +/** + * Apply filter list to a data buffer. + * + * @param out Buffer to store the result of the filtering + * @param filters A loaded git_filter_list (or NULL) + * @param in Buffer containing the data to filter + * @param in_len The length of the input buffer + * @return 0 on success, an error code otherwise + */ +GIT_EXTERN(int) git_filter_list_apply_to_buffer( + git_buf *out, + git_filter_list *filters, + const char *in, + size_t in_len); + +/** + * Apply a filter list to the contents of a file on disk + * + * @param out buffer into which to store the filtered file + * @param filters the list of filters to apply + * @param repo the repository in which to perform the filtering + * @param path the path of the file to filter, a relative path will be + * taken as relative to the workdir + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_filter_list_apply_to_file( + git_buf *out, + git_filter_list *filters, + git_repository *repo, + const char *path); + +/** + * Apply a filter list to the contents of a blob + * + * @param out buffer into which to store the filtered file + * @param filters the list of filters to apply + * @param blob the blob to filter + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_filter_list_apply_to_blob( + git_buf *out, + git_filter_list *filters, + git_blob *blob); + +/** + * Apply a filter list to an arbitrary buffer as a stream + * + * @param filters the list of filters to apply + * @param buffer the buffer to filter + * @param len the size of the buffer + * @param target the stream into which the data will be written + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_filter_list_stream_buffer( + git_filter_list *filters, + const char *buffer, + size_t len, + git_writestream *target); + +/** + * Apply a filter list to a file as a stream + * + * @param filters the list of filters to apply + * @param repo the repository in which to perform the filtering + * @param path the path of the file to filter, a relative path will be + * taken as relative to the workdir + * @param target the stream into which the data will be written + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_filter_list_stream_file( + git_filter_list *filters, + git_repository *repo, + const char *path, + git_writestream *target); + +/** + * Apply a filter list to a blob as a stream + * + * @param filters the list of filters to apply + * @param blob the blob to filter + * @param target the stream into which the data will be written + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_filter_list_stream_blob( + git_filter_list *filters, + git_blob *blob, + git_writestream *target); + +/** + * Free a git_filter_list + * + * @param filters A git_filter_list created by `git_filter_list_load` + */ +GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters); + + +GIT_END_DECL + +/** @} */ + +#endif diff --git a/3rdparty/libgit2/include/git2/global.h b/3rdparty/libgit2/include/git2/global.h index 2a87e10..8ff7714 100644 --- a/3rdparty/libgit2/include/git2/global.h +++ b/3rdparty/libgit2/include/git2/global.h @@ -1,44 +1,44 @@ -/* - * 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_global_h__ -#define INCLUDE_git_global_h__ - -#include "common.h" - -GIT_BEGIN_DECL - -/** - * Init the global state - * - * This function must be called before any other libgit2 function in - * order to set up global state and threading. - * - * This function may be called multiple times - it will return the number - * of times the initialization has been called (including this one) that have - * not subsequently been shutdown. - * - * @return the number of initializations of the library, or an error code. - */ -GIT_EXTERN(int) git_libgit2_init(void); - -/** - * Shutdown the global state - * - * Clean up the global state and threading context after calling it as - * many times as `git_libgit2_init()` was called - it will return the - * number of remainining initializations that have not been shutdown - * (after this one). - * - * @return the number of remaining initializations of the library, or an - * error code. - */ -GIT_EXTERN(int) git_libgit2_shutdown(void); - -/** @} */ -GIT_END_DECL -#endif - +/* + * 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_global_h__ +#define INCLUDE_git_global_h__ + +#include "common.h" + +GIT_BEGIN_DECL + +/** + * Init the global state + * + * This function must be called before any other libgit2 function in + * order to set up global state and threading. + * + * This function may be called multiple times - it will return the number + * of times the initialization has been called (including this one) that have + * not subsequently been shutdown. + * + * @return the number of initializations of the library, or an error code. + */ +GIT_EXTERN(int) git_libgit2_init(void); + +/** + * Shutdown the global state + * + * Clean up the global state and threading context after calling it as + * many times as `git_libgit2_init()` was called - it will return the + * number of remainining initializations that have not been shutdown + * (after this one). + * + * @return the number of remaining initializations of the library, or an + * error code. + */ +GIT_EXTERN(int) git_libgit2_shutdown(void); + +/** @} */ +GIT_END_DECL +#endif + diff --git a/3rdparty/libgit2/include/git2/graph.h b/3rdparty/libgit2/include/git2/graph.h index 56edb2f..f7a75ff 100644 --- a/3rdparty/libgit2/include/git2/graph.h +++ b/3rdparty/libgit2/include/git2/graph.h @@ -1,77 +1,77 @@ -/* - * 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_graph_h__ -#define INCLUDE_git_graph_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" - -/** - * @file git2/graph.h - * @brief Git graph traversal routines - * @defgroup git_revwalk Git graph traversal routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Count the number of unique commits between two commit objects - * - * There is no need for branches containing the commits to have any - * upstream relationship, but it helps to think of one as a branch and - * the other as its upstream, the `ahead` and `behind` values will be - * what git would report for the branches. - * - * @param ahead number of unique from commits in `upstream` - * @param behind number of unique from commits in `local` - * @param repo the repository where the commits exist - * @param local the commit for local - * @param upstream the commit for upstream - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_graph_ahead_behind(size_t *ahead, size_t *behind, git_repository *repo, const git_oid *local, const git_oid *upstream); - - -/** - * Determine if a commit is the descendant of another commit. - * - * Note that a commit is not considered a descendant of itself, in contrast - * to `git merge-base --is-ancestor`. - * - * @param repo the repository where the commits exist - * @param commit a previously loaded commit - * @param ancestor a potential ancestor commit - * @return 1 if the given commit is a descendant of the potential ancestor, - * 0 if not, error code otherwise. - */ -GIT_EXTERN(int) git_graph_descendant_of( - git_repository *repo, - const git_oid *commit, - const git_oid *ancestor); - -/** - * Determine if a commit is reachable from any of a list of commits by - * following parent edges. - * - * @param repo the repository where the commits exist - * @param commit a previously loaded commit - * @param length the number of commits in the provided `descendant_array` - * @param descendant_array oids of the commits - * @return 1 if the given commit is an ancestor of any of the given potential - * descendants, 0 if not, error code otherwise. - */ -GIT_EXTERN(int) git_graph_reachable_from_any( - git_repository *repo, - const git_oid *commit, - const git_oid descendant_array[], - size_t length); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_graph_h__ +#define INCLUDE_git_graph_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" + +/** + * @file git2/graph.h + * @brief Git graph traversal routines + * @defgroup git_revwalk Git graph traversal routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Count the number of unique commits between two commit objects + * + * There is no need for branches containing the commits to have any + * upstream relationship, but it helps to think of one as a branch and + * the other as its upstream, the `ahead` and `behind` values will be + * what git would report for the branches. + * + * @param ahead number of unique from commits in `upstream` + * @param behind number of unique from commits in `local` + * @param repo the repository where the commits exist + * @param local the commit for local + * @param upstream the commit for upstream + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_graph_ahead_behind(size_t *ahead, size_t *behind, git_repository *repo, const git_oid *local, const git_oid *upstream); + + +/** + * Determine if a commit is the descendant of another commit. + * + * Note that a commit is not considered a descendant of itself, in contrast + * to `git merge-base --is-ancestor`. + * + * @param repo the repository where the commits exist + * @param commit a previously loaded commit + * @param ancestor a potential ancestor commit + * @return 1 if the given commit is a descendant of the potential ancestor, + * 0 if not, error code otherwise. + */ +GIT_EXTERN(int) git_graph_descendant_of( + git_repository *repo, + const git_oid *commit, + const git_oid *ancestor); + +/** + * Determine if a commit is reachable from any of a list of commits by + * following parent edges. + * + * @param repo the repository where the commits exist + * @param commit a previously loaded commit + * @param length the number of commits in the provided `descendant_array` + * @param descendant_array oids of the commits + * @return 1 if the given commit is an ancestor of any of the given potential + * descendants, 0 if not, error code otherwise. + */ +GIT_EXTERN(int) git_graph_reachable_from_any( + git_repository *repo, + const git_oid *commit, + const git_oid descendant_array[], + size_t length); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/ignore.h b/3rdparty/libgit2/include/git2/ignore.h index 4c441c6..67095bc 100644 --- a/3rdparty/libgit2/include/git2/ignore.h +++ b/3rdparty/libgit2/include/git2/ignore.h @@ -1,78 +1,78 @@ -/* - * 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_ignore_h__ -#define INCLUDE_git_ignore_h__ - -#include "common.h" -#include "types.h" - -GIT_BEGIN_DECL - -/** - * Add ignore rules for a repository. - * - * Excludesfile rules (i.e. .gitignore rules) are generally read from - * .gitignore files in the repository tree or from a shared system file - * only if a "core.excludesfile" config value is set. The library also - * keeps a set of per-repository internal ignores that can be configured - * in-memory and will not persist. This function allows you to add to - * that internal rules list. - * - * Example usage: - * - * error = git_ignore_add_rule(myrepo, "*.c\ndir/\nFile with space\n"); - * - * This would add three rules to the ignores. - * - * @param repo The repository to add ignore rules to. - * @param rules Text of rules, the contents to add on a .gitignore file. - * It is okay to have multiple rules in the text; if so, - * each rule should be terminated with a newline. - * @return 0 on success - */ -GIT_EXTERN(int) git_ignore_add_rule( - git_repository *repo, - const char *rules); - -/** - * Clear ignore rules that were explicitly added. - * - * Resets to the default internal ignore rules. This will not turn off - * rules in .gitignore files that actually exist in the filesystem. - * - * The default internal ignores ignore ".", ".." and ".git" entries. - * - * @param repo The repository to remove ignore rules from. - * @return 0 on success - */ -GIT_EXTERN(int) git_ignore_clear_internal_rules( - git_repository *repo); - -/** - * Test if the ignore rules apply to a given path. - * - * This function checks the ignore rules to see if they would apply to the - * given file. This indicates if the file would be ignored regardless of - * whether the file is already in the index or committed to the repository. - * - * One way to think of this is if you were to do "git check-ignore --no-index" - * on the given file, would it be shown or not? - * - * @param ignored boolean returning 0 if the file is not ignored, 1 if it is - * @param repo a repository object - * @param path the file to check ignores for, relative to the repo's workdir. - * @return 0 if ignore rules could be processed for the file (regardless - * of whether it exists or not), or an error < 0 if they could not. - */ -GIT_EXTERN(int) git_ignore_path_is_ignored( - int *ignored, - git_repository *repo, - const char *path); - -GIT_END_DECL - -#endif +/* + * 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_ignore_h__ +#define INCLUDE_git_ignore_h__ + +#include "common.h" +#include "types.h" + +GIT_BEGIN_DECL + +/** + * Add ignore rules for a repository. + * + * Excludesfile rules (i.e. .gitignore rules) are generally read from + * .gitignore files in the repository tree or from a shared system file + * only if a "core.excludesfile" config value is set. The library also + * keeps a set of per-repository internal ignores that can be configured + * in-memory and will not persist. This function allows you to add to + * that internal rules list. + * + * Example usage: + * + * error = git_ignore_add_rule(myrepo, "*.c\ndir/\nFile with space\n"); + * + * This would add three rules to the ignores. + * + * @param repo The repository to add ignore rules to. + * @param rules Text of rules, the contents to add on a .gitignore file. + * It is okay to have multiple rules in the text; if so, + * each rule should be terminated with a newline. + * @return 0 on success + */ +GIT_EXTERN(int) git_ignore_add_rule( + git_repository *repo, + const char *rules); + +/** + * Clear ignore rules that were explicitly added. + * + * Resets to the default internal ignore rules. This will not turn off + * rules in .gitignore files that actually exist in the filesystem. + * + * The default internal ignores ignore ".", ".." and ".git" entries. + * + * @param repo The repository to remove ignore rules from. + * @return 0 on success + */ +GIT_EXTERN(int) git_ignore_clear_internal_rules( + git_repository *repo); + +/** + * Test if the ignore rules apply to a given path. + * + * This function checks the ignore rules to see if they would apply to the + * given file. This indicates if the file would be ignored regardless of + * whether the file is already in the index or committed to the repository. + * + * One way to think of this is if you were to do "git check-ignore --no-index" + * on the given file, would it be shown or not? + * + * @param ignored boolean returning 0 if the file is not ignored, 1 if it is + * @param repo a repository object + * @param path the file to check ignores for, relative to the repo's workdir. + * @return 0 if ignore rules could be processed for the file (regardless + * of whether it exists or not), or an error < 0 if they could not. + */ +GIT_EXTERN(int) git_ignore_path_is_ignored( + int *ignored, + git_repository *repo, + const char *path); + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/index.h b/3rdparty/libgit2/include/git2/index.h index 6e80637..db510ba 100644 --- a/3rdparty/libgit2/include/git2/index.h +++ b/3rdparty/libgit2/include/git2/index.h @@ -1,848 +1,848 @@ -/* - * 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_index_h__ -#define INCLUDE_git_index_h__ - -#include "common.h" -#include "indexer.h" -#include "types.h" -#include "oid.h" -#include "strarray.h" - -/** - * @file git2/index.h - * @brief Git index parsing and manipulation routines - * @defgroup git_index Git index parsing and manipulation routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** Time structure used in a git index entry */ -typedef struct { - int32_t seconds; - /* nsec should not be stored as time_t compatible */ - uint32_t nanoseconds; -} git_index_time; - -/** - * In-memory representation of a file entry in the index. - * - * This is a public structure that represents a file entry in the index. - * The meaning of the fields corresponds to core Git's documentation (in - * "Documentation/technical/index-format.txt"). - * - * The `flags` field consists of a number of bit fields which can be - * accessed via the first set of `GIT_INDEX_ENTRY_...` bitmasks below. - * These flags are all read from and persisted to disk. - * - * The `flags_extended` field also has a number of bit fields which can be - * accessed via the later `GIT_INDEX_ENTRY_...` bitmasks below. Some of - * these flags are read from and written to disk, but some are set aside - * for in-memory only reference. - * - * Note that the time and size fields are truncated to 32 bits. This - * is enough to detect changes, which is enough for the index to - * function as a cache, but it should not be taken as an authoritative - * source for that data. - */ -typedef struct git_index_entry { - git_index_time ctime; - git_index_time mtime; - - uint32_t dev; - uint32_t ino; - uint32_t mode; - uint32_t uid; - uint32_t gid; - uint32_t file_size; - - git_oid id; - - uint16_t flags; - uint16_t flags_extended; - - const char *path; -} git_index_entry; - -/** - * Bitmasks for on-disk fields of `git_index_entry`'s `flags` - * - * These bitmasks match the four fields in the `git_index_entry` `flags` - * value both in memory and on disk. You can use them to interpret the - * data in the `flags`. - */ - -#define GIT_INDEX_ENTRY_NAMEMASK (0x0fff) -#define GIT_INDEX_ENTRY_STAGEMASK (0x3000) -#define GIT_INDEX_ENTRY_STAGESHIFT 12 - -/** - * Flags for index entries - */ -typedef enum { - GIT_INDEX_ENTRY_EXTENDED = (0x4000), - GIT_INDEX_ENTRY_VALID = (0x8000) -} git_index_entry_flag_t; - -#define GIT_INDEX_ENTRY_STAGE(E) \ - (((E)->flags & GIT_INDEX_ENTRY_STAGEMASK) >> GIT_INDEX_ENTRY_STAGESHIFT) - -#define GIT_INDEX_ENTRY_STAGE_SET(E,S) do { \ - (E)->flags = ((E)->flags & ~GIT_INDEX_ENTRY_STAGEMASK) | \ - (((S) & 0x03) << GIT_INDEX_ENTRY_STAGESHIFT); } while (0) - -/** - * Bitmasks for on-disk fields of `git_index_entry`'s `flags_extended` - * - * In memory, the `flags_extended` fields are divided into two parts: the - * fields that are read from and written to disk, and other fields that - * in-memory only and used by libgit2. Only the flags in - * `GIT_INDEX_ENTRY_EXTENDED_FLAGS` will get saved on-disk. - * - * Thee first three bitmasks match the three fields in the - * `git_index_entry` `flags_extended` value that belong on disk. You - * can use them to interpret the data in the `flags_extended`. - * - * The rest of the bitmasks match the other fields in the `git_index_entry` - * `flags_extended` value that are only used in-memory by libgit2. - * You can use them to interpret the data in the `flags_extended`. - * - */ -typedef enum { - GIT_INDEX_ENTRY_INTENT_TO_ADD = (1 << 13), - GIT_INDEX_ENTRY_SKIP_WORKTREE = (1 << 14), - - GIT_INDEX_ENTRY_EXTENDED_FLAGS = (GIT_INDEX_ENTRY_INTENT_TO_ADD | GIT_INDEX_ENTRY_SKIP_WORKTREE), - - GIT_INDEX_ENTRY_UPTODATE = (1 << 2) -} git_index_entry_extended_flag_t; - -/** Capabilities of system that affect index actions. */ -typedef enum { - GIT_INDEX_CAPABILITY_IGNORE_CASE = 1, - GIT_INDEX_CAPABILITY_NO_FILEMODE = 2, - GIT_INDEX_CAPABILITY_NO_SYMLINKS = 4, - GIT_INDEX_CAPABILITY_FROM_OWNER = -1 -} git_index_capability_t; - - -/** Callback for APIs that add/remove/update files matching pathspec */ -typedef int GIT_CALLBACK(git_index_matched_path_cb)( - const char *path, const char *matched_pathspec, void *payload); - -/** Flags for APIs that add files matching pathspec */ -typedef enum { - GIT_INDEX_ADD_DEFAULT = 0, - GIT_INDEX_ADD_FORCE = (1u << 0), - GIT_INDEX_ADD_DISABLE_PATHSPEC_MATCH = (1u << 1), - GIT_INDEX_ADD_CHECK_PATHSPEC = (1u << 2) -} git_index_add_option_t; - -/** Git index stage states */ -typedef enum { - /** - * Match any index stage. - * - * Some index APIs take a stage to match; pass this value to match - * any entry matching the path regardless of stage. - */ - GIT_INDEX_STAGE_ANY = -1, - - /** A normal staged file in the index. */ - GIT_INDEX_STAGE_NORMAL = 0, - - /** The ancestor side of a conflict. */ - GIT_INDEX_STAGE_ANCESTOR = 1, - - /** The "ours" side of a conflict. */ - GIT_INDEX_STAGE_OURS = 2, - - /** The "theirs" side of a conflict. */ - GIT_INDEX_STAGE_THEIRS = 3 -} git_index_stage_t; - -/** - * Create a new bare Git index object as a memory representation - * of the Git index file in 'index_path', without a repository - * to back it. - * - * Since there is no ODB or working directory behind this index, - * any Index methods which rely on these (e.g. index_add_bypath) - * will fail with the GIT_ERROR error code. - * - * If you need to access the index of an actual repository, - * use the `git_repository_index` wrapper. - * - * The index must be freed once it's no longer in use. - * - * @param out the pointer for the new index - * @param index_path the path to the index file in disk - * @return 0 or an error code - */ - -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path, git_oid_t oid_type); -#else -GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path); -#endif - -/** - * Create an in-memory index object. - * - * This index object cannot be read/written to the filesystem, - * but may be used to perform in-memory index operations. - * - * The index must be freed once it's no longer in use. - * - * @param out the pointer for the new index - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_index_new(git_index **out, git_oid_t oid_type); -#else -GIT_EXTERN(int) git_index_new(git_index **out); -#endif - -/** - * Free an existing index object. - * - * @param index an existing index object - */ -GIT_EXTERN(void) git_index_free(git_index *index); - -/** - * Get the repository this index relates to - * - * @param index The index - * @return A pointer to the repository - */ -GIT_EXTERN(git_repository *) git_index_owner(const git_index *index); - -/** - * Read index capabilities flags. - * - * @param index An existing index object - * @return A combination of GIT_INDEX_CAPABILITY values - */ -GIT_EXTERN(int) git_index_caps(const git_index *index); - -/** - * Set index capabilities flags. - * - * If you pass `GIT_INDEX_CAPABILITY_FROM_OWNER` for the caps, then - * capabilities will be read from the config of the owner object, - * looking at `core.ignorecase`, `core.filemode`, `core.symlinks`. - * - * @param index An existing index object - * @param caps A combination of GIT_INDEX_CAPABILITY values - * @return 0 on success, -1 on failure - */ -GIT_EXTERN(int) git_index_set_caps(git_index *index, int caps); - -/** - * Get index on-disk version. - * - * Valid return values are 2, 3, or 4. If 3 is returned, an index - * with version 2 may be written instead, if the extension data in - * version 3 is not necessary. - * - * @param index An existing index object - * @return the index version - */ -GIT_EXTERN(unsigned int) git_index_version(git_index *index); - -/** - * Set index on-disk version. - * - * Valid values are 2, 3, or 4. If 2 is given, git_index_write may - * write an index with version 3 instead, if necessary to accurately - * represent the index. - * - * @param index An existing index object - * @param version The new version number - * @return 0 on success, -1 on failure - */ -GIT_EXTERN(int) git_index_set_version(git_index *index, unsigned int version); - -/** - * Update the contents of an existing index object in memory by reading - * from the hard disk. - * - * If `force` is true, this performs a "hard" read that discards in-memory - * changes and always reloads the on-disk index data. If there is no - * on-disk version, the index will be cleared. - * - * If `force` is false, this does a "soft" read that reloads the index - * data from disk only if it has changed since the last time it was - * loaded. Purely in-memory index data will be untouched. Be aware: if - * there are changes on disk, unwritten in-memory changes are discarded. - * - * @param index an existing index object - * @param force if true, always reload, vs. only read if file has changed - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_read(git_index *index, int force); - -/** - * Write an existing index object from memory back to disk - * using an atomic file lock. - * - * @param index an existing index object - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_write(git_index *index); - -/** - * Get the full path to the index file on disk. - * - * @param index an existing index object - * @return path to index file or NULL for in-memory index - */ -GIT_EXTERN(const char *) git_index_path(const git_index *index); - -#ifndef GIT_DEPRECATE_HARD -/** - * Get the checksum of the index - * - * This checksum is the SHA-1 hash over the index file (except the - * last 20 bytes which are the checksum itself). In cases where the - * index does not exist on-disk, it will be zeroed out. - * - * @deprecated this function is deprecated with no replacement - * @param index an existing index object - * @return a pointer to the checksum of the index - */ -GIT_EXTERN(const git_oid *) git_index_checksum(git_index *index); -#endif - -/** - * Read a tree into the index file with stats - * - * The current index contents will be replaced by the specified tree. - * - * @param index an existing index object - * @param tree tree to read - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_read_tree(git_index *index, const git_tree *tree); - -/** - * Write the index as a tree - * - * This method will scan the index and write a representation - * of its current state back to disk; it recursively creates - * tree objects for each of the subtrees stored in the index, - * but only returns the OID of the root tree. This is the OID - * that can be used e.g. to create a commit. - * - * The index instance cannot be bare, and needs to be associated - * to an existing repository. - * - * The index must not contain any file in conflict. - * - * @param out Pointer where to store the OID of the written tree - * @param index Index to write - * @return 0 on success, GIT_EUNMERGED when the index is not clean - * or an error code - */ -GIT_EXTERN(int) git_index_write_tree(git_oid *out, git_index *index); - -/** - * Write the index as a tree to the given repository - * - * This method will do the same as `git_index_write_tree`, but - * letting the user choose the repository where the tree will - * be written. - * - * The index must not contain any file in conflict. - * - * @param out Pointer where to store OID of the written tree - * @param index Index to write - * @param repo Repository where to write the tree - * @return 0 on success, GIT_EUNMERGED when the index is not clean - * or an error code - */ -GIT_EXTERN(int) git_index_write_tree_to(git_oid *out, git_index *index, git_repository *repo); - -/**@}*/ - -/** @name Raw Index Entry Functions - * - * These functions work on index entries, and allow for raw manipulation - * of the entries. - */ -/**@{*/ - -/* Index entry manipulation */ - -/** - * Get the count of entries currently in the index - * - * @param index an existing index object - * @return integer of count of current entries - */ -GIT_EXTERN(size_t) git_index_entrycount(const git_index *index); - -/** - * Clear the contents (all the entries) of an index object. - * - * This clears the index object in memory; changes must be explicitly - * written to disk for them to take effect persistently. - * - * @param index an existing index object - * @return 0 on success, error code < 0 on failure - */ -GIT_EXTERN(int) git_index_clear(git_index *index); - -/** - * Get a pointer to one of the entries in the index - * - * The entry is not modifiable and should not be freed. Because the - * `git_index_entry` struct is a publicly defined struct, you should - * be able to make your own permanent copy of the data if necessary. - * - * @param index an existing index object - * @param n the position of the entry - * @return a pointer to the entry; NULL if out of bounds - */ -GIT_EXTERN(const git_index_entry *) git_index_get_byindex( - git_index *index, size_t n); - -/** - * Get a pointer to one of the entries in the index - * - * The entry is not modifiable and should not be freed. Because the - * `git_index_entry` struct is a publicly defined struct, you should - * be able to make your own permanent copy of the data if necessary. - * - * @param index an existing index object - * @param path path to search - * @param stage stage to search - * @return a pointer to the entry; NULL if it was not found - */ -GIT_EXTERN(const git_index_entry *) git_index_get_bypath( - git_index *index, const char *path, int stage); - -/** - * Remove an entry from the index - * - * @param index an existing index object - * @param path path to search - * @param stage stage to search - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_remove(git_index *index, const char *path, int stage); - -/** - * Remove all entries from the index under a given directory - * - * @param index an existing index object - * @param dir container directory path - * @param stage stage to search - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_remove_directory( - git_index *index, const char *dir, int stage); - -/** - * Add or update an index entry from an in-memory struct - * - * If a previous index entry exists that has the same path and stage - * as the given 'source_entry', it will be replaced. Otherwise, the - * 'source_entry' will be added. - * - * A full copy (including the 'path' string) of the given - * 'source_entry' will be inserted on the index. - * - * @param index an existing index object - * @param source_entry new entry object - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_add(git_index *index, const git_index_entry *source_entry); - -/** - * Return the stage number from a git index entry - * - * This entry is calculated from the entry's flag attribute like this: - * - * (entry->flags & GIT_INDEX_ENTRY_STAGEMASK) >> GIT_INDEX_ENTRY_STAGESHIFT - * - * @param entry The entry - * @return the stage number - */ -GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry); - -/** - * Return whether the given index entry is a conflict (has a high stage - * entry). This is simply shorthand for `git_index_entry_stage > 0`. - * - * @param entry The entry - * @return 1 if the entry is a conflict entry, 0 otherwise - */ -GIT_EXTERN(int) git_index_entry_is_conflict(const git_index_entry *entry); - -/**@}*/ - -/** @name Index Entry Iteration Functions - * - * These functions provide an iterator for index entries. - */ -/**@{*/ - -/** - * Create an iterator that will return every entry contained in the - * index at the time of creation. Entries are returned in order, - * sorted by path. This iterator is backed by a snapshot that allows - * callers to modify the index while iterating without affecting the - * iterator. - * - * @param iterator_out The newly created iterator - * @param index The index to iterate - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_index_iterator_new( - git_index_iterator **iterator_out, - git_index *index); - -/** - * Return the next index entry in-order from the iterator. - * - * @param out Pointer to store the index entry in - * @param iterator The iterator - * @return 0, GIT_ITEROVER on iteration completion or an error code - */ -GIT_EXTERN(int) git_index_iterator_next( - const git_index_entry **out, - git_index_iterator *iterator); - -/** - * Free the index iterator - * - * @param iterator The iterator to free - */ -GIT_EXTERN(void) git_index_iterator_free(git_index_iterator *iterator); - -/**@}*/ - -/** @name Workdir Index Entry Functions - * - * These functions work on index entries specifically in the working - * directory (ie, stage 0). - */ -/**@{*/ - -/** - * Add or update an index entry from a file on disk - * - * The file `path` must be relative to the repository's - * working folder and must be readable. - * - * This method will fail in bare index instances. - * - * This forces the file to be added to the index, not looking - * at gitignore rules. Those rules can be evaluated through - * the git_status APIs (in status.h) before calling this. - * - * If this file currently is the result of a merge conflict, this - * file will no longer be marked as conflicting. The data about - * the conflict will be moved to the "resolve undo" (REUC) section. - * - * @param index an existing index object - * @param path filename to add - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_add_bypath(git_index *index, const char *path); - -/** - * Add or update an index entry from a buffer in memory - * - * This method will create a blob in the repository that owns the - * index and then add the index entry to the index. The `path` of the - * entry represents the position of the blob relative to the - * repository's root folder. - * - * If a previous index entry exists that has the same path as the - * given 'entry', it will be replaced. Otherwise, the 'entry' will be - * added. - * - * This forces the file to be added to the index, not looking - * at gitignore rules. Those rules can be evaluated through - * the git_status APIs (in status.h) before calling this. - * - * If this file currently is the result of a merge conflict, this - * file will no longer be marked as conflicting. The data about - * the conflict will be moved to the "resolve undo" (REUC) section. - * - * @param index an existing index object - * @param entry filename to add - * @param buffer data to be written into the blob - * @param len length of the data - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_add_from_buffer( - git_index *index, - const git_index_entry *entry, - const void *buffer, size_t len); - -/** - * Remove an index entry corresponding to a file on disk - * - * The file `path` must be relative to the repository's - * working folder. It may exist. - * - * If this file currently is the result of a merge conflict, this - * file will no longer be marked as conflicting. The data about - * the conflict will be moved to the "resolve undo" (REUC) section. - * - * @param index an existing index object - * @param path filename to remove - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_remove_bypath(git_index *index, const char *path); - -/** - * Add or update index entries matching files in the working directory. - * - * This method will fail in bare index instances. - * - * The `pathspec` is a list of file names or shell glob patterns that will - * be matched against files in the repository's working directory. Each - * file that matches will be added to the index (either updating an - * existing entry or adding a new entry). You can disable glob expansion - * and force exact matching with the `GIT_INDEX_ADD_DISABLE_PATHSPEC_MATCH` - * flag. - * - * Files that are ignored will be skipped (unlike `git_index_add_bypath`). - * If a file is already tracked in the index, then it *will* be updated - * even if it is ignored. Pass the `GIT_INDEX_ADD_FORCE` flag to skip - * the checking of ignore rules. - * - * To emulate `git add -A` and generate an error if the pathspec contains - * the exact path of an ignored file (when not using FORCE), add the - * `GIT_INDEX_ADD_CHECK_PATHSPEC` flag. This checks that each entry - * in the `pathspec` that is an exact match to a filename on disk is - * either not ignored or already in the index. If this check fails, the - * function will return GIT_EINVALIDSPEC. - * - * To emulate `git add -A` with the "dry-run" option, just use a callback - * function that always returns a positive value. See below for details. - * - * If any files are currently the result of a merge conflict, those files - * will no longer be marked as conflicting. The data about the conflicts - * will be moved to the "resolve undo" (REUC) section. - * - * If you provide a callback function, it will be invoked on each matching - * item in the working directory immediately *before* it is added to / - * updated in the index. Returning zero will add the item to the index, - * greater than zero will skip the item, and less than zero will abort the - * scan and return that value to the caller. - * - * @param index an existing index object - * @param pathspec array of path patterns - * @param flags combination of git_index_add_option_t flags - * @param callback notification callback for each added/updated path (also - * gets index of matching pathspec entry); can be NULL; - * return 0 to add, >0 to skip, <0 to abort scan. - * @param payload payload passed through to callback function - * @return 0 on success, negative callback return value, or error code - */ -GIT_EXTERN(int) git_index_add_all( - git_index *index, - const git_strarray *pathspec, - unsigned int flags, - git_index_matched_path_cb callback, - void *payload); - -/** - * Remove all matching index entries. - * - * If you provide a callback function, it will be invoked on each matching - * item in the index immediately *before* it is removed. Return 0 to - * remove the item, > 0 to skip the item, and < 0 to abort the scan. - * - * @param index An existing index object - * @param pathspec array of path patterns - * @param callback notification callback for each removed path (also - * gets index of matching pathspec entry); can be NULL; - * return 0 to add, >0 to skip, <0 to abort scan. - * @param payload payload passed through to callback function - * @return 0 on success, negative callback return value, or error code - */ -GIT_EXTERN(int) git_index_remove_all( - git_index *index, - const git_strarray *pathspec, - git_index_matched_path_cb callback, - void *payload); - -/** - * Update all index entries to match the working directory - * - * This method will fail in bare index instances. - * - * This scans the existing index entries and synchronizes them with the - * working directory, deleting them if the corresponding working directory - * file no longer exists otherwise updating the information (including - * adding the latest version of file to the ODB if needed). - * - * If you provide a callback function, it will be invoked on each matching - * item in the index immediately *before* it is updated (either refreshed - * or removed depending on working directory state). Return 0 to proceed - * with updating the item, > 0 to skip the item, and < 0 to abort the scan. - * - * @param index An existing index object - * @param pathspec array of path patterns - * @param callback notification callback for each updated path (also - * gets index of matching pathspec entry); can be NULL; - * return 0 to add, >0 to skip, <0 to abort scan. - * @param payload payload passed through to callback function - * @return 0 on success, negative callback return value, or error code - */ -GIT_EXTERN(int) git_index_update_all( - git_index *index, - const git_strarray *pathspec, - git_index_matched_path_cb callback, - void *payload); - -/** - * Find the first position of any entries which point to given - * path in the Git index. - * - * @param at_pos the address to which the position of the index entry is written (optional) - * @param index an existing index object - * @param path path to search - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_find(size_t *at_pos, git_index *index, const char *path); - -/** - * Find the first position of any entries matching a prefix. To find the first position - * of a path inside a given folder, suffix the prefix with a '/'. - * - * @param at_pos the address to which the position of the index entry is written (optional) - * @param index an existing index object - * @param prefix the prefix to search for - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_find_prefix(size_t *at_pos, git_index *index, const char *prefix); - -/**@}*/ - -/** @name Conflict Index Entry Functions - * - * These functions work on conflict index entries specifically (ie, stages 1-3) - */ -/**@{*/ - -/** - * Add or update index entries to represent a conflict. Any staged - * entries that exist at the given paths will be removed. - * - * The entries are the entries from the tree included in the merge. Any - * entry may be null to indicate that that file was not present in the - * trees during the merge. For example, ancestor_entry may be NULL to - * indicate that a file was added in both branches and must be resolved. - * - * @param index an existing index object - * @param ancestor_entry the entry data for the ancestor of the conflict - * @param our_entry the entry data for our side of the merge conflict - * @param their_entry the entry data for their side of the merge conflict - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_conflict_add( - git_index *index, - const git_index_entry *ancestor_entry, - const git_index_entry *our_entry, - const git_index_entry *their_entry); - -/** - * Get the index entries that represent a conflict of a single file. - * - * The entries are not modifiable and should not be freed. Because the - * `git_index_entry` struct is a publicly defined struct, you should - * be able to make your own permanent copy of the data if necessary. - * - * @param ancestor_out Pointer to store the ancestor entry - * @param our_out Pointer to store the our entry - * @param their_out Pointer to store the their entry - * @param index an existing index object - * @param path path to search - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_conflict_get( - const git_index_entry **ancestor_out, - const git_index_entry **our_out, - const git_index_entry **their_out, - git_index *index, - const char *path); - -/** - * Removes the index entries that represent a conflict of a single file. - * - * @param index an existing index object - * @param path path to remove conflicts for - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_conflict_remove(git_index *index, const char *path); - -/** - * Remove all conflicts in the index (entries with a stage greater than 0). - * - * @param index an existing index object - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_conflict_cleanup(git_index *index); - -/** - * Determine if the index contains entries representing file conflicts. - * - * @param index An existing index object. - * @return 1 if at least one conflict is found, 0 otherwise. - */ -GIT_EXTERN(int) git_index_has_conflicts(const git_index *index); - -/** - * Create an iterator for the conflicts in the index. - * - * The index must not be modified while iterating; the results are undefined. - * - * @param iterator_out The newly created conflict iterator - * @param index The index to scan - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_conflict_iterator_new( - git_index_conflict_iterator **iterator_out, - git_index *index); - -/** - * Returns the current conflict (ancestor, ours and theirs entry) and - * advance the iterator internally to the next value. - * - * @param ancestor_out Pointer to store the ancestor side of the conflict - * @param our_out Pointer to store our side of the conflict - * @param their_out Pointer to store their side of the conflict - * @param iterator The conflict iterator. - * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code - * (negative value) - */ -GIT_EXTERN(int) git_index_conflict_next( - const git_index_entry **ancestor_out, - const git_index_entry **our_out, - const git_index_entry **their_out, - git_index_conflict_iterator *iterator); - -/** - * Frees a `git_index_conflict_iterator`. - * - * @param iterator pointer to the iterator - */ -GIT_EXTERN(void) git_index_conflict_iterator_free( - git_index_conflict_iterator *iterator); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_index_h__ +#define INCLUDE_git_index_h__ + +#include "common.h" +#include "indexer.h" +#include "types.h" +#include "oid.h" +#include "strarray.h" + +/** + * @file git2/index.h + * @brief Git index parsing and manipulation routines + * @defgroup git_index Git index parsing and manipulation routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** Time structure used in a git index entry */ +typedef struct { + int32_t seconds; + /* nsec should not be stored as time_t compatible */ + uint32_t nanoseconds; +} git_index_time; + +/** + * In-memory representation of a file entry in the index. + * + * This is a public structure that represents a file entry in the index. + * The meaning of the fields corresponds to core Git's documentation (in + * "Documentation/technical/index-format.txt"). + * + * The `flags` field consists of a number of bit fields which can be + * accessed via the first set of `GIT_INDEX_ENTRY_...` bitmasks below. + * These flags are all read from and persisted to disk. + * + * The `flags_extended` field also has a number of bit fields which can be + * accessed via the later `GIT_INDEX_ENTRY_...` bitmasks below. Some of + * these flags are read from and written to disk, but some are set aside + * for in-memory only reference. + * + * Note that the time and size fields are truncated to 32 bits. This + * is enough to detect changes, which is enough for the index to + * function as a cache, but it should not be taken as an authoritative + * source for that data. + */ +typedef struct git_index_entry { + git_index_time ctime; + git_index_time mtime; + + uint32_t dev; + uint32_t ino; + uint32_t mode; + uint32_t uid; + uint32_t gid; + uint32_t file_size; + + git_oid id; + + uint16_t flags; + uint16_t flags_extended; + + const char *path; +} git_index_entry; + +/** + * Bitmasks for on-disk fields of `git_index_entry`'s `flags` + * + * These bitmasks match the four fields in the `git_index_entry` `flags` + * value both in memory and on disk. You can use them to interpret the + * data in the `flags`. + */ + +#define GIT_INDEX_ENTRY_NAMEMASK (0x0fff) +#define GIT_INDEX_ENTRY_STAGEMASK (0x3000) +#define GIT_INDEX_ENTRY_STAGESHIFT 12 + +/** + * Flags for index entries + */ +typedef enum { + GIT_INDEX_ENTRY_EXTENDED = (0x4000), + GIT_INDEX_ENTRY_VALID = (0x8000) +} git_index_entry_flag_t; + +#define GIT_INDEX_ENTRY_STAGE(E) \ + (((E)->flags & GIT_INDEX_ENTRY_STAGEMASK) >> GIT_INDEX_ENTRY_STAGESHIFT) + +#define GIT_INDEX_ENTRY_STAGE_SET(E,S) do { \ + (E)->flags = ((E)->flags & ~GIT_INDEX_ENTRY_STAGEMASK) | \ + (((S) & 0x03) << GIT_INDEX_ENTRY_STAGESHIFT); } while (0) + +/** + * Bitmasks for on-disk fields of `git_index_entry`'s `flags_extended` + * + * In memory, the `flags_extended` fields are divided into two parts: the + * fields that are read from and written to disk, and other fields that + * in-memory only and used by libgit2. Only the flags in + * `GIT_INDEX_ENTRY_EXTENDED_FLAGS` will get saved on-disk. + * + * Thee first three bitmasks match the three fields in the + * `git_index_entry` `flags_extended` value that belong on disk. You + * can use them to interpret the data in the `flags_extended`. + * + * The rest of the bitmasks match the other fields in the `git_index_entry` + * `flags_extended` value that are only used in-memory by libgit2. + * You can use them to interpret the data in the `flags_extended`. + * + */ +typedef enum { + GIT_INDEX_ENTRY_INTENT_TO_ADD = (1 << 13), + GIT_INDEX_ENTRY_SKIP_WORKTREE = (1 << 14), + + GIT_INDEX_ENTRY_EXTENDED_FLAGS = (GIT_INDEX_ENTRY_INTENT_TO_ADD | GIT_INDEX_ENTRY_SKIP_WORKTREE), + + GIT_INDEX_ENTRY_UPTODATE = (1 << 2) +} git_index_entry_extended_flag_t; + +/** Capabilities of system that affect index actions. */ +typedef enum { + GIT_INDEX_CAPABILITY_IGNORE_CASE = 1, + GIT_INDEX_CAPABILITY_NO_FILEMODE = 2, + GIT_INDEX_CAPABILITY_NO_SYMLINKS = 4, + GIT_INDEX_CAPABILITY_FROM_OWNER = -1 +} git_index_capability_t; + + +/** Callback for APIs that add/remove/update files matching pathspec */ +typedef int GIT_CALLBACK(git_index_matched_path_cb)( + const char *path, const char *matched_pathspec, void *payload); + +/** Flags for APIs that add files matching pathspec */ +typedef enum { + GIT_INDEX_ADD_DEFAULT = 0, + GIT_INDEX_ADD_FORCE = (1u << 0), + GIT_INDEX_ADD_DISABLE_PATHSPEC_MATCH = (1u << 1), + GIT_INDEX_ADD_CHECK_PATHSPEC = (1u << 2) +} git_index_add_option_t; + +/** Git index stage states */ +typedef enum { + /** + * Match any index stage. + * + * Some index APIs take a stage to match; pass this value to match + * any entry matching the path regardless of stage. + */ + GIT_INDEX_STAGE_ANY = -1, + + /** A normal staged file in the index. */ + GIT_INDEX_STAGE_NORMAL = 0, + + /** The ancestor side of a conflict. */ + GIT_INDEX_STAGE_ANCESTOR = 1, + + /** The "ours" side of a conflict. */ + GIT_INDEX_STAGE_OURS = 2, + + /** The "theirs" side of a conflict. */ + GIT_INDEX_STAGE_THEIRS = 3 +} git_index_stage_t; + +/** + * Create a new bare Git index object as a memory representation + * of the Git index file in 'index_path', without a repository + * to back it. + * + * Since there is no ODB or working directory behind this index, + * any Index methods which rely on these (e.g. index_add_bypath) + * will fail with the GIT_ERROR error code. + * + * If you need to access the index of an actual repository, + * use the `git_repository_index` wrapper. + * + * The index must be freed once it's no longer in use. + * + * @param out the pointer for the new index + * @param index_path the path to the index file in disk + * @return 0 or an error code + */ + +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path, git_oid_t oid_type); +#else +GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path); +#endif + +/** + * Create an in-memory index object. + * + * This index object cannot be read/written to the filesystem, + * but may be used to perform in-memory index operations. + * + * The index must be freed once it's no longer in use. + * + * @param out the pointer for the new index + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_index_new(git_index **out, git_oid_t oid_type); +#else +GIT_EXTERN(int) git_index_new(git_index **out); +#endif + +/** + * Free an existing index object. + * + * @param index an existing index object + */ +GIT_EXTERN(void) git_index_free(git_index *index); + +/** + * Get the repository this index relates to + * + * @param index The index + * @return A pointer to the repository + */ +GIT_EXTERN(git_repository *) git_index_owner(const git_index *index); + +/** + * Read index capabilities flags. + * + * @param index An existing index object + * @return A combination of GIT_INDEX_CAPABILITY values + */ +GIT_EXTERN(int) git_index_caps(const git_index *index); + +/** + * Set index capabilities flags. + * + * If you pass `GIT_INDEX_CAPABILITY_FROM_OWNER` for the caps, then + * capabilities will be read from the config of the owner object, + * looking at `core.ignorecase`, `core.filemode`, `core.symlinks`. + * + * @param index An existing index object + * @param caps A combination of GIT_INDEX_CAPABILITY values + * @return 0 on success, -1 on failure + */ +GIT_EXTERN(int) git_index_set_caps(git_index *index, int caps); + +/** + * Get index on-disk version. + * + * Valid return values are 2, 3, or 4. If 3 is returned, an index + * with version 2 may be written instead, if the extension data in + * version 3 is not necessary. + * + * @param index An existing index object + * @return the index version + */ +GIT_EXTERN(unsigned int) git_index_version(git_index *index); + +/** + * Set index on-disk version. + * + * Valid values are 2, 3, or 4. If 2 is given, git_index_write may + * write an index with version 3 instead, if necessary to accurately + * represent the index. + * + * @param index An existing index object + * @param version The new version number + * @return 0 on success, -1 on failure + */ +GIT_EXTERN(int) git_index_set_version(git_index *index, unsigned int version); + +/** + * Update the contents of an existing index object in memory by reading + * from the hard disk. + * + * If `force` is true, this performs a "hard" read that discards in-memory + * changes and always reloads the on-disk index data. If there is no + * on-disk version, the index will be cleared. + * + * If `force` is false, this does a "soft" read that reloads the index + * data from disk only if it has changed since the last time it was + * loaded. Purely in-memory index data will be untouched. Be aware: if + * there are changes on disk, unwritten in-memory changes are discarded. + * + * @param index an existing index object + * @param force if true, always reload, vs. only read if file has changed + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_read(git_index *index, int force); + +/** + * Write an existing index object from memory back to disk + * using an atomic file lock. + * + * @param index an existing index object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_write(git_index *index); + +/** + * Get the full path to the index file on disk. + * + * @param index an existing index object + * @return path to index file or NULL for in-memory index + */ +GIT_EXTERN(const char *) git_index_path(const git_index *index); + +#ifndef GIT_DEPRECATE_HARD +/** + * Get the checksum of the index + * + * This checksum is the SHA-1 hash over the index file (except the + * last 20 bytes which are the checksum itself). In cases where the + * index does not exist on-disk, it will be zeroed out. + * + * @deprecated this function is deprecated with no replacement + * @param index an existing index object + * @return a pointer to the checksum of the index + */ +GIT_EXTERN(const git_oid *) git_index_checksum(git_index *index); +#endif + +/** + * Read a tree into the index file with stats + * + * The current index contents will be replaced by the specified tree. + * + * @param index an existing index object + * @param tree tree to read + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_read_tree(git_index *index, const git_tree *tree); + +/** + * Write the index as a tree + * + * This method will scan the index and write a representation + * of its current state back to disk; it recursively creates + * tree objects for each of the subtrees stored in the index, + * but only returns the OID of the root tree. This is the OID + * that can be used e.g. to create a commit. + * + * The index instance cannot be bare, and needs to be associated + * to an existing repository. + * + * The index must not contain any file in conflict. + * + * @param out Pointer where to store the OID of the written tree + * @param index Index to write + * @return 0 on success, GIT_EUNMERGED when the index is not clean + * or an error code + */ +GIT_EXTERN(int) git_index_write_tree(git_oid *out, git_index *index); + +/** + * Write the index as a tree to the given repository + * + * This method will do the same as `git_index_write_tree`, but + * letting the user choose the repository where the tree will + * be written. + * + * The index must not contain any file in conflict. + * + * @param out Pointer where to store OID of the written tree + * @param index Index to write + * @param repo Repository where to write the tree + * @return 0 on success, GIT_EUNMERGED when the index is not clean + * or an error code + */ +GIT_EXTERN(int) git_index_write_tree_to(git_oid *out, git_index *index, git_repository *repo); + +/**@}*/ + +/** @name Raw Index Entry Functions + * + * These functions work on index entries, and allow for raw manipulation + * of the entries. + */ +/**@{*/ + +/* Index entry manipulation */ + +/** + * Get the count of entries currently in the index + * + * @param index an existing index object + * @return integer of count of current entries + */ +GIT_EXTERN(size_t) git_index_entrycount(const git_index *index); + +/** + * Clear the contents (all the entries) of an index object. + * + * This clears the index object in memory; changes must be explicitly + * written to disk for them to take effect persistently. + * + * @param index an existing index object + * @return 0 on success, error code < 0 on failure + */ +GIT_EXTERN(int) git_index_clear(git_index *index); + +/** + * Get a pointer to one of the entries in the index + * + * The entry is not modifiable and should not be freed. Because the + * `git_index_entry` struct is a publicly defined struct, you should + * be able to make your own permanent copy of the data if necessary. + * + * @param index an existing index object + * @param n the position of the entry + * @return a pointer to the entry; NULL if out of bounds + */ +GIT_EXTERN(const git_index_entry *) git_index_get_byindex( + git_index *index, size_t n); + +/** + * Get a pointer to one of the entries in the index + * + * The entry is not modifiable and should not be freed. Because the + * `git_index_entry` struct is a publicly defined struct, you should + * be able to make your own permanent copy of the data if necessary. + * + * @param index an existing index object + * @param path path to search + * @param stage stage to search + * @return a pointer to the entry; NULL if it was not found + */ +GIT_EXTERN(const git_index_entry *) git_index_get_bypath( + git_index *index, const char *path, int stage); + +/** + * Remove an entry from the index + * + * @param index an existing index object + * @param path path to search + * @param stage stage to search + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_remove(git_index *index, const char *path, int stage); + +/** + * Remove all entries from the index under a given directory + * + * @param index an existing index object + * @param dir container directory path + * @param stage stage to search + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_remove_directory( + git_index *index, const char *dir, int stage); + +/** + * Add or update an index entry from an in-memory struct + * + * If a previous index entry exists that has the same path and stage + * as the given 'source_entry', it will be replaced. Otherwise, the + * 'source_entry' will be added. + * + * A full copy (including the 'path' string) of the given + * 'source_entry' will be inserted on the index. + * + * @param index an existing index object + * @param source_entry new entry object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_add(git_index *index, const git_index_entry *source_entry); + +/** + * Return the stage number from a git index entry + * + * This entry is calculated from the entry's flag attribute like this: + * + * (entry->flags & GIT_INDEX_ENTRY_STAGEMASK) >> GIT_INDEX_ENTRY_STAGESHIFT + * + * @param entry The entry + * @return the stage number + */ +GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry); + +/** + * Return whether the given index entry is a conflict (has a high stage + * entry). This is simply shorthand for `git_index_entry_stage > 0`. + * + * @param entry The entry + * @return 1 if the entry is a conflict entry, 0 otherwise + */ +GIT_EXTERN(int) git_index_entry_is_conflict(const git_index_entry *entry); + +/**@}*/ + +/** @name Index Entry Iteration Functions + * + * These functions provide an iterator for index entries. + */ +/**@{*/ + +/** + * Create an iterator that will return every entry contained in the + * index at the time of creation. Entries are returned in order, + * sorted by path. This iterator is backed by a snapshot that allows + * callers to modify the index while iterating without affecting the + * iterator. + * + * @param iterator_out The newly created iterator + * @param index The index to iterate + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_index_iterator_new( + git_index_iterator **iterator_out, + git_index *index); + +/** + * Return the next index entry in-order from the iterator. + * + * @param out Pointer to store the index entry in + * @param iterator The iterator + * @return 0, GIT_ITEROVER on iteration completion or an error code + */ +GIT_EXTERN(int) git_index_iterator_next( + const git_index_entry **out, + git_index_iterator *iterator); + +/** + * Free the index iterator + * + * @param iterator The iterator to free + */ +GIT_EXTERN(void) git_index_iterator_free(git_index_iterator *iterator); + +/**@}*/ + +/** @name Workdir Index Entry Functions + * + * These functions work on index entries specifically in the working + * directory (ie, stage 0). + */ +/**@{*/ + +/** + * Add or update an index entry from a file on disk + * + * The file `path` must be relative to the repository's + * working folder and must be readable. + * + * This method will fail in bare index instances. + * + * This forces the file to be added to the index, not looking + * at gitignore rules. Those rules can be evaluated through + * the git_status APIs (in status.h) before calling this. + * + * If this file currently is the result of a merge conflict, this + * file will no longer be marked as conflicting. The data about + * the conflict will be moved to the "resolve undo" (REUC) section. + * + * @param index an existing index object + * @param path filename to add + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_add_bypath(git_index *index, const char *path); + +/** + * Add or update an index entry from a buffer in memory + * + * This method will create a blob in the repository that owns the + * index and then add the index entry to the index. The `path` of the + * entry represents the position of the blob relative to the + * repository's root folder. + * + * If a previous index entry exists that has the same path as the + * given 'entry', it will be replaced. Otherwise, the 'entry' will be + * added. + * + * This forces the file to be added to the index, not looking + * at gitignore rules. Those rules can be evaluated through + * the git_status APIs (in status.h) before calling this. + * + * If this file currently is the result of a merge conflict, this + * file will no longer be marked as conflicting. The data about + * the conflict will be moved to the "resolve undo" (REUC) section. + * + * @param index an existing index object + * @param entry filename to add + * @param buffer data to be written into the blob + * @param len length of the data + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_add_from_buffer( + git_index *index, + const git_index_entry *entry, + const void *buffer, size_t len); + +/** + * Remove an index entry corresponding to a file on disk + * + * The file `path` must be relative to the repository's + * working folder. It may exist. + * + * If this file currently is the result of a merge conflict, this + * file will no longer be marked as conflicting. The data about + * the conflict will be moved to the "resolve undo" (REUC) section. + * + * @param index an existing index object + * @param path filename to remove + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_remove_bypath(git_index *index, const char *path); + +/** + * Add or update index entries matching files in the working directory. + * + * This method will fail in bare index instances. + * + * The `pathspec` is a list of file names or shell glob patterns that will + * be matched against files in the repository's working directory. Each + * file that matches will be added to the index (either updating an + * existing entry or adding a new entry). You can disable glob expansion + * and force exact matching with the `GIT_INDEX_ADD_DISABLE_PATHSPEC_MATCH` + * flag. + * + * Files that are ignored will be skipped (unlike `git_index_add_bypath`). + * If a file is already tracked in the index, then it *will* be updated + * even if it is ignored. Pass the `GIT_INDEX_ADD_FORCE` flag to skip + * the checking of ignore rules. + * + * To emulate `git add -A` and generate an error if the pathspec contains + * the exact path of an ignored file (when not using FORCE), add the + * `GIT_INDEX_ADD_CHECK_PATHSPEC` flag. This checks that each entry + * in the `pathspec` that is an exact match to a filename on disk is + * either not ignored or already in the index. If this check fails, the + * function will return GIT_EINVALIDSPEC. + * + * To emulate `git add -A` with the "dry-run" option, just use a callback + * function that always returns a positive value. See below for details. + * + * If any files are currently the result of a merge conflict, those files + * will no longer be marked as conflicting. The data about the conflicts + * will be moved to the "resolve undo" (REUC) section. + * + * If you provide a callback function, it will be invoked on each matching + * item in the working directory immediately *before* it is added to / + * updated in the index. Returning zero will add the item to the index, + * greater than zero will skip the item, and less than zero will abort the + * scan and return that value to the caller. + * + * @param index an existing index object + * @param pathspec array of path patterns + * @param flags combination of git_index_add_option_t flags + * @param callback notification callback for each added/updated path (also + * gets index of matching pathspec entry); can be NULL; + * return 0 to add, >0 to skip, <0 to abort scan. + * @param payload payload passed through to callback function + * @return 0 on success, negative callback return value, or error code + */ +GIT_EXTERN(int) git_index_add_all( + git_index *index, + const git_strarray *pathspec, + unsigned int flags, + git_index_matched_path_cb callback, + void *payload); + +/** + * Remove all matching index entries. + * + * If you provide a callback function, it will be invoked on each matching + * item in the index immediately *before* it is removed. Return 0 to + * remove the item, > 0 to skip the item, and < 0 to abort the scan. + * + * @param index An existing index object + * @param pathspec array of path patterns + * @param callback notification callback for each removed path (also + * gets index of matching pathspec entry); can be NULL; + * return 0 to add, >0 to skip, <0 to abort scan. + * @param payload payload passed through to callback function + * @return 0 on success, negative callback return value, or error code + */ +GIT_EXTERN(int) git_index_remove_all( + git_index *index, + const git_strarray *pathspec, + git_index_matched_path_cb callback, + void *payload); + +/** + * Update all index entries to match the working directory + * + * This method will fail in bare index instances. + * + * This scans the existing index entries and synchronizes them with the + * working directory, deleting them if the corresponding working directory + * file no longer exists otherwise updating the information (including + * adding the latest version of file to the ODB if needed). + * + * If you provide a callback function, it will be invoked on each matching + * item in the index immediately *before* it is updated (either refreshed + * or removed depending on working directory state). Return 0 to proceed + * with updating the item, > 0 to skip the item, and < 0 to abort the scan. + * + * @param index An existing index object + * @param pathspec array of path patterns + * @param callback notification callback for each updated path (also + * gets index of matching pathspec entry); can be NULL; + * return 0 to add, >0 to skip, <0 to abort scan. + * @param payload payload passed through to callback function + * @return 0 on success, negative callback return value, or error code + */ +GIT_EXTERN(int) git_index_update_all( + git_index *index, + const git_strarray *pathspec, + git_index_matched_path_cb callback, + void *payload); + +/** + * Find the first position of any entries which point to given + * path in the Git index. + * + * @param at_pos the address to which the position of the index entry is written (optional) + * @param index an existing index object + * @param path path to search + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_find(size_t *at_pos, git_index *index, const char *path); + +/** + * Find the first position of any entries matching a prefix. To find the first position + * of a path inside a given folder, suffix the prefix with a '/'. + * + * @param at_pos the address to which the position of the index entry is written (optional) + * @param index an existing index object + * @param prefix the prefix to search for + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_find_prefix(size_t *at_pos, git_index *index, const char *prefix); + +/**@}*/ + +/** @name Conflict Index Entry Functions + * + * These functions work on conflict index entries specifically (ie, stages 1-3) + */ +/**@{*/ + +/** + * Add or update index entries to represent a conflict. Any staged + * entries that exist at the given paths will be removed. + * + * The entries are the entries from the tree included in the merge. Any + * entry may be null to indicate that that file was not present in the + * trees during the merge. For example, ancestor_entry may be NULL to + * indicate that a file was added in both branches and must be resolved. + * + * @param index an existing index object + * @param ancestor_entry the entry data for the ancestor of the conflict + * @param our_entry the entry data for our side of the merge conflict + * @param their_entry the entry data for their side of the merge conflict + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_conflict_add( + git_index *index, + const git_index_entry *ancestor_entry, + const git_index_entry *our_entry, + const git_index_entry *their_entry); + +/** + * Get the index entries that represent a conflict of a single file. + * + * The entries are not modifiable and should not be freed. Because the + * `git_index_entry` struct is a publicly defined struct, you should + * be able to make your own permanent copy of the data if necessary. + * + * @param ancestor_out Pointer to store the ancestor entry + * @param our_out Pointer to store the our entry + * @param their_out Pointer to store the their entry + * @param index an existing index object + * @param path path to search + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_conflict_get( + const git_index_entry **ancestor_out, + const git_index_entry **our_out, + const git_index_entry **their_out, + git_index *index, + const char *path); + +/** + * Removes the index entries that represent a conflict of a single file. + * + * @param index an existing index object + * @param path path to remove conflicts for + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_conflict_remove(git_index *index, const char *path); + +/** + * Remove all conflicts in the index (entries with a stage greater than 0). + * + * @param index an existing index object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_conflict_cleanup(git_index *index); + +/** + * Determine if the index contains entries representing file conflicts. + * + * @param index An existing index object. + * @return 1 if at least one conflict is found, 0 otherwise. + */ +GIT_EXTERN(int) git_index_has_conflicts(const git_index *index); + +/** + * Create an iterator for the conflicts in the index. + * + * The index must not be modified while iterating; the results are undefined. + * + * @param iterator_out The newly created conflict iterator + * @param index The index to scan + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_conflict_iterator_new( + git_index_conflict_iterator **iterator_out, + git_index *index); + +/** + * Returns the current conflict (ancestor, ours and theirs entry) and + * advance the iterator internally to the next value. + * + * @param ancestor_out Pointer to store the ancestor side of the conflict + * @param our_out Pointer to store our side of the conflict + * @param their_out Pointer to store their side of the conflict + * @param iterator The conflict iterator. + * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code + * (negative value) + */ +GIT_EXTERN(int) git_index_conflict_next( + const git_index_entry **ancestor_out, + const git_index_entry **our_out, + const git_index_entry **their_out, + git_index_conflict_iterator *iterator); + +/** + * Frees a `git_index_conflict_iterator`. + * + * @param iterator pointer to the iterator + */ +GIT_EXTERN(void) git_index_conflict_iterator_free( + git_index_conflict_iterator *iterator); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/indexer.h b/3rdparty/libgit2/include/git2/indexer.h index 630eef9..9d4eede 100644 --- a/3rdparty/libgit2/include/git2/indexer.h +++ b/3rdparty/libgit2/include/git2/indexer.h @@ -1,195 +1,195 @@ -/* - * 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_indexer_h__ -#define _INCLUDE_git_indexer_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" - -GIT_BEGIN_DECL - -/** A git indexer object */ -typedef struct git_indexer git_indexer; - -/** - * This structure is used to provide callers information about the - * progress of indexing a packfile, either directly or part of a - * fetch or clone that downloads a packfile. - */ -typedef struct git_indexer_progress { - /** number of objects in the packfile being indexed */ - unsigned int total_objects; - - /** received objects that have been hashed */ - unsigned int indexed_objects; - - /** received_objects: objects which have been downloaded */ - unsigned int received_objects; - - /** - * locally-available objects that have been injected in order - * to fix a thin pack - */ - unsigned int local_objects; - - /** number of deltas in the packfile being indexed */ - unsigned int total_deltas; - - /** received deltas that have been indexed */ - unsigned int indexed_deltas; - - /** size of the packfile received up to now */ - size_t received_bytes; -} git_indexer_progress; - -/** - * Type for progress callbacks during indexing. Return a value less - * than zero to cancel the indexing or download. - * - * @param stats Structure containing information about the state of the transfer - * @param payload Payload provided by caller - */ -typedef int GIT_CALLBACK(git_indexer_progress_cb)(const git_indexer_progress *stats, void *payload); - -/** - * Options for indexer configuration - */ -typedef struct git_indexer_options { - unsigned int version; - -#ifdef GIT_EXPERIMENTAL_SHA256 - /** permissions to use creating packfile or 0 for defaults */ - unsigned int mode; - - /** - * object database from which to read base objects when - * fixing thin packs. This can be NULL if there are no thin - * packs; if a thin pack is encountered, an error will be - * returned if there are bases missing. - */ - git_odb *odb; -#endif - - /** progress_cb function to call with progress information */ - git_indexer_progress_cb progress_cb; - - /** progress_cb_payload payload for the progress callback */ - void *progress_cb_payload; - - /** Do connectivity checks for the received pack */ - unsigned char verify; -} git_indexer_options; - -#define GIT_INDEXER_OPTIONS_VERSION 1 -#define GIT_INDEXER_OPTIONS_INIT { GIT_INDEXER_OPTIONS_VERSION } - -/** - * Initializes a `git_indexer_options` with default values. Equivalent to - * creating an instance with GIT_INDEXER_OPTIONS_INIT. - * - * @param opts the `git_indexer_options` struct to initialize. - * @param version Version of struct; pass `GIT_INDEXER_OPTIONS_VERSION` - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_indexer_options_init( - git_indexer_options *opts, - unsigned int version); - -#ifdef GIT_EXPERIMENTAL_SHA256 -/** - * Create a new indexer instance - * - * @param out where to store the indexer instance - * @param path to the directory where the packfile should be stored - * @param oid_type the oid type to use for objects - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_indexer_new( - git_indexer **out, - const char *path, - git_oid_t oid_type, - git_indexer_options *opts); -#else -/** - * Create a new indexer instance - * - * @param out where to store the indexer instance - * @param path to the directory where the packfile should be stored - * @param mode permissions to use creating packfile or 0 for defaults - * @param odb object database from which to read base objects when - * fixing thin packs. Pass NULL if no thin pack is expected (an error - * will be returned if there are bases missing) - * @param opts Optional structure containing additional options. See - * `git_indexer_options` above. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_indexer_new( - git_indexer **out, - const char *path, - unsigned int mode, - git_odb *odb, - git_indexer_options *opts); -#endif - -/** - * Add data to the indexer - * - * @param idx the indexer - * @param data the data to add - * @param size the size of the data in bytes - * @param stats stat storage - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_indexer_append(git_indexer *idx, const void *data, size_t size, git_indexer_progress *stats); - -/** - * Finalize the pack and index - * - * Resolve any pending deltas and write out the index file - * - * @param idx the indexer - * @param stats Stat storage. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_indexer_commit(git_indexer *idx, git_indexer_progress *stats); - -#ifndef GIT_DEPRECATE_HARD -/** - * Get the packfile's hash - * - * A packfile's name is derived from the sorted hashing of all object - * names. This is only correct after the index has been finalized. - * - * @deprecated use git_indexer_name - * @param idx the indexer instance - * @return the packfile's hash - */ -GIT_EXTERN(const git_oid *) git_indexer_hash(const git_indexer *idx); -#endif - -/** - * Get the unique name for the resulting packfile. - * - * The packfile's name is derived from the packfile's content. - * This is only correct after the index has been finalized. - * - * @param idx the indexer instance - * @return a NUL terminated string for the packfile name - */ -GIT_EXTERN(const char *) git_indexer_name(const git_indexer *idx); - -/** - * Free the indexer and its resources - * - * @param idx the indexer to free - */ -GIT_EXTERN(void) git_indexer_free(git_indexer *idx); - -GIT_END_DECL - -#endif +/* + * 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_indexer_h__ +#define _INCLUDE_git_indexer_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" + +GIT_BEGIN_DECL + +/** A git indexer object */ +typedef struct git_indexer git_indexer; + +/** + * This structure is used to provide callers information about the + * progress of indexing a packfile, either directly or part of a + * fetch or clone that downloads a packfile. + */ +typedef struct git_indexer_progress { + /** number of objects in the packfile being indexed */ + unsigned int total_objects; + + /** received objects that have been hashed */ + unsigned int indexed_objects; + + /** received_objects: objects which have been downloaded */ + unsigned int received_objects; + + /** + * locally-available objects that have been injected in order + * to fix a thin pack + */ + unsigned int local_objects; + + /** number of deltas in the packfile being indexed */ + unsigned int total_deltas; + + /** received deltas that have been indexed */ + unsigned int indexed_deltas; + + /** size of the packfile received up to now */ + size_t received_bytes; +} git_indexer_progress; + +/** + * Type for progress callbacks during indexing. Return a value less + * than zero to cancel the indexing or download. + * + * @param stats Structure containing information about the state of the transfer + * @param payload Payload provided by caller + */ +typedef int GIT_CALLBACK(git_indexer_progress_cb)(const git_indexer_progress *stats, void *payload); + +/** + * Options for indexer configuration + */ +typedef struct git_indexer_options { + unsigned int version; + +#ifdef GIT_EXPERIMENTAL_SHA256 + /** permissions to use creating packfile or 0 for defaults */ + unsigned int mode; + + /** + * object database from which to read base objects when + * fixing thin packs. This can be NULL if there are no thin + * packs; if a thin pack is encountered, an error will be + * returned if there are bases missing. + */ + git_odb *odb; +#endif + + /** progress_cb function to call with progress information */ + git_indexer_progress_cb progress_cb; + + /** progress_cb_payload payload for the progress callback */ + void *progress_cb_payload; + + /** Do connectivity checks for the received pack */ + unsigned char verify; +} git_indexer_options; + +#define GIT_INDEXER_OPTIONS_VERSION 1 +#define GIT_INDEXER_OPTIONS_INIT { GIT_INDEXER_OPTIONS_VERSION } + +/** + * Initializes a `git_indexer_options` with default values. Equivalent to + * creating an instance with GIT_INDEXER_OPTIONS_INIT. + * + * @param opts the `git_indexer_options` struct to initialize. + * @param version Version of struct; pass `GIT_INDEXER_OPTIONS_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_indexer_options_init( + git_indexer_options *opts, + unsigned int version); + +#ifdef GIT_EXPERIMENTAL_SHA256 +/** + * Create a new indexer instance + * + * @param out where to store the indexer instance + * @param path to the directory where the packfile should be stored + * @param oid_type the oid type to use for objects + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_indexer_new( + git_indexer **out, + const char *path, + git_oid_t oid_type, + git_indexer_options *opts); +#else +/** + * Create a new indexer instance + * + * @param out where to store the indexer instance + * @param path to the directory where the packfile should be stored + * @param mode permissions to use creating packfile or 0 for defaults + * @param odb object database from which to read base objects when + * fixing thin packs. Pass NULL if no thin pack is expected (an error + * will be returned if there are bases missing) + * @param opts Optional structure containing additional options. See + * `git_indexer_options` above. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_indexer_new( + git_indexer **out, + const char *path, + unsigned int mode, + git_odb *odb, + git_indexer_options *opts); +#endif + +/** + * Add data to the indexer + * + * @param idx the indexer + * @param data the data to add + * @param size the size of the data in bytes + * @param stats stat storage + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_indexer_append(git_indexer *idx, const void *data, size_t size, git_indexer_progress *stats); + +/** + * Finalize the pack and index + * + * Resolve any pending deltas and write out the index file + * + * @param idx the indexer + * @param stats Stat storage. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_indexer_commit(git_indexer *idx, git_indexer_progress *stats); + +#ifndef GIT_DEPRECATE_HARD +/** + * Get the packfile's hash + * + * A packfile's name is derived from the sorted hashing of all object + * names. This is only correct after the index has been finalized. + * + * @deprecated use git_indexer_name + * @param idx the indexer instance + * @return the packfile's hash + */ +GIT_EXTERN(const git_oid *) git_indexer_hash(const git_indexer *idx); +#endif + +/** + * Get the unique name for the resulting packfile. + * + * The packfile's name is derived from the packfile's content. + * This is only correct after the index has been finalized. + * + * @param idx the indexer instance + * @return a NUL terminated string for the packfile name + */ +GIT_EXTERN(const char *) git_indexer_name(const git_indexer *idx); + +/** + * Free the indexer and its resources + * + * @param idx the indexer to free + */ +GIT_EXTERN(void) git_indexer_free(git_indexer *idx); + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/mailmap.h b/3rdparty/libgit2/include/git2/mailmap.h index 7c3f60f..c7239e4 100644 --- a/3rdparty/libgit2/include/git2/mailmap.h +++ b/3rdparty/libgit2/include/git2/mailmap.h @@ -1,115 +1,115 @@ -/* - * 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_mailmap_h__ -#define INCLUDE_git_mailmap_h__ - -#include "common.h" -#include "types.h" -#include "buffer.h" - -/** - * @file git2/mailmap.h - * @brief Mailmap parsing routines - * @defgroup git_mailmap Git mailmap routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Allocate a new mailmap object. - * - * This object is empty, so you'll have to add a mailmap file before you can do - * anything with it. The mailmap must be freed with 'git_mailmap_free'. - * - * @param out pointer to store the new mailmap - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_mailmap_new(git_mailmap **out); - -/** - * Free the mailmap and its associated memory. - * - * @param mm the mailmap to free - */ -GIT_EXTERN(void) git_mailmap_free(git_mailmap *mm); - -/** - * Add a single entry to the given mailmap object. If the entry already exists, - * it will be replaced with the new entry. - * - * @param mm mailmap to add the entry to - * @param real_name the real name to use, or NULL - * @param real_email the real email to use, or NULL - * @param replace_name the name to replace, or NULL - * @param replace_email the email to replace - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_mailmap_add_entry( - git_mailmap *mm, const char *real_name, const char *real_email, - const char *replace_name, const char *replace_email); - -/** - * Create a new mailmap instance containing a single mailmap file - * - * @param out pointer to store the new mailmap - * @param buf buffer to parse the mailmap from - * @param len the length of the input buffer - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_mailmap_from_buffer( - git_mailmap **out, const char *buf, size_t len); - -/** - * Create a new mailmap instance from a repository, loading mailmap files based - * on the repository's configuration. - * - * Mailmaps are loaded in the following order: - * 1. '.mailmap' in the root of the repository's working directory, if present. - * 2. The blob object identified by the 'mailmap.blob' config entry, if set. - * [NOTE: 'mailmap.blob' defaults to 'HEAD:.mailmap' in bare repositories] - * 3. The path in the 'mailmap.file' config entry, if set. - * - * @param out pointer to store the new mailmap - * @param repo repository to load mailmap information from - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_mailmap_from_repository( - git_mailmap **out, git_repository *repo); - -/** - * Resolve a name and email to the corresponding real name and email. - * - * The lifetime of the strings are tied to `mm`, `name`, and `email` parameters. - * - * @param real_name pointer to store the real name - * @param real_email pointer to store the real email - * @param mm the mailmap to perform a lookup with (may be NULL) - * @param name the name to look up - * @param email the email to look up - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_mailmap_resolve( - const char **real_name, const char **real_email, - const git_mailmap *mm, const char *name, const char *email); - -/** - * Resolve a signature to use real names and emails with a mailmap. - * - * Call `git_signature_free()` to free the data. - * - * @param out new signature - * @param mm mailmap to resolve with - * @param sig signature to resolve - * @return 0 or an error code - */ -GIT_EXTERN(int) git_mailmap_resolve_signature( - git_signature **out, const git_mailmap *mm, const git_signature *sig); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_mailmap_h__ +#define INCLUDE_git_mailmap_h__ + +#include "common.h" +#include "types.h" +#include "buffer.h" + +/** + * @file git2/mailmap.h + * @brief Mailmap parsing routines + * @defgroup git_mailmap Git mailmap routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Allocate a new mailmap object. + * + * This object is empty, so you'll have to add a mailmap file before you can do + * anything with it. The mailmap must be freed with 'git_mailmap_free'. + * + * @param out pointer to store the new mailmap + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_mailmap_new(git_mailmap **out); + +/** + * Free the mailmap and its associated memory. + * + * @param mm the mailmap to free + */ +GIT_EXTERN(void) git_mailmap_free(git_mailmap *mm); + +/** + * Add a single entry to the given mailmap object. If the entry already exists, + * it will be replaced with the new entry. + * + * @param mm mailmap to add the entry to + * @param real_name the real name to use, or NULL + * @param real_email the real email to use, or NULL + * @param replace_name the name to replace, or NULL + * @param replace_email the email to replace + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_mailmap_add_entry( + git_mailmap *mm, const char *real_name, const char *real_email, + const char *replace_name, const char *replace_email); + +/** + * Create a new mailmap instance containing a single mailmap file + * + * @param out pointer to store the new mailmap + * @param buf buffer to parse the mailmap from + * @param len the length of the input buffer + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_mailmap_from_buffer( + git_mailmap **out, const char *buf, size_t len); + +/** + * Create a new mailmap instance from a repository, loading mailmap files based + * on the repository's configuration. + * + * Mailmaps are loaded in the following order: + * 1. '.mailmap' in the root of the repository's working directory, if present. + * 2. The blob object identified by the 'mailmap.blob' config entry, if set. + * [NOTE: 'mailmap.blob' defaults to 'HEAD:.mailmap' in bare repositories] + * 3. The path in the 'mailmap.file' config entry, if set. + * + * @param out pointer to store the new mailmap + * @param repo repository to load mailmap information from + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_mailmap_from_repository( + git_mailmap **out, git_repository *repo); + +/** + * Resolve a name and email to the corresponding real name and email. + * + * The lifetime of the strings are tied to `mm`, `name`, and `email` parameters. + * + * @param real_name pointer to store the real name + * @param real_email pointer to store the real email + * @param mm the mailmap to perform a lookup with (may be NULL) + * @param name the name to look up + * @param email the email to look up + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_mailmap_resolve( + const char **real_name, const char **real_email, + const git_mailmap *mm, const char *name, const char *email); + +/** + * Resolve a signature to use real names and emails with a mailmap. + * + * Call `git_signature_free()` to free the data. + * + * @param out new signature + * @param mm mailmap to resolve with + * @param sig signature to resolve + * @return 0 or an error code + */ +GIT_EXTERN(int) git_mailmap_resolve_signature( + git_signature **out, const git_mailmap *mm, const git_signature *sig); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/merge.h b/3rdparty/libgit2/include/git2/merge.h index fcce559..b1a852f 100644 --- a/3rdparty/libgit2/include/git2/merge.h +++ b/3rdparty/libgit2/include/git2/merge.h @@ -1,626 +1,626 @@ -/* - * 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_merge_h__ -#define INCLUDE_git_merge_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "oidarray.h" -#include "checkout.h" -#include "index.h" -#include "annotated_commit.h" - -/** - * @file git2/merge.h - * @brief Git merge routines - * @defgroup git_merge Git merge routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * The file inputs to `git_merge_file`. Callers should populate the - * `git_merge_file_input` structure with descriptions of the files in - * each side of the conflict for use in producing the merge file. - */ -typedef struct { - unsigned int version; - - /** Pointer to the contents of the file. */ - const char *ptr; - - /** Size of the contents pointed to in `ptr`. */ - size_t size; - - /** File name of the conflicted file, or `NULL` to not merge the path. */ - const char *path; - - /** File mode of the conflicted file, or `0` to not merge the mode. */ - unsigned int mode; -} git_merge_file_input; - -#define GIT_MERGE_FILE_INPUT_VERSION 1 -#define GIT_MERGE_FILE_INPUT_INIT {GIT_MERGE_FILE_INPUT_VERSION} - -/** - * Initializes a `git_merge_file_input` with default values. Equivalent to - * creating an instance with GIT_MERGE_FILE_INPUT_INIT. - * - * @param opts the `git_merge_file_input` instance to initialize. - * @param version the version of the struct; you should pass - * `GIT_MERGE_FILE_INPUT_VERSION` here. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_merge_file_input_init( - git_merge_file_input *opts, - unsigned int version); - -/** - * Flags for `git_merge` options. A combination of these flags can be - * passed in via the `flags` value in the `git_merge_options`. - */ -typedef enum { - /** - * Detect renames that occur between the common ancestor and the "ours" - * side or the common ancestor and the "theirs" side. This will enable - * the ability to merge between a modified and renamed file. - */ - GIT_MERGE_FIND_RENAMES = (1 << 0), - - /** - * If a conflict occurs, exit immediately instead of attempting to - * continue resolving conflicts. The merge operation will fail with - * GIT_EMERGECONFLICT and no index will be returned. - */ - GIT_MERGE_FAIL_ON_CONFLICT = (1 << 1), - - /** - * Do not write the REUC extension on the generated index - */ - GIT_MERGE_SKIP_REUC = (1 << 2), - - /** - * If the commits being merged have multiple merge bases, do not build - * a recursive merge base (by merging the multiple merge bases), - * instead simply use the first base. This flag provides a similar - * merge base to `git-merge-resolve`. - */ - GIT_MERGE_NO_RECURSIVE = (1 << 3), - - /** - * Treat this merge as if it is to produce the virtual base - * of a recursive merge. This will ensure that there are - * no conflicts, any conflicting regions will keep conflict - * markers in the merge result. - */ - GIT_MERGE_VIRTUAL_BASE = (1 << 4) -} git_merge_flag_t; - -/** - * Merge file favor options for `git_merge_options` instruct the file-level - * merging functionality how to deal with conflicting regions of the files. - */ -typedef enum { - /** - * When a region of a file is changed in both branches, a conflict - * will be recorded in the index so that `git_checkout` can produce - * a merge file with conflict markers in the working directory. - * This is the default. - */ - GIT_MERGE_FILE_FAVOR_NORMAL = 0, - - /** - * When a region of a file is changed in both branches, the file - * created in the index will contain the "ours" side of any conflicting - * region. The index will not record a conflict. - */ - GIT_MERGE_FILE_FAVOR_OURS = 1, - - /** - * When a region of a file is changed in both branches, the file - * created in the index will contain the "theirs" side of any conflicting - * region. The index will not record a conflict. - */ - GIT_MERGE_FILE_FAVOR_THEIRS = 2, - - /** - * When a region of a file is changed in both branches, the file - * created in the index will contain each unique line from each side, - * which has the result of combining both files. The index will not - * record a conflict. - */ - GIT_MERGE_FILE_FAVOR_UNION = 3 -} git_merge_file_favor_t; - -/** - * File merging flags - */ -typedef enum { - /** Defaults */ - GIT_MERGE_FILE_DEFAULT = 0, - - /** Create standard conflicted merge files */ - GIT_MERGE_FILE_STYLE_MERGE = (1 << 0), - - /** Create diff3-style files */ - GIT_MERGE_FILE_STYLE_DIFF3 = (1 << 1), - - /** Condense non-alphanumeric regions for simplified diff file */ - GIT_MERGE_FILE_SIMPLIFY_ALNUM = (1 << 2), - - /** Ignore all whitespace */ - GIT_MERGE_FILE_IGNORE_WHITESPACE = (1 << 3), - - /** Ignore changes in amount of whitespace */ - GIT_MERGE_FILE_IGNORE_WHITESPACE_CHANGE = (1 << 4), - - /** Ignore whitespace at end of line */ - GIT_MERGE_FILE_IGNORE_WHITESPACE_EOL = (1 << 5), - - /** Use the "patience diff" algorithm */ - GIT_MERGE_FILE_DIFF_PATIENCE = (1 << 6), - - /** Take extra time to find minimal diff */ - GIT_MERGE_FILE_DIFF_MINIMAL = (1 << 7), - - /** Create zdiff3 ("zealous diff3")-style files */ - GIT_MERGE_FILE_STYLE_ZDIFF3 = (1 << 8), - - /** - * Do not produce file conflicts when common regions have - * changed; keep the conflict markers in the file and accept - * that as the merge result. - */ - GIT_MERGE_FILE_ACCEPT_CONFLICTS = (1 << 9) -} git_merge_file_flag_t; - -#define GIT_MERGE_CONFLICT_MARKER_SIZE 7 - -/** - * Options for merging a file - */ -typedef struct { - unsigned int version; - - /** - * Label for the ancestor file side of the conflict which will be prepended - * to labels in diff3-format merge files. - */ - const char *ancestor_label; - - /** - * Label for our file side of the conflict which will be prepended - * to labels in merge files. - */ - const char *our_label; - - /** - * Label for their file side of the conflict which will be prepended - * to labels in merge files. - */ - const char *their_label; - - /** The file to favor in region conflicts. */ - git_merge_file_favor_t favor; - - /** see `git_merge_file_flag_t` above */ - uint32_t flags; - - /** The size of conflict markers (eg, "<<<<<<<"). Default is - * GIT_MERGE_CONFLICT_MARKER_SIZE. */ - unsigned short marker_size; -} git_merge_file_options; - -#define GIT_MERGE_FILE_OPTIONS_VERSION 1 -#define GIT_MERGE_FILE_OPTIONS_INIT {GIT_MERGE_FILE_OPTIONS_VERSION} - -/** - * Initialize git_merge_file_options structure - * - * Initializes a `git_merge_file_options` with default values. Equivalent to - * creating an instance with `GIT_MERGE_FILE_OPTIONS_INIT`. - * - * @param opts The `git_merge_file_options` struct to initialize. - * @param version The struct version; pass `GIT_MERGE_FILE_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_merge_file_options_init(git_merge_file_options *opts, unsigned int version); - -/** - * Information about file-level merging - */ -typedef struct { - /** - * True if the output was automerged, false if the output contains - * conflict markers. - */ - unsigned int automergeable; - - /** - * The path that the resultant merge file should use, or NULL if a - * filename conflict would occur. - */ - const char *path; - - /** The mode that the resultant merge file should use. */ - unsigned int mode; - - /** The contents of the merge. */ - const char *ptr; - - /** The length of the merge contents. */ - size_t len; -} git_merge_file_result; - -/** - * Merging options - */ -typedef struct { - unsigned int version; - - /** See `git_merge_flag_t` above */ - uint32_t flags; - - /** - * Similarity to consider a file renamed (default 50). If - * `GIT_MERGE_FIND_RENAMES` is enabled, added files will be compared - * with deleted files to determine their similarity. Files that are - * more similar than the rename threshold (percentage-wise) will be - * treated as a rename. - */ - unsigned int rename_threshold; - - /** - * Maximum similarity sources to examine for renames (default 200). - * If the number of rename candidates (add / delete pairs) is greater - * than this value, inexact rename detection is aborted. - * - * This setting overrides the `merge.renameLimit` configuration value. - */ - unsigned int target_limit; - - /** Pluggable similarity metric; pass NULL to use internal metric */ - git_diff_similarity_metric *metric; - - /** - * Maximum number of times to merge common ancestors to build a - * virtual merge base when faced with criss-cross merges. When this - * limit is reached, the next ancestor will simply be used instead of - * attempting to merge it. The default is unlimited. - */ - unsigned int recursion_limit; - - /** - * Default merge driver to be used when both sides of a merge have - * changed. The default is the `text` driver. - */ - const char *default_driver; - - /** - * Flags for handling conflicting content, to be used with the standard - * (`text`) merge driver. - */ - git_merge_file_favor_t file_favor; - - /** see `git_merge_file_flag_t` above */ - uint32_t file_flags; -} git_merge_options; - -#define GIT_MERGE_OPTIONS_VERSION 1 -#define GIT_MERGE_OPTIONS_INIT { \ - GIT_MERGE_OPTIONS_VERSION, GIT_MERGE_FIND_RENAMES } - -/** - * Initialize git_merge_options structure - * - * Initializes a `git_merge_options` with default values. Equivalent to - * creating an instance with `GIT_MERGE_OPTIONS_INIT`. - * - * @param opts The `git_merge_options` struct to initialize. - * @param version The struct version; pass `GIT_MERGE_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_merge_options_init(git_merge_options *opts, unsigned int version); - -/** - * The results of `git_merge_analysis` indicate the merge opportunities. - */ -typedef enum { - /** No merge is possible. (Unused.) */ - GIT_MERGE_ANALYSIS_NONE = 0, - - /** - * A "normal" merge; both HEAD and the given merge input have diverged - * from their common ancestor. The divergent commits must be merged. - */ - GIT_MERGE_ANALYSIS_NORMAL = (1 << 0), - - /** - * All given merge inputs are reachable from HEAD, meaning the - * repository is up-to-date and no merge needs to be performed. - */ - GIT_MERGE_ANALYSIS_UP_TO_DATE = (1 << 1), - - /** - * The given merge input is a fast-forward from HEAD and no merge - * needs to be performed. Instead, the client can check out the - * given merge input. - */ - GIT_MERGE_ANALYSIS_FASTFORWARD = (1 << 2), - - /** - * The HEAD of the current repository is "unborn" and does not point to - * a valid commit. No merge can be performed, but the caller may wish - * to simply set HEAD to the target commit(s). - */ - GIT_MERGE_ANALYSIS_UNBORN = (1 << 3) -} git_merge_analysis_t; - -/** - * The user's stated preference for merges. - */ -typedef enum { - /** - * No configuration was found that suggests a preferred behavior for - * merge. - */ - GIT_MERGE_PREFERENCE_NONE = 0, - - /** - * There is a `merge.ff=false` configuration setting, suggesting that - * the user does not want to allow a fast-forward merge. - */ - GIT_MERGE_PREFERENCE_NO_FASTFORWARD = (1 << 0), - - /** - * There is a `merge.ff=only` configuration setting, suggesting that - * the user only wants fast-forward merges. - */ - GIT_MERGE_PREFERENCE_FASTFORWARD_ONLY = (1 << 1) -} git_merge_preference_t; - -/** - * Analyzes the given branch(es) and determines the opportunities for - * merging them into the HEAD of the repository. - * - * @param analysis_out analysis enumeration that the result is written into - * @param preference_out One of the `git_merge_preference_t` flag. - * @param repo the repository to merge - * @param their_heads the heads to merge into - * @param their_heads_len the number of heads to merge - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_merge_analysis( - git_merge_analysis_t *analysis_out, - git_merge_preference_t *preference_out, - git_repository *repo, - const git_annotated_commit **their_heads, - size_t their_heads_len); - -/** - * Analyzes the given branch(es) and determines the opportunities for - * merging them into a reference. - * - * @param analysis_out analysis enumeration that the result is written into - * @param preference_out One of the `git_merge_preference_t` flag. - * @param repo the repository to merge - * @param our_ref the reference to perform the analysis from - * @param their_heads the heads to merge into - * @param their_heads_len the number of heads to merge - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_merge_analysis_for_ref( - git_merge_analysis_t *analysis_out, - git_merge_preference_t *preference_out, - git_repository *repo, - git_reference *our_ref, - const git_annotated_commit **their_heads, - size_t their_heads_len); - -/** - * Find a merge base between two commits - * - * @param out the OID of a merge base between 'one' and 'two' - * @param repo the repository where the commits exist - * @param one one of the commits - * @param two the other commit - * @return 0 on success, GIT_ENOTFOUND if not found or error code - */ -GIT_EXTERN(int) git_merge_base( - git_oid *out, - git_repository *repo, - const git_oid *one, - const git_oid *two); - -/** - * Find merge bases between two commits - * - * @param out array in which to store the resulting ids - * @param repo the repository where the commits exist - * @param one one of the commits - * @param two the other commit - * @return 0 on success, GIT_ENOTFOUND if not found or error code - */ -GIT_EXTERN(int) git_merge_bases( - git_oidarray *out, - git_repository *repo, - const git_oid *one, - const git_oid *two); - -/** - * Find a merge base given a list of commits - * - * @param out the OID of a merge base considering all the commits - * @param repo the repository where the commits exist - * @param length The number of commits in the provided `input_array` - * @param input_array oids of the commits - * @return Zero on success; GIT_ENOTFOUND or -1 on failure. - */ -GIT_EXTERN(int) git_merge_base_many( - git_oid *out, - git_repository *repo, - size_t length, - const git_oid input_array[]); - -/** - * Find all merge bases given a list of commits - * - * @param out array in which to store the resulting ids - * @param repo the repository where the commits exist - * @param length The number of commits in the provided `input_array` - * @param input_array oids of the commits - * @return Zero on success; GIT_ENOTFOUND or -1 on failure. - */ -GIT_EXTERN(int) git_merge_bases_many( - git_oidarray *out, - git_repository *repo, - size_t length, - const git_oid input_array[]); - -/** - * Find a merge base in preparation for an octopus merge - * - * @param out the OID of a merge base considering all the commits - * @param repo the repository where the commits exist - * @param length The number of commits in the provided `input_array` - * @param input_array oids of the commits - * @return Zero on success; GIT_ENOTFOUND or -1 on failure. - */ -GIT_EXTERN(int) git_merge_base_octopus( - git_oid *out, - git_repository *repo, - size_t length, - const git_oid input_array[]); - -/** - * Merge two files as they exist in the in-memory data structures, using - * the given common ancestor as the baseline, producing a - * `git_merge_file_result` that reflects the merge result. The - * `git_merge_file_result` must be freed with `git_merge_file_result_free`. - * - * Note that this function does not reference a repository and any - * configuration must be passed as `git_merge_file_options`. - * - * @param out The git_merge_file_result to be filled in - * @param ancestor The contents of the ancestor file - * @param ours The contents of the file in "our" side - * @param theirs The contents of the file in "their" side - * @param opts The merge file options or `NULL` for defaults - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_merge_file( - git_merge_file_result *out, - const git_merge_file_input *ancestor, - const git_merge_file_input *ours, - const git_merge_file_input *theirs, - const git_merge_file_options *opts); - -/** - * Merge two files as they exist in the index, using the given common - * ancestor as the baseline, producing a `git_merge_file_result` that - * reflects the merge result. The `git_merge_file_result` must be freed with - * `git_merge_file_result_free`. - * - * @param out The git_merge_file_result to be filled in - * @param repo The repository - * @param ancestor The index entry for the ancestor file (stage level 1) - * @param ours The index entry for our file (stage level 2) - * @param theirs The index entry for their file (stage level 3) - * @param opts The merge file options or NULL - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_merge_file_from_index( - git_merge_file_result *out, - git_repository *repo, - const git_index_entry *ancestor, - const git_index_entry *ours, - const git_index_entry *theirs, - const git_merge_file_options *opts); - -/** - * Frees a `git_merge_file_result`. - * - * @param result The result to free or `NULL` - */ -GIT_EXTERN(void) git_merge_file_result_free(git_merge_file_result *result); - -/** - * Merge two trees, producing a `git_index` that reflects the result of - * the merge. The index may be written as-is to the working directory - * or checked out. If the index is to be converted to a tree, the caller - * should resolve any conflicts that arose as part of the merge. - * - * The returned index must be freed explicitly with `git_index_free`. - * - * @param out pointer to store the index result in - * @param repo repository that contains the given trees - * @param ancestor_tree the common ancestor between the trees (or null if none) - * @param our_tree the tree that reflects the destination tree - * @param their_tree the tree to merge in to `our_tree` - * @param opts the merge tree options (or null for defaults) - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_merge_trees( - git_index **out, - git_repository *repo, - const git_tree *ancestor_tree, - const git_tree *our_tree, - const git_tree *their_tree, - const git_merge_options *opts); - -/** - * Merge two commits, producing a `git_index` that reflects the result of - * the merge. The index may be written as-is to the working directory - * or checked out. If the index is to be converted to a tree, the caller - * should resolve any conflicts that arose as part of the merge. - * - * The returned index must be freed explicitly with `git_index_free`. - * - * @param out pointer to store the index result in - * @param repo repository that contains the given trees - * @param our_commit the commit that reflects the destination tree - * @param their_commit the commit to merge in to `our_commit` - * @param opts the merge tree options (or null for defaults) - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_merge_commits( - git_index **out, - git_repository *repo, - const git_commit *our_commit, - const git_commit *their_commit, - const git_merge_options *opts); - -/** - * Merges the given commit(s) into HEAD, writing the results into the working - * directory. Any changes are staged for commit and any conflicts are written - * to the index. Callers should inspect the repository's index after this - * completes, resolve any conflicts and prepare a commit. - * - * For compatibility with git, the repository is put into a merging - * state. Once the commit is done (or if the user wishes to abort), - * you should clear this state by calling - * `git_repository_state_cleanup()`. - * - * @param repo the repository to merge - * @param their_heads the heads to merge into - * @param their_heads_len the number of heads to merge - * @param merge_opts merge options - * @param checkout_opts checkout options - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_merge( - git_repository *repo, - const git_annotated_commit **their_heads, - size_t their_heads_len, - const git_merge_options *merge_opts, - const git_checkout_options *checkout_opts); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_merge_h__ +#define INCLUDE_git_merge_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "oidarray.h" +#include "checkout.h" +#include "index.h" +#include "annotated_commit.h" + +/** + * @file git2/merge.h + * @brief Git merge routines + * @defgroup git_merge Git merge routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * The file inputs to `git_merge_file`. Callers should populate the + * `git_merge_file_input` structure with descriptions of the files in + * each side of the conflict for use in producing the merge file. + */ +typedef struct { + unsigned int version; + + /** Pointer to the contents of the file. */ + const char *ptr; + + /** Size of the contents pointed to in `ptr`. */ + size_t size; + + /** File name of the conflicted file, or `NULL` to not merge the path. */ + const char *path; + + /** File mode of the conflicted file, or `0` to not merge the mode. */ + unsigned int mode; +} git_merge_file_input; + +#define GIT_MERGE_FILE_INPUT_VERSION 1 +#define GIT_MERGE_FILE_INPUT_INIT {GIT_MERGE_FILE_INPUT_VERSION} + +/** + * Initializes a `git_merge_file_input` with default values. Equivalent to + * creating an instance with GIT_MERGE_FILE_INPUT_INIT. + * + * @param opts the `git_merge_file_input` instance to initialize. + * @param version the version of the struct; you should pass + * `GIT_MERGE_FILE_INPUT_VERSION` here. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_merge_file_input_init( + git_merge_file_input *opts, + unsigned int version); + +/** + * Flags for `git_merge` options. A combination of these flags can be + * passed in via the `flags` value in the `git_merge_options`. + */ +typedef enum { + /** + * Detect renames that occur between the common ancestor and the "ours" + * side or the common ancestor and the "theirs" side. This will enable + * the ability to merge between a modified and renamed file. + */ + GIT_MERGE_FIND_RENAMES = (1 << 0), + + /** + * If a conflict occurs, exit immediately instead of attempting to + * continue resolving conflicts. The merge operation will fail with + * GIT_EMERGECONFLICT and no index will be returned. + */ + GIT_MERGE_FAIL_ON_CONFLICT = (1 << 1), + + /** + * Do not write the REUC extension on the generated index + */ + GIT_MERGE_SKIP_REUC = (1 << 2), + + /** + * If the commits being merged have multiple merge bases, do not build + * a recursive merge base (by merging the multiple merge bases), + * instead simply use the first base. This flag provides a similar + * merge base to `git-merge-resolve`. + */ + GIT_MERGE_NO_RECURSIVE = (1 << 3), + + /** + * Treat this merge as if it is to produce the virtual base + * of a recursive merge. This will ensure that there are + * no conflicts, any conflicting regions will keep conflict + * markers in the merge result. + */ + GIT_MERGE_VIRTUAL_BASE = (1 << 4) +} git_merge_flag_t; + +/** + * Merge file favor options for `git_merge_options` instruct the file-level + * merging functionality how to deal with conflicting regions of the files. + */ +typedef enum { + /** + * When a region of a file is changed in both branches, a conflict + * will be recorded in the index so that `git_checkout` can produce + * a merge file with conflict markers in the working directory. + * This is the default. + */ + GIT_MERGE_FILE_FAVOR_NORMAL = 0, + + /** + * When a region of a file is changed in both branches, the file + * created in the index will contain the "ours" side of any conflicting + * region. The index will not record a conflict. + */ + GIT_MERGE_FILE_FAVOR_OURS = 1, + + /** + * When a region of a file is changed in both branches, the file + * created in the index will contain the "theirs" side of any conflicting + * region. The index will not record a conflict. + */ + GIT_MERGE_FILE_FAVOR_THEIRS = 2, + + /** + * When a region of a file is changed in both branches, the file + * created in the index will contain each unique line from each side, + * which has the result of combining both files. The index will not + * record a conflict. + */ + GIT_MERGE_FILE_FAVOR_UNION = 3 +} git_merge_file_favor_t; + +/** + * File merging flags + */ +typedef enum { + /** Defaults */ + GIT_MERGE_FILE_DEFAULT = 0, + + /** Create standard conflicted merge files */ + GIT_MERGE_FILE_STYLE_MERGE = (1 << 0), + + /** Create diff3-style files */ + GIT_MERGE_FILE_STYLE_DIFF3 = (1 << 1), + + /** Condense non-alphanumeric regions for simplified diff file */ + GIT_MERGE_FILE_SIMPLIFY_ALNUM = (1 << 2), + + /** Ignore all whitespace */ + GIT_MERGE_FILE_IGNORE_WHITESPACE = (1 << 3), + + /** Ignore changes in amount of whitespace */ + GIT_MERGE_FILE_IGNORE_WHITESPACE_CHANGE = (1 << 4), + + /** Ignore whitespace at end of line */ + GIT_MERGE_FILE_IGNORE_WHITESPACE_EOL = (1 << 5), + + /** Use the "patience diff" algorithm */ + GIT_MERGE_FILE_DIFF_PATIENCE = (1 << 6), + + /** Take extra time to find minimal diff */ + GIT_MERGE_FILE_DIFF_MINIMAL = (1 << 7), + + /** Create zdiff3 ("zealous diff3")-style files */ + GIT_MERGE_FILE_STYLE_ZDIFF3 = (1 << 8), + + /** + * Do not produce file conflicts when common regions have + * changed; keep the conflict markers in the file and accept + * that as the merge result. + */ + GIT_MERGE_FILE_ACCEPT_CONFLICTS = (1 << 9) +} git_merge_file_flag_t; + +#define GIT_MERGE_CONFLICT_MARKER_SIZE 7 + +/** + * Options for merging a file + */ +typedef struct { + unsigned int version; + + /** + * Label for the ancestor file side of the conflict which will be prepended + * to labels in diff3-format merge files. + */ + const char *ancestor_label; + + /** + * Label for our file side of the conflict which will be prepended + * to labels in merge files. + */ + const char *our_label; + + /** + * Label for their file side of the conflict which will be prepended + * to labels in merge files. + */ + const char *their_label; + + /** The file to favor in region conflicts. */ + git_merge_file_favor_t favor; + + /** see `git_merge_file_flag_t` above */ + uint32_t flags; + + /** The size of conflict markers (eg, "<<<<<<<"). Default is + * GIT_MERGE_CONFLICT_MARKER_SIZE. */ + unsigned short marker_size; +} git_merge_file_options; + +#define GIT_MERGE_FILE_OPTIONS_VERSION 1 +#define GIT_MERGE_FILE_OPTIONS_INIT {GIT_MERGE_FILE_OPTIONS_VERSION} + +/** + * Initialize git_merge_file_options structure + * + * Initializes a `git_merge_file_options` with default values. Equivalent to + * creating an instance with `GIT_MERGE_FILE_OPTIONS_INIT`. + * + * @param opts The `git_merge_file_options` struct to initialize. + * @param version The struct version; pass `GIT_MERGE_FILE_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_merge_file_options_init(git_merge_file_options *opts, unsigned int version); + +/** + * Information about file-level merging + */ +typedef struct { + /** + * True if the output was automerged, false if the output contains + * conflict markers. + */ + unsigned int automergeable; + + /** + * The path that the resultant merge file should use, or NULL if a + * filename conflict would occur. + */ + const char *path; + + /** The mode that the resultant merge file should use. */ + unsigned int mode; + + /** The contents of the merge. */ + const char *ptr; + + /** The length of the merge contents. */ + size_t len; +} git_merge_file_result; + +/** + * Merging options + */ +typedef struct { + unsigned int version; + + /** See `git_merge_flag_t` above */ + uint32_t flags; + + /** + * Similarity to consider a file renamed (default 50). If + * `GIT_MERGE_FIND_RENAMES` is enabled, added files will be compared + * with deleted files to determine their similarity. Files that are + * more similar than the rename threshold (percentage-wise) will be + * treated as a rename. + */ + unsigned int rename_threshold; + + /** + * Maximum similarity sources to examine for renames (default 200). + * If the number of rename candidates (add / delete pairs) is greater + * than this value, inexact rename detection is aborted. + * + * This setting overrides the `merge.renameLimit` configuration value. + */ + unsigned int target_limit; + + /** Pluggable similarity metric; pass NULL to use internal metric */ + git_diff_similarity_metric *metric; + + /** + * Maximum number of times to merge common ancestors to build a + * virtual merge base when faced with criss-cross merges. When this + * limit is reached, the next ancestor will simply be used instead of + * attempting to merge it. The default is unlimited. + */ + unsigned int recursion_limit; + + /** + * Default merge driver to be used when both sides of a merge have + * changed. The default is the `text` driver. + */ + const char *default_driver; + + /** + * Flags for handling conflicting content, to be used with the standard + * (`text`) merge driver. + */ + git_merge_file_favor_t file_favor; + + /** see `git_merge_file_flag_t` above */ + uint32_t file_flags; +} git_merge_options; + +#define GIT_MERGE_OPTIONS_VERSION 1 +#define GIT_MERGE_OPTIONS_INIT { \ + GIT_MERGE_OPTIONS_VERSION, GIT_MERGE_FIND_RENAMES } + +/** + * Initialize git_merge_options structure + * + * Initializes a `git_merge_options` with default values. Equivalent to + * creating an instance with `GIT_MERGE_OPTIONS_INIT`. + * + * @param opts The `git_merge_options` struct to initialize. + * @param version The struct version; pass `GIT_MERGE_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_merge_options_init(git_merge_options *opts, unsigned int version); + +/** + * The results of `git_merge_analysis` indicate the merge opportunities. + */ +typedef enum { + /** No merge is possible. (Unused.) */ + GIT_MERGE_ANALYSIS_NONE = 0, + + /** + * A "normal" merge; both HEAD and the given merge input have diverged + * from their common ancestor. The divergent commits must be merged. + */ + GIT_MERGE_ANALYSIS_NORMAL = (1 << 0), + + /** + * All given merge inputs are reachable from HEAD, meaning the + * repository is up-to-date and no merge needs to be performed. + */ + GIT_MERGE_ANALYSIS_UP_TO_DATE = (1 << 1), + + /** + * The given merge input is a fast-forward from HEAD and no merge + * needs to be performed. Instead, the client can check out the + * given merge input. + */ + GIT_MERGE_ANALYSIS_FASTFORWARD = (1 << 2), + + /** + * The HEAD of the current repository is "unborn" and does not point to + * a valid commit. No merge can be performed, but the caller may wish + * to simply set HEAD to the target commit(s). + */ + GIT_MERGE_ANALYSIS_UNBORN = (1 << 3) +} git_merge_analysis_t; + +/** + * The user's stated preference for merges. + */ +typedef enum { + /** + * No configuration was found that suggests a preferred behavior for + * merge. + */ + GIT_MERGE_PREFERENCE_NONE = 0, + + /** + * There is a `merge.ff=false` configuration setting, suggesting that + * the user does not want to allow a fast-forward merge. + */ + GIT_MERGE_PREFERENCE_NO_FASTFORWARD = (1 << 0), + + /** + * There is a `merge.ff=only` configuration setting, suggesting that + * the user only wants fast-forward merges. + */ + GIT_MERGE_PREFERENCE_FASTFORWARD_ONLY = (1 << 1) +} git_merge_preference_t; + +/** + * Analyzes the given branch(es) and determines the opportunities for + * merging them into the HEAD of the repository. + * + * @param analysis_out analysis enumeration that the result is written into + * @param preference_out One of the `git_merge_preference_t` flag. + * @param repo the repository to merge + * @param their_heads the heads to merge into + * @param their_heads_len the number of heads to merge + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_merge_analysis( + git_merge_analysis_t *analysis_out, + git_merge_preference_t *preference_out, + git_repository *repo, + const git_annotated_commit **their_heads, + size_t their_heads_len); + +/** + * Analyzes the given branch(es) and determines the opportunities for + * merging them into a reference. + * + * @param analysis_out analysis enumeration that the result is written into + * @param preference_out One of the `git_merge_preference_t` flag. + * @param repo the repository to merge + * @param our_ref the reference to perform the analysis from + * @param their_heads the heads to merge into + * @param their_heads_len the number of heads to merge + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_merge_analysis_for_ref( + git_merge_analysis_t *analysis_out, + git_merge_preference_t *preference_out, + git_repository *repo, + git_reference *our_ref, + const git_annotated_commit **their_heads, + size_t their_heads_len); + +/** + * Find a merge base between two commits + * + * @param out the OID of a merge base between 'one' and 'two' + * @param repo the repository where the commits exist + * @param one one of the commits + * @param two the other commit + * @return 0 on success, GIT_ENOTFOUND if not found or error code + */ +GIT_EXTERN(int) git_merge_base( + git_oid *out, + git_repository *repo, + const git_oid *one, + const git_oid *two); + +/** + * Find merge bases between two commits + * + * @param out array in which to store the resulting ids + * @param repo the repository where the commits exist + * @param one one of the commits + * @param two the other commit + * @return 0 on success, GIT_ENOTFOUND if not found or error code + */ +GIT_EXTERN(int) git_merge_bases( + git_oidarray *out, + git_repository *repo, + const git_oid *one, + const git_oid *two); + +/** + * Find a merge base given a list of commits + * + * @param out the OID of a merge base considering all the commits + * @param repo the repository where the commits exist + * @param length The number of commits in the provided `input_array` + * @param input_array oids of the commits + * @return Zero on success; GIT_ENOTFOUND or -1 on failure. + */ +GIT_EXTERN(int) git_merge_base_many( + git_oid *out, + git_repository *repo, + size_t length, + const git_oid input_array[]); + +/** + * Find all merge bases given a list of commits + * + * @param out array in which to store the resulting ids + * @param repo the repository where the commits exist + * @param length The number of commits in the provided `input_array` + * @param input_array oids of the commits + * @return Zero on success; GIT_ENOTFOUND or -1 on failure. + */ +GIT_EXTERN(int) git_merge_bases_many( + git_oidarray *out, + git_repository *repo, + size_t length, + const git_oid input_array[]); + +/** + * Find a merge base in preparation for an octopus merge + * + * @param out the OID of a merge base considering all the commits + * @param repo the repository where the commits exist + * @param length The number of commits in the provided `input_array` + * @param input_array oids of the commits + * @return Zero on success; GIT_ENOTFOUND or -1 on failure. + */ +GIT_EXTERN(int) git_merge_base_octopus( + git_oid *out, + git_repository *repo, + size_t length, + const git_oid input_array[]); + +/** + * Merge two files as they exist in the in-memory data structures, using + * the given common ancestor as the baseline, producing a + * `git_merge_file_result` that reflects the merge result. The + * `git_merge_file_result` must be freed with `git_merge_file_result_free`. + * + * Note that this function does not reference a repository and any + * configuration must be passed as `git_merge_file_options`. + * + * @param out The git_merge_file_result to be filled in + * @param ancestor The contents of the ancestor file + * @param ours The contents of the file in "our" side + * @param theirs The contents of the file in "their" side + * @param opts The merge file options or `NULL` for defaults + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_merge_file( + git_merge_file_result *out, + const git_merge_file_input *ancestor, + const git_merge_file_input *ours, + const git_merge_file_input *theirs, + const git_merge_file_options *opts); + +/** + * Merge two files as they exist in the index, using the given common + * ancestor as the baseline, producing a `git_merge_file_result` that + * reflects the merge result. The `git_merge_file_result` must be freed with + * `git_merge_file_result_free`. + * + * @param out The git_merge_file_result to be filled in + * @param repo The repository + * @param ancestor The index entry for the ancestor file (stage level 1) + * @param ours The index entry for our file (stage level 2) + * @param theirs The index entry for their file (stage level 3) + * @param opts The merge file options or NULL + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_merge_file_from_index( + git_merge_file_result *out, + git_repository *repo, + const git_index_entry *ancestor, + const git_index_entry *ours, + const git_index_entry *theirs, + const git_merge_file_options *opts); + +/** + * Frees a `git_merge_file_result`. + * + * @param result The result to free or `NULL` + */ +GIT_EXTERN(void) git_merge_file_result_free(git_merge_file_result *result); + +/** + * Merge two trees, producing a `git_index` that reflects the result of + * the merge. The index may be written as-is to the working directory + * or checked out. If the index is to be converted to a tree, the caller + * should resolve any conflicts that arose as part of the merge. + * + * The returned index must be freed explicitly with `git_index_free`. + * + * @param out pointer to store the index result in + * @param repo repository that contains the given trees + * @param ancestor_tree the common ancestor between the trees (or null if none) + * @param our_tree the tree that reflects the destination tree + * @param their_tree the tree to merge in to `our_tree` + * @param opts the merge tree options (or null for defaults) + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_merge_trees( + git_index **out, + git_repository *repo, + const git_tree *ancestor_tree, + const git_tree *our_tree, + const git_tree *their_tree, + const git_merge_options *opts); + +/** + * Merge two commits, producing a `git_index` that reflects the result of + * the merge. The index may be written as-is to the working directory + * or checked out. If the index is to be converted to a tree, the caller + * should resolve any conflicts that arose as part of the merge. + * + * The returned index must be freed explicitly with `git_index_free`. + * + * @param out pointer to store the index result in + * @param repo repository that contains the given trees + * @param our_commit the commit that reflects the destination tree + * @param their_commit the commit to merge in to `our_commit` + * @param opts the merge tree options (or null for defaults) + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_merge_commits( + git_index **out, + git_repository *repo, + const git_commit *our_commit, + const git_commit *their_commit, + const git_merge_options *opts); + +/** + * Merges the given commit(s) into HEAD, writing the results into the working + * directory. Any changes are staged for commit and any conflicts are written + * to the index. Callers should inspect the repository's index after this + * completes, resolve any conflicts and prepare a commit. + * + * For compatibility with git, the repository is put into a merging + * state. Once the commit is done (or if the user wishes to abort), + * you should clear this state by calling + * `git_repository_state_cleanup()`. + * + * @param repo the repository to merge + * @param their_heads the heads to merge into + * @param their_heads_len the number of heads to merge + * @param merge_opts merge options + * @param checkout_opts checkout options + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_merge( + git_repository *repo, + const git_annotated_commit **their_heads, + size_t their_heads_len, + const git_merge_options *merge_opts, + const git_checkout_options *checkout_opts); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/message.h b/3rdparty/libgit2/include/git2/message.h index cd3ddf7..f8801a6 100644 --- a/3rdparty/libgit2/include/git2/message.h +++ b/3rdparty/libgit2/include/git2/message.h @@ -1,86 +1,86 @@ -/* - * 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_message_h__ -#define INCLUDE_git_message_h__ - -#include "common.h" -#include "buffer.h" - -/** - * @file git2/message.h - * @brief Git message management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Clean up excess whitespace and make sure there is a trailing newline in the message. - * - * Optionally, it can remove lines which start with the comment character. - * - * @param out The user-allocated git_buf which will be filled with the - * cleaned up message. - * - * @param message The message to be prettified. - * - * @param strip_comments Non-zero to remove comment lines, 0 to leave them in. - * - * @param comment_char Comment character. Lines starting with this character - * are considered to be comments and removed if `strip_comments` is non-zero. - * - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_message_prettify(git_buf *out, const char *message, int strip_comments, char comment_char); - -/** - * Represents a single git message trailer. - */ -typedef struct { - const char *key; - const char *value; -} git_message_trailer; - -/** - * Represents an array of git message trailers. - * - * Struct members under the private comment are private, subject to change - * and should not be used by callers. - */ -typedef struct { - git_message_trailer *trailers; - size_t count; - - /* private */ - char *_trailer_block; -} git_message_trailer_array; - -/** - * Parse trailers out of a message, filling the array pointed to by +arr+. - * - * Trailers are key/value pairs in the last paragraph of a message, not - * including any patches or conflicts that may be present. - * - * @param arr A pre-allocated git_message_trailer_array struct to be filled in - * with any trailers found during parsing. - * @param message The message to be parsed - * @return 0 on success, or non-zero on error. - */ -GIT_EXTERN(int) git_message_trailers(git_message_trailer_array *arr, const char *message); - -/** - * Clean's up any allocated memory in the git_message_trailer_array filled by - * a call to git_message_trailers. - * - * @param arr The trailer to free. - */ -GIT_EXTERN(void) git_message_trailer_array_free(git_message_trailer_array *arr); - -/** @} */ -GIT_END_DECL - -#endif /* INCLUDE_git_message_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_message_h__ +#define INCLUDE_git_message_h__ + +#include "common.h" +#include "buffer.h" + +/** + * @file git2/message.h + * @brief Git message management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Clean up excess whitespace and make sure there is a trailing newline in the message. + * + * Optionally, it can remove lines which start with the comment character. + * + * @param out The user-allocated git_buf which will be filled with the + * cleaned up message. + * + * @param message The message to be prettified. + * + * @param strip_comments Non-zero to remove comment lines, 0 to leave them in. + * + * @param comment_char Comment character. Lines starting with this character + * are considered to be comments and removed if `strip_comments` is non-zero. + * + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_message_prettify(git_buf *out, const char *message, int strip_comments, char comment_char); + +/** + * Represents a single git message trailer. + */ +typedef struct { + const char *key; + const char *value; +} git_message_trailer; + +/** + * Represents an array of git message trailers. + * + * Struct members under the private comment are private, subject to change + * and should not be used by callers. + */ +typedef struct { + git_message_trailer *trailers; + size_t count; + + /* private */ + char *_trailer_block; +} git_message_trailer_array; + +/** + * Parse trailers out of a message, filling the array pointed to by +arr+. + * + * Trailers are key/value pairs in the last paragraph of a message, not + * including any patches or conflicts that may be present. + * + * @param arr A pre-allocated git_message_trailer_array struct to be filled in + * with any trailers found during parsing. + * @param message The message to be parsed + * @return 0 on success, or non-zero on error. + */ +GIT_EXTERN(int) git_message_trailers(git_message_trailer_array *arr, const char *message); + +/** + * Clean's up any allocated memory in the git_message_trailer_array filled by + * a call to git_message_trailers. + * + * @param arr The trailer to free. + */ +GIT_EXTERN(void) git_message_trailer_array_free(git_message_trailer_array *arr); + +/** @} */ +GIT_END_DECL + +#endif /* INCLUDE_git_message_h__ */ diff --git a/3rdparty/libgit2/include/git2/net.h b/3rdparty/libgit2/include/git2/net.h index 8103eaf..217500f 100644 --- a/3rdparty/libgit2/include/git2/net.h +++ b/3rdparty/libgit2/include/git2/net.h @@ -1,54 +1,54 @@ -/* - * 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_net_h__ -#define INCLUDE_git_net_h__ - -#include "common.h" -#include "oid.h" -#include "types.h" - -/** - * @file git2/net.h - * @brief Git networking declarations - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -#define GIT_DEFAULT_PORT "9418" - -/** - * Direction of the connection. - * - * We need this because we need to know whether we should call - * git-upload-pack or git-receive-pack on the remote end when get_refs - * gets called. - */ -typedef enum { - GIT_DIRECTION_FETCH = 0, - GIT_DIRECTION_PUSH = 1 -} git_direction; - -/** - * Description of a reference advertised by a remote server, given out - * on `ls` calls. - */ -struct git_remote_head { - int local; /* available locally */ - git_oid oid; - git_oid loid; - char *name; - /** - * If the server send a symref mapping for this ref, this will - * point to the target. - */ - char *symref_target; -}; - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_net_h__ +#define INCLUDE_git_net_h__ + +#include "common.h" +#include "oid.h" +#include "types.h" + +/** + * @file git2/net.h + * @brief Git networking declarations + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +#define GIT_DEFAULT_PORT "9418" + +/** + * Direction of the connection. + * + * We need this because we need to know whether we should call + * git-upload-pack or git-receive-pack on the remote end when get_refs + * gets called. + */ +typedef enum { + GIT_DIRECTION_FETCH = 0, + GIT_DIRECTION_PUSH = 1 +} git_direction; + +/** + * Description of a reference advertised by a remote server, given out + * on `ls` calls. + */ +struct git_remote_head { + int local; /* available locally */ + git_oid oid; + git_oid loid; + char *name; + /** + * If the server send a symref mapping for this ref, this will + * point to the target. + */ + char *symref_target; +}; + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/notes.h b/3rdparty/libgit2/include/git2/notes.h index c135881..c6c907b 100644 --- a/3rdparty/libgit2/include/git2/notes.h +++ b/3rdparty/libgit2/include/git2/notes.h @@ -1,306 +1,306 @@ -/* - * 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_note_h__ -#define INCLUDE_git_note_h__ - -#include "oid.h" - -/** - * @file git2/notes.h - * @brief Git notes management routines - * @defgroup git_note Git notes management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Callback for git_note_foreach. - * - * Receives: - * - blob_id: Oid of the blob containing the message - * - annotated_object_id: Oid of the git object being annotated - * - payload: Payload data passed to `git_note_foreach` - */ -typedef int GIT_CALLBACK(git_note_foreach_cb)( - const git_oid *blob_id, const git_oid *annotated_object_id, void *payload); - -/** - * note iterator - */ -typedef struct git_iterator git_note_iterator; - -/** - * Creates a new iterator for notes - * - * The iterator must be freed manually by the user. - * - * @param out pointer to the iterator - * @param repo repository where to look up the note - * @param notes_ref canonical name of the reference to use (optional); defaults to - * "refs/notes/commits" - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_note_iterator_new( - git_note_iterator **out, - git_repository *repo, - const char *notes_ref); - -/** - * Creates a new iterator for notes from a commit - * - * The iterator must be freed manually by the user. - * - * @param out pointer to the iterator - * @param notes_commit a pointer to the notes commit object - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_note_commit_iterator_new( - git_note_iterator **out, - git_commit *notes_commit); - -/** - * Frees an git_note_iterator - * - * @param it pointer to the iterator - */ -GIT_EXTERN(void) git_note_iterator_free(git_note_iterator *it); - -/** - * Return the current item (note_id and annotated_id) and advance the iterator - * internally to the next value - * - * @param note_id id of blob containing the message - * @param annotated_id id of the git object being annotated - * @param it pointer to the iterator - * - * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code - * (negative value) - */ -GIT_EXTERN(int) git_note_next( - git_oid *note_id, - git_oid *annotated_id, - git_note_iterator *it); - - -/** - * Read the note for an object - * - * The note must be freed manually by the user. - * - * @param out pointer to the read note; NULL in case of error - * @param repo repository where to look up the note - * @param notes_ref canonical name of the reference to use (optional); defaults to - * "refs/notes/commits" - * @param oid OID of the git object to read the note from - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_note_read( - git_note **out, - git_repository *repo, - const char *notes_ref, - const git_oid *oid); - - -/** - * Read the note for an object from a note commit - * - * The note must be freed manually by the user. - * - * @param out pointer to the read note; NULL in case of error - * @param repo repository where to look up the note - * @param notes_commit a pointer to the notes commit object - * @param oid OID of the git object to read the note from - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_note_commit_read( - git_note **out, - git_repository *repo, - git_commit *notes_commit, - const git_oid *oid); - -/** - * Get the note author - * - * @param note the note - * @return the author - */ -GIT_EXTERN(const git_signature *) git_note_author(const git_note *note); - -/** - * Get the note committer - * - * @param note the note - * @return the committer - */ -GIT_EXTERN(const git_signature *) git_note_committer(const git_note *note); - - -/** - * Get the note message - * - * @param note the note - * @return the note message - */ -GIT_EXTERN(const char *) git_note_message(const git_note *note); - - -/** - * Get the note object's id - * - * @param note the note - * @return the note object's id - */ -GIT_EXTERN(const git_oid *) git_note_id(const git_note *note); - -/** - * Add a note for an object - * - * @param out pointer to store the OID (optional); NULL in case of error - * @param repo repository where to store the note - * @param notes_ref canonical name of the reference to use (optional); - * defaults to "refs/notes/commits" - * @param author signature of the notes commit author - * @param committer signature of the notes commit committer - * @param oid OID of the git object to decorate - * @param note Content of the note to add for object oid - * @param force Overwrite existing note - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_note_create( - git_oid *out, - git_repository *repo, - const char *notes_ref, - const git_signature *author, - const git_signature *committer, - const git_oid *oid, - const char *note, - int force); - -/** - * Add a note for an object from a commit - * - * This function will create a notes commit for a given object, - * the commit is a dangling commit, no reference is created. - * - * @param notes_commit_out pointer to store the commit (optional); - * NULL in case of error - * @param notes_blob_out a point to the id of a note blob (optional) - * @param repo repository where the note will live - * @param parent Pointer to parent note - * or NULL if this shall start a new notes tree - * @param author signature of the notes commit author - * @param committer signature of the notes commit committer - * @param oid OID of the git object to decorate - * @param note Content of the note to add for object oid - * @param allow_note_overwrite Overwrite existing note - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_note_commit_create( - git_oid *notes_commit_out, - git_oid *notes_blob_out, - git_repository *repo, - git_commit *parent, - const git_signature *author, - const git_signature *committer, - const git_oid *oid, - const char *note, - int allow_note_overwrite); - -/** - * Remove the note for an object - * - * @param repo repository where the note lives - * @param notes_ref canonical name of the reference to use (optional); - * defaults to "refs/notes/commits" - * @param author signature of the notes commit author - * @param committer signature of the notes commit committer - * @param oid OID of the git object to remove the note from - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_note_remove( - git_repository *repo, - const char *notes_ref, - const git_signature *author, - const git_signature *committer, - const git_oid *oid); - -/** - * Remove the note for an object - * - * @param notes_commit_out pointer to store the new notes commit (optional); - * NULL in case of error. - * When removing a note a new tree containing all notes - * sans the note to be removed is created and a new commit - * pointing to that tree is also created. - * In the case where the resulting tree is an empty tree - * a new commit pointing to this empty tree will be returned. - * @param repo repository where the note lives - * @param notes_commit a pointer to the notes commit object - * @param author signature of the notes commit author - * @param committer signature of the notes commit committer - * @param oid OID of the git object to remove the note from - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_note_commit_remove( - git_oid *notes_commit_out, - git_repository *repo, - git_commit *notes_commit, - const git_signature *author, - const git_signature *committer, - const git_oid *oid); - -/** - * Free a git_note object - * - * @param note git_note object - */ -GIT_EXTERN(void) git_note_free(git_note *note); - -/** - * Get the default notes reference for a repository - * - * @param out buffer in which to store the name of the default notes reference - * @param repo The Git repository - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_note_default_ref(git_buf *out, git_repository *repo); - -/** - * Loop over all the notes within a specified namespace - * and issue a callback for each one. - * - * @param repo Repository where to find the notes. - * - * @param notes_ref Reference to read from (optional); defaults to - * "refs/notes/commits". - * - * @param note_cb Callback to invoke per found annotation. Return non-zero - * to stop looping. - * - * @param payload Extra parameter to callback function. - * - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_note_foreach( - git_repository *repo, - const char *notes_ref, - git_note_foreach_cb note_cb, - void *payload); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_note_h__ +#define INCLUDE_git_note_h__ + +#include "oid.h" + +/** + * @file git2/notes.h + * @brief Git notes management routines + * @defgroup git_note Git notes management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Callback for git_note_foreach. + * + * Receives: + * - blob_id: Oid of the blob containing the message + * - annotated_object_id: Oid of the git object being annotated + * - payload: Payload data passed to `git_note_foreach` + */ +typedef int GIT_CALLBACK(git_note_foreach_cb)( + const git_oid *blob_id, const git_oid *annotated_object_id, void *payload); + +/** + * note iterator + */ +typedef struct git_iterator git_note_iterator; + +/** + * Creates a new iterator for notes + * + * The iterator must be freed manually by the user. + * + * @param out pointer to the iterator + * @param repo repository where to look up the note + * @param notes_ref canonical name of the reference to use (optional); defaults to + * "refs/notes/commits" + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_iterator_new( + git_note_iterator **out, + git_repository *repo, + const char *notes_ref); + +/** + * Creates a new iterator for notes from a commit + * + * The iterator must be freed manually by the user. + * + * @param out pointer to the iterator + * @param notes_commit a pointer to the notes commit object + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_commit_iterator_new( + git_note_iterator **out, + git_commit *notes_commit); + +/** + * Frees an git_note_iterator + * + * @param it pointer to the iterator + */ +GIT_EXTERN(void) git_note_iterator_free(git_note_iterator *it); + +/** + * Return the current item (note_id and annotated_id) and advance the iterator + * internally to the next value + * + * @param note_id id of blob containing the message + * @param annotated_id id of the git object being annotated + * @param it pointer to the iterator + * + * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code + * (negative value) + */ +GIT_EXTERN(int) git_note_next( + git_oid *note_id, + git_oid *annotated_id, + git_note_iterator *it); + + +/** + * Read the note for an object + * + * The note must be freed manually by the user. + * + * @param out pointer to the read note; NULL in case of error + * @param repo repository where to look up the note + * @param notes_ref canonical name of the reference to use (optional); defaults to + * "refs/notes/commits" + * @param oid OID of the git object to read the note from + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_read( + git_note **out, + git_repository *repo, + const char *notes_ref, + const git_oid *oid); + + +/** + * Read the note for an object from a note commit + * + * The note must be freed manually by the user. + * + * @param out pointer to the read note; NULL in case of error + * @param repo repository where to look up the note + * @param notes_commit a pointer to the notes commit object + * @param oid OID of the git object to read the note from + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_commit_read( + git_note **out, + git_repository *repo, + git_commit *notes_commit, + const git_oid *oid); + +/** + * Get the note author + * + * @param note the note + * @return the author + */ +GIT_EXTERN(const git_signature *) git_note_author(const git_note *note); + +/** + * Get the note committer + * + * @param note the note + * @return the committer + */ +GIT_EXTERN(const git_signature *) git_note_committer(const git_note *note); + + +/** + * Get the note message + * + * @param note the note + * @return the note message + */ +GIT_EXTERN(const char *) git_note_message(const git_note *note); + + +/** + * Get the note object's id + * + * @param note the note + * @return the note object's id + */ +GIT_EXTERN(const git_oid *) git_note_id(const git_note *note); + +/** + * Add a note for an object + * + * @param out pointer to store the OID (optional); NULL in case of error + * @param repo repository where to store the note + * @param notes_ref canonical name of the reference to use (optional); + * defaults to "refs/notes/commits" + * @param author signature of the notes commit author + * @param committer signature of the notes commit committer + * @param oid OID of the git object to decorate + * @param note Content of the note to add for object oid + * @param force Overwrite existing note + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_create( + git_oid *out, + git_repository *repo, + const char *notes_ref, + const git_signature *author, + const git_signature *committer, + const git_oid *oid, + const char *note, + int force); + +/** + * Add a note for an object from a commit + * + * This function will create a notes commit for a given object, + * the commit is a dangling commit, no reference is created. + * + * @param notes_commit_out pointer to store the commit (optional); + * NULL in case of error + * @param notes_blob_out a point to the id of a note blob (optional) + * @param repo repository where the note will live + * @param parent Pointer to parent note + * or NULL if this shall start a new notes tree + * @param author signature of the notes commit author + * @param committer signature of the notes commit committer + * @param oid OID of the git object to decorate + * @param note Content of the note to add for object oid + * @param allow_note_overwrite Overwrite existing note + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_commit_create( + git_oid *notes_commit_out, + git_oid *notes_blob_out, + git_repository *repo, + git_commit *parent, + const git_signature *author, + const git_signature *committer, + const git_oid *oid, + const char *note, + int allow_note_overwrite); + +/** + * Remove the note for an object + * + * @param repo repository where the note lives + * @param notes_ref canonical name of the reference to use (optional); + * defaults to "refs/notes/commits" + * @param author signature of the notes commit author + * @param committer signature of the notes commit committer + * @param oid OID of the git object to remove the note from + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_remove( + git_repository *repo, + const char *notes_ref, + const git_signature *author, + const git_signature *committer, + const git_oid *oid); + +/** + * Remove the note for an object + * + * @param notes_commit_out pointer to store the new notes commit (optional); + * NULL in case of error. + * When removing a note a new tree containing all notes + * sans the note to be removed is created and a new commit + * pointing to that tree is also created. + * In the case where the resulting tree is an empty tree + * a new commit pointing to this empty tree will be returned. + * @param repo repository where the note lives + * @param notes_commit a pointer to the notes commit object + * @param author signature of the notes commit author + * @param committer signature of the notes commit committer + * @param oid OID of the git object to remove the note from + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_commit_remove( + git_oid *notes_commit_out, + git_repository *repo, + git_commit *notes_commit, + const git_signature *author, + const git_signature *committer, + const git_oid *oid); + +/** + * Free a git_note object + * + * @param note git_note object + */ +GIT_EXTERN(void) git_note_free(git_note *note); + +/** + * Get the default notes reference for a repository + * + * @param out buffer in which to store the name of the default notes reference + * @param repo The Git repository + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_default_ref(git_buf *out, git_repository *repo); + +/** + * Loop over all the notes within a specified namespace + * and issue a callback for each one. + * + * @param repo Repository where to find the notes. + * + * @param notes_ref Reference to read from (optional); defaults to + * "refs/notes/commits". + * + * @param note_cb Callback to invoke per found annotation. Return non-zero + * to stop looping. + * + * @param payload Extra parameter to callback function. + * + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_note_foreach( + git_repository *repo, + const char *notes_ref, + git_note_foreach_cb note_cb, + void *payload); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/object.h b/3rdparty/libgit2/include/git2/object.h index 6384aaa..e0ab948 100644 --- a/3rdparty/libgit2/include/git2/object.h +++ b/3rdparty/libgit2/include/git2/object.h @@ -1,279 +1,279 @@ -/* - * 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_object_h__ -#define INCLUDE_git_object_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "buffer.h" - -/** - * @file git2/object.h - * @brief Git revision object management routines - * @defgroup git_object Git revision object management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -#define GIT_OBJECT_SIZE_MAX UINT64_MAX - -/** - * Lookup a reference to one of the objects in a repository. - * - * The generated reference is owned by the repository and - * should be closed with the `git_object_free` method - * instead of free'd manually. - * - * The 'type' parameter must match the type of the object - * in the odb; the method will fail otherwise. - * The special value 'GIT_OBJECT_ANY' may be passed to let - * the method guess the object's type. - * - * @param object pointer to the looked-up object - * @param repo the repository to look up the object - * @param id the unique identifier for the object - * @param type the type of the object - * @return 0 or an error code - */ -GIT_EXTERN(int) git_object_lookup( - git_object **object, - git_repository *repo, - const git_oid *id, - git_object_t type); - -/** - * Lookup a reference to one of the objects in a repository, - * given a prefix of its identifier (short id). - * - * The object obtained will be so that its identifier - * matches the first 'len' hexadecimal characters - * (packets of 4 bits) of the given 'id'. - * 'len' must be at least GIT_OID_MINPREFIXLEN, and - * long enough to identify a unique object matching - * the prefix; otherwise the method will fail. - * - * The generated reference is owned by the repository and - * should be closed with the `git_object_free` method - * instead of free'd manually. - * - * The 'type' parameter must match the type of the object - * in the odb; the method will fail otherwise. - * The special value 'GIT_OBJECT_ANY' may be passed to let - * the method guess the object's type. - * - * @param object_out pointer where to store the looked-up object - * @param repo the repository to look up the object - * @param id a short identifier for the object - * @param len the length of the short identifier - * @param type the type of the object - * @return 0 or an error code - */ -GIT_EXTERN(int) git_object_lookup_prefix( - git_object **object_out, - git_repository *repo, - const git_oid *id, - size_t len, - git_object_t type); - - -/** - * Lookup an object that represents a tree entry. - * - * @param out buffer that receives a pointer to the object (which must be freed - * by the caller) - * @param treeish root object that can be peeled to a tree - * @param path relative path from the root object to the desired object - * @param type type of object desired - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_object_lookup_bypath( - git_object **out, - const git_object *treeish, - const char *path, - git_object_t type); - -/** - * Get the id (SHA1) of a repository object - * - * @param obj the repository object - * @return the SHA1 id - */ -GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj); - -/** - * Get a short abbreviated OID string for the object - * - * This starts at the "core.abbrev" length (default 7 characters) and - * iteratively extends to a longer string if that length is ambiguous. - * The result will be unambiguous (at least until new objects are added to - * the repository). - * - * @param out Buffer to write string into - * @param obj The object to get an ID for - * @return 0 on success, <0 for error - */ -GIT_EXTERN(int) git_object_short_id(git_buf *out, const git_object *obj); - -/** - * Get the object type of an object - * - * @param obj the repository object - * @return the object's type - */ -GIT_EXTERN(git_object_t) git_object_type(const git_object *obj); - -/** - * Get the repository that owns this object - * - * Freeing or calling `git_repository_close` on the - * returned pointer will invalidate the actual object. - * - * Any other operation may be run on the repository without - * affecting the object. - * - * @param obj the object - * @return the repository who owns this object - */ -GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj); - -/** - * Close an open object - * - * This method instructs the library to close an existing - * object; note that git_objects are owned and cached by the repository - * so the object may or may not be freed after this library call, - * depending on how aggressive is the caching mechanism used - * by the repository. - * - * IMPORTANT: - * It *is* necessary to call this method when you stop using - * an object. Failure to do so will cause a memory leak. - * - * @param object the object to close - */ -GIT_EXTERN(void) git_object_free(git_object *object); - -/** - * Convert an object type to its string representation. - * - * The result is a pointer to a string in static memory and - * should not be free()'ed. - * - * @param type object type to convert. - * @return the corresponding string representation. - */ -GIT_EXTERN(const char *) git_object_type2string(git_object_t type); - -/** - * Convert a string object type representation to it's git_object_t. - * - * @param str the string to convert. - * @return the corresponding git_object_t. - */ -GIT_EXTERN(git_object_t) git_object_string2type(const char *str); - -/** - * Determine if the given git_object_t is a valid loose object type. - * - * @param type object type to test. - * @return true if the type represents a valid loose object type, - * false otherwise. - */ -GIT_EXTERN(int) git_object_typeisloose(git_object_t type); - -/** - * Recursively peel an object until an object of the specified type is met. - * - * If the query cannot be satisfied due to the object model, - * GIT_EINVALIDSPEC will be returned (e.g. trying to peel a blob to a - * tree). - * - * If you pass `GIT_OBJECT_ANY` as the target type, then the object will - * be peeled until the type changes. A tag will be peeled until the - * referenced object is no longer a tag, and a commit will be peeled - * to a tree. Any other object type will return GIT_EINVALIDSPEC. - * - * If peeling a tag we discover an object which cannot be peeled to - * the target type due to the object model, GIT_EPEEL will be - * returned. - * - * You must free the returned object. - * - * @param peeled Pointer to the peeled git_object - * @param object The object to be processed - * @param target_type The type of the requested object (a GIT_OBJECT_ value) - * @return 0 on success, GIT_EINVALIDSPEC, GIT_EPEEL, or an error code - */ -GIT_EXTERN(int) git_object_peel( - git_object **peeled, - const git_object *object, - git_object_t target_type); - -/** - * Create an in-memory copy of a Git object. The copy must be - * explicitly free'd or it will leak. - * - * @param dest Pointer to store the copy of the object - * @param source Original object to copy - * @return 0 or an error code - */ -GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source); - -#ifdef GIT_EXPERIMENTAL_SHA256 -/** - * Analyzes a buffer of raw object content and determines its validity. - * Tree, commit, and tag objects will be parsed and ensured that they - * are valid, parseable content. (Blobs are always valid by definition.) - * An error message will be set with an informative message if the object - * is not valid. - * - * @warning This function is experimental and its signature may change in - * the future. - * - * @param valid Output pointer to set with validity of the object content - * @param buf The contents to validate - * @param len The length of the buffer - * @param object_type The type of the object in the buffer - * @param oid_type The object ID type for the OIDs in the given buffer - * @return 0 on success or an error code - */ -GIT_EXTERN(int) git_object_rawcontent_is_valid( - int *valid, - const char *buf, - size_t len, - git_object_t object_type, - git_oid_t oid_type); -#else -/** - * Analyzes a buffer of raw object content and determines its validity. - * Tree, commit, and tag objects will be parsed and ensured that they - * are valid, parseable content. (Blobs are always valid by definition.) - * An error message will be set with an informative message if the object - * is not valid. - * - * @warning This function is experimental and its signature may change in - * the future. - * - * @param valid Output pointer to set with validity of the object content - * @param buf The contents to validate - * @param len The length of the buffer - * @param object_type The type of the object in the buffer - * @return 0 on success or an error code - */ -GIT_EXTERN(int) git_object_rawcontent_is_valid( - int *valid, - const char *buf, - size_t len, - git_object_t object_type); -#endif - -/** @} */ -GIT_END_DECL - -#endif +/* + * 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_object_h__ +#define INCLUDE_git_object_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "buffer.h" + +/** + * @file git2/object.h + * @brief Git revision object management routines + * @defgroup git_object Git revision object management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +#define GIT_OBJECT_SIZE_MAX UINT64_MAX + +/** + * Lookup a reference to one of the objects in a repository. + * + * The generated reference is owned by the repository and + * should be closed with the `git_object_free` method + * instead of free'd manually. + * + * The 'type' parameter must match the type of the object + * in the odb; the method will fail otherwise. + * The special value 'GIT_OBJECT_ANY' may be passed to let + * the method guess the object's type. + * + * @param object pointer to the looked-up object + * @param repo the repository to look up the object + * @param id the unique identifier for the object + * @param type the type of the object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_object_lookup( + git_object **object, + git_repository *repo, + const git_oid *id, + git_object_t type); + +/** + * Lookup a reference to one of the objects in a repository, + * given a prefix of its identifier (short id). + * + * The object obtained will be so that its identifier + * matches the first 'len' hexadecimal characters + * (packets of 4 bits) of the given 'id'. + * 'len' must be at least GIT_OID_MINPREFIXLEN, and + * long enough to identify a unique object matching + * the prefix; otherwise the method will fail. + * + * The generated reference is owned by the repository and + * should be closed with the `git_object_free` method + * instead of free'd manually. + * + * The 'type' parameter must match the type of the object + * in the odb; the method will fail otherwise. + * The special value 'GIT_OBJECT_ANY' may be passed to let + * the method guess the object's type. + * + * @param object_out pointer where to store the looked-up object + * @param repo the repository to look up the object + * @param id a short identifier for the object + * @param len the length of the short identifier + * @param type the type of the object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_object_lookup_prefix( + git_object **object_out, + git_repository *repo, + const git_oid *id, + size_t len, + git_object_t type); + + +/** + * Lookup an object that represents a tree entry. + * + * @param out buffer that receives a pointer to the object (which must be freed + * by the caller) + * @param treeish root object that can be peeled to a tree + * @param path relative path from the root object to the desired object + * @param type type of object desired + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_object_lookup_bypath( + git_object **out, + const git_object *treeish, + const char *path, + git_object_t type); + +/** + * Get the id (SHA1) of a repository object + * + * @param obj the repository object + * @return the SHA1 id + */ +GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj); + +/** + * Get a short abbreviated OID string for the object + * + * This starts at the "core.abbrev" length (default 7 characters) and + * iteratively extends to a longer string if that length is ambiguous. + * The result will be unambiguous (at least until new objects are added to + * the repository). + * + * @param out Buffer to write string into + * @param obj The object to get an ID for + * @return 0 on success, <0 for error + */ +GIT_EXTERN(int) git_object_short_id(git_buf *out, const git_object *obj); + +/** + * Get the object type of an object + * + * @param obj the repository object + * @return the object's type + */ +GIT_EXTERN(git_object_t) git_object_type(const git_object *obj); + +/** + * Get the repository that owns this object + * + * Freeing or calling `git_repository_close` on the + * returned pointer will invalidate the actual object. + * + * Any other operation may be run on the repository without + * affecting the object. + * + * @param obj the object + * @return the repository who owns this object + */ +GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj); + +/** + * Close an open object + * + * This method instructs the library to close an existing + * object; note that git_objects are owned and cached by the repository + * so the object may or may not be freed after this library call, + * depending on how aggressive is the caching mechanism used + * by the repository. + * + * IMPORTANT: + * It *is* necessary to call this method when you stop using + * an object. Failure to do so will cause a memory leak. + * + * @param object the object to close + */ +GIT_EXTERN(void) git_object_free(git_object *object); + +/** + * Convert an object type to its string representation. + * + * The result is a pointer to a string in static memory and + * should not be free()'ed. + * + * @param type object type to convert. + * @return the corresponding string representation. + */ +GIT_EXTERN(const char *) git_object_type2string(git_object_t type); + +/** + * Convert a string object type representation to it's git_object_t. + * + * @param str the string to convert. + * @return the corresponding git_object_t. + */ +GIT_EXTERN(git_object_t) git_object_string2type(const char *str); + +/** + * Determine if the given git_object_t is a valid loose object type. + * + * @param type object type to test. + * @return true if the type represents a valid loose object type, + * false otherwise. + */ +GIT_EXTERN(int) git_object_typeisloose(git_object_t type); + +/** + * Recursively peel an object until an object of the specified type is met. + * + * If the query cannot be satisfied due to the object model, + * GIT_EINVALIDSPEC will be returned (e.g. trying to peel a blob to a + * tree). + * + * If you pass `GIT_OBJECT_ANY` as the target type, then the object will + * be peeled until the type changes. A tag will be peeled until the + * referenced object is no longer a tag, and a commit will be peeled + * to a tree. Any other object type will return GIT_EINVALIDSPEC. + * + * If peeling a tag we discover an object which cannot be peeled to + * the target type due to the object model, GIT_EPEEL will be + * returned. + * + * You must free the returned object. + * + * @param peeled Pointer to the peeled git_object + * @param object The object to be processed + * @param target_type The type of the requested object (a GIT_OBJECT_ value) + * @return 0 on success, GIT_EINVALIDSPEC, GIT_EPEEL, or an error code + */ +GIT_EXTERN(int) git_object_peel( + git_object **peeled, + const git_object *object, + git_object_t target_type); + +/** + * Create an in-memory copy of a Git object. The copy must be + * explicitly free'd or it will leak. + * + * @param dest Pointer to store the copy of the object + * @param source Original object to copy + * @return 0 or an error code + */ +GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source); + +#ifdef GIT_EXPERIMENTAL_SHA256 +/** + * Analyzes a buffer of raw object content and determines its validity. + * Tree, commit, and tag objects will be parsed and ensured that they + * are valid, parseable content. (Blobs are always valid by definition.) + * An error message will be set with an informative message if the object + * is not valid. + * + * @warning This function is experimental and its signature may change in + * the future. + * + * @param valid Output pointer to set with validity of the object content + * @param buf The contents to validate + * @param len The length of the buffer + * @param object_type The type of the object in the buffer + * @param oid_type The object ID type for the OIDs in the given buffer + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_object_rawcontent_is_valid( + int *valid, + const char *buf, + size_t len, + git_object_t object_type, + git_oid_t oid_type); +#else +/** + * Analyzes a buffer of raw object content and determines its validity. + * Tree, commit, and tag objects will be parsed and ensured that they + * are valid, parseable content. (Blobs are always valid by definition.) + * An error message will be set with an informative message if the object + * is not valid. + * + * @warning This function is experimental and its signature may change in + * the future. + * + * @param valid Output pointer to set with validity of the object content + * @param buf The contents to validate + * @param len The length of the buffer + * @param object_type The type of the object in the buffer + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_object_rawcontent_is_valid( + int *valid, + const char *buf, + size_t len, + git_object_t object_type); +#endif + +/** @} */ +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/odb.h b/3rdparty/libgit2/include/git2/odb.h index c7d6a89..b4d5ce6 100644 --- a/3rdparty/libgit2/include/git2/odb.h +++ b/3rdparty/libgit2/include/git2/odb.h @@ -1,654 +1,654 @@ -/* - * 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_odb_h__ -#define INCLUDE_git_odb_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "oidarray.h" -#include "indexer.h" - -/** - * @file git2/odb.h - * @brief Git object database routines - * @defgroup git_odb Git object database routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** Flags controlling the behavior of ODB lookup operations */ -typedef enum { - /** - * Don't call `git_odb_refresh` if the lookup fails. Useful when doing - * a batch of lookup operations for objects that may legitimately not - * exist. When using this flag, you may wish to manually call - * `git_odb_refresh` before processing a batch of objects. - */ - GIT_ODB_LOOKUP_NO_REFRESH = (1 << 0) -} git_odb_lookup_flags_t; - -/** - * Function type for callbacks from git_odb_foreach. - */ -typedef int GIT_CALLBACK(git_odb_foreach_cb)(const git_oid *id, void *payload); - -/** Options for configuring a loose object backend. */ -typedef struct { - unsigned int version; /**< version for the struct */ - - /** - * Type of object IDs to use for this object database, or - * 0 for default (currently SHA1). - */ - git_oid_t oid_type; -} git_odb_options; - -/* The current version of the diff options structure */ -#define GIT_ODB_OPTIONS_VERSION 1 - -/* Stack initializer for odb options. Alternatively use - * `git_odb_options_init` programmatic initialization. - */ -#define GIT_ODB_OPTIONS_INIT { GIT_ODB_OPTIONS_VERSION } - -/** - * Create a new object database with no backends. - * - * Before the ODB can be used for read/writing, a custom database - * backend must be manually added using `git_odb_add_backend()` - * - * @param out location to store the database pointer, if opened. - * Set to NULL if the open failed. - * @param opts the options for this object database or NULL for defaults - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_new(git_odb **out, const git_odb_options *opts); -#else -GIT_EXTERN(int) git_odb_new(git_odb **out); -#endif - -/** - * Create a new object database and automatically add - * the two default backends: - * - * - git_odb_backend_loose: read and write loose object files - * from disk, assuming `objects_dir` as the Objects folder - * - * - git_odb_backend_pack: read objects from packfiles, - * assuming `objects_dir` as the Objects folder which - * contains a 'pack/' folder with the corresponding data - * - * @param out location to store the database pointer, if opened. - * Set to NULL if the open failed. - * @param objects_dir path of the backends' "objects" directory. - * @param opts the options for this object database or NULL for defaults - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_open( - git_odb **out, - const char *objects_dir, - const git_odb_options *opts); -#else -GIT_EXTERN(int) git_odb_open(git_odb **out, const char *objects_dir); -#endif - -/** - * Add an on-disk alternate to an existing Object DB. - * - * Note that the added path must point to an `objects`, not - * to a full repository, to use it as an alternate store. - * - * Alternate backends are always checked for objects *after* - * all the main backends have been exhausted. - * - * Writing is disabled on alternate backends. - * - * @param odb database to add the backend to - * @param path path to the objects folder for the alternate - * @return 0 on success, error code otherwise - */ -GIT_EXTERN(int) git_odb_add_disk_alternate(git_odb *odb, const char *path); - -/** - * Close an open object database. - * - * @param db database pointer to close. If NULL no action is taken. - */ -GIT_EXTERN(void) git_odb_free(git_odb *db); - -/** - * Read an object from the database. - * - * This method queries all available ODB backends - * trying to read the given OID. - * - * The returned object is reference counted and - * internally cached, so it should be closed - * by the user once it's no longer in use. - * - * @param out pointer where to store the read object - * @param db database to search for the object in. - * @param id identity of the object to read. - * @return 0 if the object was read, GIT_ENOTFOUND if the object is - * not in the database. - */ -GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *id); - -/** - * Read an object from the database, given a prefix - * of its identifier. - * - * This method queries all available ODB backends - * trying to match the 'len' first hexadecimal - * characters of the 'short_id'. - * The remaining (GIT_OID_SHA1_HEXSIZE-len)*4 bits of - * 'short_id' must be 0s. - * 'len' must be at least GIT_OID_MINPREFIXLEN, - * and the prefix must be long enough to identify - * a unique object in all the backends; the - * method will fail otherwise. - * - * The returned object is reference counted and - * internally cached, so it should be closed - * by the user once it's no longer in use. - * - * @param out pointer where to store the read object - * @param db database to search for the object in. - * @param short_id a prefix of the id of the object to read. - * @param len the length of the prefix - * @return 0 if the object was read, GIT_ENOTFOUND if the object is not in the - * database. GIT_EAMBIGUOUS if the prefix is ambiguous - * (several objects match the prefix) - */ -GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git_oid *short_id, size_t len); - -/** - * Read the header of an object from the database, without - * reading its full contents. - * - * The header includes the length and the type of an object. - * - * Note that most backends do not support reading only the header - * of an object, so the whole object will be read and then the - * header will be returned. - * - * @param len_out pointer where to store the length - * @param type_out pointer where to store the type - * @param db database to search for the object in. - * @param id identity of the object to read. - * @return 0 if the object was read, GIT_ENOTFOUND if the object is not - * in the database. - */ -GIT_EXTERN(int) git_odb_read_header(size_t *len_out, git_object_t *type_out, git_odb *db, const git_oid *id); - -/** - * Determine if the given object can be found in the object database. - * - * @param db database to be searched for the given object. - * @param id the object to search for. - * @return 1 if the object was found, 0 otherwise - */ -GIT_EXTERN(int) git_odb_exists(git_odb *db, const git_oid *id); - -/** - * Determine if the given object can be found in the object database, with - * extended options. - * - * @param db database to be searched for the given object. - * @param id the object to search for. - * @param flags flags affecting the lookup (see `git_odb_lookup_flags_t`) - * @return 1 if the object was found, 0 otherwise - */ -GIT_EXTERN(int) git_odb_exists_ext(git_odb *db, const git_oid *id, unsigned int flags); - -/** - * Determine if an object can be found in the object database by an - * abbreviated object ID. - * - * @param out The full OID of the found object if just one is found. - * @param db The database to be searched for the given object. - * @param short_id A prefix of the id of the object to read. - * @param len The length of the prefix. - * @return 0 if found, GIT_ENOTFOUND if not found, GIT_EAMBIGUOUS if multiple - * matches were found, other value < 0 if there was a read error. - */ -GIT_EXTERN(int) git_odb_exists_prefix( - git_oid *out, git_odb *db, const git_oid *short_id, size_t len); - -/** - * The information about object IDs to query in `git_odb_expand_ids`, - * which will be populated upon return. - */ -typedef struct git_odb_expand_id { - /** The object ID to expand */ - git_oid id; - - /** - * The length of the object ID (in nibbles, or packets of 4 bits; the - * number of hex characters) - * */ - unsigned short length; - - /** - * The (optional) type of the object to search for; leave as `0` or set - * to `GIT_OBJECT_ANY` to query for any object matching the ID. - */ - git_object_t type; -} git_odb_expand_id; - -/** - * Determine if one or more objects can be found in the object database - * by their abbreviated object ID and type. - * - * The given array will be updated in place: for each abbreviated ID that is - * unique in the database, and of the given type (if specified), - * the full object ID, object ID length (`GIT_OID_SHA1_HEXSIZE`) and type will be - * written back to the array. For IDs that are not found (or are ambiguous), - * the array entry will be zeroed. - * - * Note that since this function operates on multiple objects, the - * underlying database will not be asked to be reloaded if an object is - * not found (which is unlike other object database operations.) - * - * @param db The database to be searched for the given objects. - * @param ids An array of short object IDs to search for - * @param count The length of the `ids` array - * @return 0 on success or an error code on failure - */ -GIT_EXTERN(int) git_odb_expand_ids( - git_odb *db, - git_odb_expand_id *ids, - size_t count); - -/** - * Refresh the object database to load newly added files. - * - * If the object databases have changed on disk while the library - * is running, this function will force a reload of the underlying - * indexes. - * - * Use this function when you're confident that an external - * application has tampered with the ODB. - * - * NOTE that it is not necessary to call this function at all. The - * library will automatically attempt to refresh the ODB - * when a lookup fails, to see if the looked up object exists - * on disk but hasn't been loaded yet. - * - * @param db database to refresh - * @return 0 on success, error code otherwise - */ -GIT_EXTERN(int) git_odb_refresh(struct git_odb *db); - -/** - * List all objects available in the database - * - * The callback will be called for each object available in the - * database. Note that the objects are likely to be returned in the index - * order, which would make accessing the objects in that order inefficient. - * Return a non-zero value from the callback to stop looping. - * - * @param db database to use - * @param cb the callback to call for each object - * @param payload data to pass to the callback - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payload); - -/** - * Write an object directly into the ODB - * - * This method writes a full object straight into the ODB. - * For most cases, it is preferred to write objects through a write - * stream, which is both faster and less memory intensive, specially - * for big objects. - * - * This method is provided for compatibility with custom backends - * which are not able to support streaming writes - * - * @param out pointer to store the OID result of the write - * @param odb object database where to store the object - * @param data buffer with the data to store - * @param len size of the buffer - * @param type type of the data to store - * @return 0 or an error code - */ -GIT_EXTERN(int) git_odb_write(git_oid *out, git_odb *odb, const void *data, size_t len, git_object_t type); - -/** - * Open a stream to write an object into the ODB - * - * The type and final length of the object must be specified - * when opening the stream. - * - * The returned stream will be of type `GIT_STREAM_WRONLY`, and it - * won't be effective until `git_odb_stream_finalize_write` is called - * and returns without an error - * - * The stream must always be freed when done with `git_odb_stream_free` or - * will leak memory. - * - * @see git_odb_stream - * - * @param out pointer where to store the stream - * @param db object database where the stream will write - * @param size final size of the object that will be written - * @param type type of the object that will be written - * @return 0 if the stream was created; error code otherwise - */ -GIT_EXTERN(int) git_odb_open_wstream(git_odb_stream **out, git_odb *db, git_object_size_t size, git_object_t type); - -/** - * Write to an odb stream - * - * This method will fail if the total number of received bytes exceeds the - * size declared with `git_odb_open_wstream()` - * - * @param stream the stream - * @param buffer the data to write - * @param len the buffer's length - * @return 0 if the write succeeded, error code otherwise - */ -GIT_EXTERN(int) git_odb_stream_write(git_odb_stream *stream, const char *buffer, size_t len); - -/** - * Finish writing to an odb stream - * - * The object will take its final name and will be available to the - * odb. - * - * This method will fail if the total number of received bytes - * differs from the size declared with `git_odb_open_wstream()` - * - * @param out pointer to store the resulting object's id - * @param stream the stream - * @return 0 on success, an error code otherwise - */ -GIT_EXTERN(int) git_odb_stream_finalize_write(git_oid *out, git_odb_stream *stream); - -/** - * Read from an odb stream - * - * Most backends don't implement streaming reads - * - * @param stream the stream - * @param buffer a user-allocated buffer to store the data in. - * @param len the buffer's length - * @return 0 if the read succeeded, error code otherwise - */ -GIT_EXTERN(int) git_odb_stream_read(git_odb_stream *stream, char *buffer, size_t len); - -/** - * Free an odb stream - * - * @param stream the stream to free - */ -GIT_EXTERN(void) git_odb_stream_free(git_odb_stream *stream); - -/** - * Open a stream to read an object from the ODB - * - * Note that most backends do *not* support streaming reads - * because they store their objects as compressed/delta'ed blobs. - * - * It's recommended to use `git_odb_read` instead, which is - * assured to work on all backends. - * - * The returned stream will be of type `GIT_STREAM_RDONLY` and - * will have the following methods: - * - * - stream->read: read `n` bytes from the stream - * - stream->free: free the stream - * - * The stream must always be free'd or will leak memory. - * - * @see git_odb_stream - * - * @param out pointer where to store the stream - * @param len pointer where to store the length of the object - * @param type pointer where to store the type of the object - * @param db object database where the stream will read from - * @param oid oid of the object the stream will read from - * @return 0 if the stream was created, error code otherwise - */ -GIT_EXTERN(int) git_odb_open_rstream( - git_odb_stream **out, - size_t *len, - git_object_t *type, - git_odb *db, - const git_oid *oid); - -/** - * Open a stream for writing a pack file to the ODB. - * - * If the ODB layer understands pack files, then the given - * packfile will likely be streamed directly to disk (and a - * corresponding index created). If the ODB layer does not - * understand pack files, the objects will be stored in whatever - * format the ODB layer uses. - * - * @see git_odb_writepack - * - * @param out pointer to the writepack functions - * @param db object database where the stream will read from - * @param progress_cb function to call with progress information. - * Be aware that this is called inline with network and indexing operations, - * so performance may be affected. - * @param progress_payload payload for the progress callback - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_odb_write_pack( - git_odb_writepack **out, - git_odb *db, - git_indexer_progress_cb progress_cb, - void *progress_payload); - -/** - * Write a `multi-pack-index` file from all the `.pack` files in the ODB. - * - * If the ODB layer understands pack files, then this will create a file called - * `multi-pack-index` next to the `.pack` and `.idx` files, which will contain - * an index of all objects stored in `.pack` files. This will allow for - * O(log n) lookup for n objects (regardless of how many packfiles there - * exist). - * - * @param db object database where the `multi-pack-index` file will be written. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_odb_write_multi_pack_index( - git_odb *db); - -/** - * Determine the object-ID (sha1 or sha256 hash) of a data buffer - * - * The resulting OID will be the identifier for the data buffer as if - * the data buffer it were to written to the ODB. - * - * @param out the resulting object-ID. - * @param data data to hash - * @param len size of the data - * @param object_type of the data to hash - * @param oid_type the oid type to hash to - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_hash( - git_oid *out, - const void *data, - size_t len, - git_object_t object_type, - git_oid_t oid_type); -#else -GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_object_t type); -#endif - -/** - * Read a file from disk and fill a git_oid with the object id - * that the file would have if it were written to the Object - * Database as an object of the given type (w/o applying filters). - * Similar functionality to git.git's `git hash-object` without - * the `-w` flag, however, with the --no-filters flag. - * If you need filters, see git_repository_hashfile. - * - * @param out oid structure the result is written into. - * @param path file to read and determine object id for - * @param object_type of the data to hash - * @param oid_type the oid type to hash to - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_hashfile( - git_oid *out, - const char *path, - git_object_t object_type, - git_oid_t oid_type); -#else -GIT_EXTERN(int) git_odb_hashfile(git_oid *out, const char *path, git_object_t type); -#endif - -/** - * Create a copy of an odb_object - * - * The returned copy must be manually freed with `git_odb_object_free`. - * Note that because of an implementation detail, the returned copy will be - * the same pointer as `source`: the object is internally refcounted, so the - * copy still needs to be freed twice. - * - * @param dest pointer where to store the copy - * @param source object to copy - * @return 0 or an error code - */ -GIT_EXTERN(int) git_odb_object_dup(git_odb_object **dest, git_odb_object *source); - -/** - * Close an ODB object - * - * This method must always be called once a `git_odb_object` is no - * longer needed, otherwise memory will leak. - * - * @param object object to close - */ -GIT_EXTERN(void) git_odb_object_free(git_odb_object *object); - -/** - * Return the OID of an ODB object - * - * This is the OID from which the object was read from - * - * @param object the object - * @return a pointer to the OID - */ -GIT_EXTERN(const git_oid *) git_odb_object_id(git_odb_object *object); - -/** - * Return the data of an ODB object - * - * This is the uncompressed, raw data as read from the ODB, - * without the leading header. - * - * This pointer is owned by the object and shall not be free'd. - * - * @param object the object - * @return a pointer to the data - */ -GIT_EXTERN(const void *) git_odb_object_data(git_odb_object *object); - -/** - * Return the size of an ODB object - * - * This is the real size of the `data` buffer, not the - * actual size of the object. - * - * @param object the object - * @return the size - */ -GIT_EXTERN(size_t) git_odb_object_size(git_odb_object *object); - -/** - * Return the type of an ODB object - * - * @param object the object - * @return the type - */ -GIT_EXTERN(git_object_t) git_odb_object_type(git_odb_object *object); - -/** - * Add a custom backend to an existing Object DB - * - * The backends are checked in relative ordering, based on the - * value of the `priority` parameter. - * - * Read for more information. - * - * @param odb database to add the backend to - * @param backend pointer to a git_odb_backend instance - * @param priority Value for ordering the backends queue - * @return 0 on success, error code otherwise - */ -GIT_EXTERN(int) git_odb_add_backend(git_odb *odb, git_odb_backend *backend, int priority); - -/** - * Add a custom backend to an existing Object DB; this - * backend will work as an alternate. - * - * Alternate backends are always checked for objects *after* - * all the main backends have been exhausted. - * - * The backends are checked in relative ordering, based on the - * value of the `priority` parameter. - * - * Writing is disabled on alternate backends. - * - * Read for more information. - * - * @param odb database to add the backend to - * @param backend pointer to a git_odb_backend instance - * @param priority Value for ordering the backends queue - * @return 0 on success, error code otherwise - */ -GIT_EXTERN(int) git_odb_add_alternate(git_odb *odb, git_odb_backend *backend, int priority); - -/** - * Get the number of ODB backend objects - * - * @param odb object database - * @return number of backends in the ODB - */ -GIT_EXTERN(size_t) git_odb_num_backends(git_odb *odb); - -/** - * Lookup an ODB backend object by index - * - * @param out output pointer to ODB backend at pos - * @param odb object database - * @param pos index into object database backend list - * @return 0 on success, GIT_ENOTFOUND if pos is invalid, other errors < 0 - */ -GIT_EXTERN(int) git_odb_get_backend(git_odb_backend **out, git_odb *odb, size_t pos); - -/** - * Set the git commit-graph for the ODB. - * - * After a successful call, the ownership of the cgraph parameter will be - * transferred to libgit2, and the caller should not free it. - * - * The commit-graph can also be unset by explicitly passing NULL as the cgraph - * parameter. - * - * @param odb object database - * @param cgraph the git commit-graph - * @return 0 on success; error code otherwise - */ -GIT_EXTERN(int) git_odb_set_commit_graph(git_odb *odb, git_commit_graph *cgraph); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_odb_h__ +#define INCLUDE_git_odb_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "oidarray.h" +#include "indexer.h" + +/** + * @file git2/odb.h + * @brief Git object database routines + * @defgroup git_odb Git object database routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** Flags controlling the behavior of ODB lookup operations */ +typedef enum { + /** + * Don't call `git_odb_refresh` if the lookup fails. Useful when doing + * a batch of lookup operations for objects that may legitimately not + * exist. When using this flag, you may wish to manually call + * `git_odb_refresh` before processing a batch of objects. + */ + GIT_ODB_LOOKUP_NO_REFRESH = (1 << 0) +} git_odb_lookup_flags_t; + +/** + * Function type for callbacks from git_odb_foreach. + */ +typedef int GIT_CALLBACK(git_odb_foreach_cb)(const git_oid *id, void *payload); + +/** Options for configuring a loose object backend. */ +typedef struct { + unsigned int version; /**< version for the struct */ + + /** + * Type of object IDs to use for this object database, or + * 0 for default (currently SHA1). + */ + git_oid_t oid_type; +} git_odb_options; + +/* The current version of the diff options structure */ +#define GIT_ODB_OPTIONS_VERSION 1 + +/* Stack initializer for odb options. Alternatively use + * `git_odb_options_init` programmatic initialization. + */ +#define GIT_ODB_OPTIONS_INIT { GIT_ODB_OPTIONS_VERSION } + +/** + * Create a new object database with no backends. + * + * Before the ODB can be used for read/writing, a custom database + * backend must be manually added using `git_odb_add_backend()` + * + * @param out location to store the database pointer, if opened. + * Set to NULL if the open failed. + * @param opts the options for this object database or NULL for defaults + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_odb_new(git_odb **out, const git_odb_options *opts); +#else +GIT_EXTERN(int) git_odb_new(git_odb **out); +#endif + +/** + * Create a new object database and automatically add + * the two default backends: + * + * - git_odb_backend_loose: read and write loose object files + * from disk, assuming `objects_dir` as the Objects folder + * + * - git_odb_backend_pack: read objects from packfiles, + * assuming `objects_dir` as the Objects folder which + * contains a 'pack/' folder with the corresponding data + * + * @param out location to store the database pointer, if opened. + * Set to NULL if the open failed. + * @param objects_dir path of the backends' "objects" directory. + * @param opts the options for this object database or NULL for defaults + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_odb_open( + git_odb **out, + const char *objects_dir, + const git_odb_options *opts); +#else +GIT_EXTERN(int) git_odb_open(git_odb **out, const char *objects_dir); +#endif + +/** + * Add an on-disk alternate to an existing Object DB. + * + * Note that the added path must point to an `objects`, not + * to a full repository, to use it as an alternate store. + * + * Alternate backends are always checked for objects *after* + * all the main backends have been exhausted. + * + * Writing is disabled on alternate backends. + * + * @param odb database to add the backend to + * @param path path to the objects folder for the alternate + * @return 0 on success, error code otherwise + */ +GIT_EXTERN(int) git_odb_add_disk_alternate(git_odb *odb, const char *path); + +/** + * Close an open object database. + * + * @param db database pointer to close. If NULL no action is taken. + */ +GIT_EXTERN(void) git_odb_free(git_odb *db); + +/** + * Read an object from the database. + * + * This method queries all available ODB backends + * trying to read the given OID. + * + * The returned object is reference counted and + * internally cached, so it should be closed + * by the user once it's no longer in use. + * + * @param out pointer where to store the read object + * @param db database to search for the object in. + * @param id identity of the object to read. + * @return 0 if the object was read, GIT_ENOTFOUND if the object is + * not in the database. + */ +GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *id); + +/** + * Read an object from the database, given a prefix + * of its identifier. + * + * This method queries all available ODB backends + * trying to match the 'len' first hexadecimal + * characters of the 'short_id'. + * The remaining (GIT_OID_SHA1_HEXSIZE-len)*4 bits of + * 'short_id' must be 0s. + * 'len' must be at least GIT_OID_MINPREFIXLEN, + * and the prefix must be long enough to identify + * a unique object in all the backends; the + * method will fail otherwise. + * + * The returned object is reference counted and + * internally cached, so it should be closed + * by the user once it's no longer in use. + * + * @param out pointer where to store the read object + * @param db database to search for the object in. + * @param short_id a prefix of the id of the object to read. + * @param len the length of the prefix + * @return 0 if the object was read, GIT_ENOTFOUND if the object is not in the + * database. GIT_EAMBIGUOUS if the prefix is ambiguous + * (several objects match the prefix) + */ +GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git_oid *short_id, size_t len); + +/** + * Read the header of an object from the database, without + * reading its full contents. + * + * The header includes the length and the type of an object. + * + * Note that most backends do not support reading only the header + * of an object, so the whole object will be read and then the + * header will be returned. + * + * @param len_out pointer where to store the length + * @param type_out pointer where to store the type + * @param db database to search for the object in. + * @param id identity of the object to read. + * @return 0 if the object was read, GIT_ENOTFOUND if the object is not + * in the database. + */ +GIT_EXTERN(int) git_odb_read_header(size_t *len_out, git_object_t *type_out, git_odb *db, const git_oid *id); + +/** + * Determine if the given object can be found in the object database. + * + * @param db database to be searched for the given object. + * @param id the object to search for. + * @return 1 if the object was found, 0 otherwise + */ +GIT_EXTERN(int) git_odb_exists(git_odb *db, const git_oid *id); + +/** + * Determine if the given object can be found in the object database, with + * extended options. + * + * @param db database to be searched for the given object. + * @param id the object to search for. + * @param flags flags affecting the lookup (see `git_odb_lookup_flags_t`) + * @return 1 if the object was found, 0 otherwise + */ +GIT_EXTERN(int) git_odb_exists_ext(git_odb *db, const git_oid *id, unsigned int flags); + +/** + * Determine if an object can be found in the object database by an + * abbreviated object ID. + * + * @param out The full OID of the found object if just one is found. + * @param db The database to be searched for the given object. + * @param short_id A prefix of the id of the object to read. + * @param len The length of the prefix. + * @return 0 if found, GIT_ENOTFOUND if not found, GIT_EAMBIGUOUS if multiple + * matches were found, other value < 0 if there was a read error. + */ +GIT_EXTERN(int) git_odb_exists_prefix( + git_oid *out, git_odb *db, const git_oid *short_id, size_t len); + +/** + * The information about object IDs to query in `git_odb_expand_ids`, + * which will be populated upon return. + */ +typedef struct git_odb_expand_id { + /** The object ID to expand */ + git_oid id; + + /** + * The length of the object ID (in nibbles, or packets of 4 bits; the + * number of hex characters) + * */ + unsigned short length; + + /** + * The (optional) type of the object to search for; leave as `0` or set + * to `GIT_OBJECT_ANY` to query for any object matching the ID. + */ + git_object_t type; +} git_odb_expand_id; + +/** + * Determine if one or more objects can be found in the object database + * by their abbreviated object ID and type. + * + * The given array will be updated in place: for each abbreviated ID that is + * unique in the database, and of the given type (if specified), + * the full object ID, object ID length (`GIT_OID_SHA1_HEXSIZE`) and type will be + * written back to the array. For IDs that are not found (or are ambiguous), + * the array entry will be zeroed. + * + * Note that since this function operates on multiple objects, the + * underlying database will not be asked to be reloaded if an object is + * not found (which is unlike other object database operations.) + * + * @param db The database to be searched for the given objects. + * @param ids An array of short object IDs to search for + * @param count The length of the `ids` array + * @return 0 on success or an error code on failure + */ +GIT_EXTERN(int) git_odb_expand_ids( + git_odb *db, + git_odb_expand_id *ids, + size_t count); + +/** + * Refresh the object database to load newly added files. + * + * If the object databases have changed on disk while the library + * is running, this function will force a reload of the underlying + * indexes. + * + * Use this function when you're confident that an external + * application has tampered with the ODB. + * + * NOTE that it is not necessary to call this function at all. The + * library will automatically attempt to refresh the ODB + * when a lookup fails, to see if the looked up object exists + * on disk but hasn't been loaded yet. + * + * @param db database to refresh + * @return 0 on success, error code otherwise + */ +GIT_EXTERN(int) git_odb_refresh(struct git_odb *db); + +/** + * List all objects available in the database + * + * The callback will be called for each object available in the + * database. Note that the objects are likely to be returned in the index + * order, which would make accessing the objects in that order inefficient. + * Return a non-zero value from the callback to stop looping. + * + * @param db database to use + * @param cb the callback to call for each object + * @param payload data to pass to the callback + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payload); + +/** + * Write an object directly into the ODB + * + * This method writes a full object straight into the ODB. + * For most cases, it is preferred to write objects through a write + * stream, which is both faster and less memory intensive, specially + * for big objects. + * + * This method is provided for compatibility with custom backends + * which are not able to support streaming writes + * + * @param out pointer to store the OID result of the write + * @param odb object database where to store the object + * @param data buffer with the data to store + * @param len size of the buffer + * @param type type of the data to store + * @return 0 or an error code + */ +GIT_EXTERN(int) git_odb_write(git_oid *out, git_odb *odb, const void *data, size_t len, git_object_t type); + +/** + * Open a stream to write an object into the ODB + * + * The type and final length of the object must be specified + * when opening the stream. + * + * The returned stream will be of type `GIT_STREAM_WRONLY`, and it + * won't be effective until `git_odb_stream_finalize_write` is called + * and returns without an error + * + * The stream must always be freed when done with `git_odb_stream_free` or + * will leak memory. + * + * @see git_odb_stream + * + * @param out pointer where to store the stream + * @param db object database where the stream will write + * @param size final size of the object that will be written + * @param type type of the object that will be written + * @return 0 if the stream was created; error code otherwise + */ +GIT_EXTERN(int) git_odb_open_wstream(git_odb_stream **out, git_odb *db, git_object_size_t size, git_object_t type); + +/** + * Write to an odb stream + * + * This method will fail if the total number of received bytes exceeds the + * size declared with `git_odb_open_wstream()` + * + * @param stream the stream + * @param buffer the data to write + * @param len the buffer's length + * @return 0 if the write succeeded, error code otherwise + */ +GIT_EXTERN(int) git_odb_stream_write(git_odb_stream *stream, const char *buffer, size_t len); + +/** + * Finish writing to an odb stream + * + * The object will take its final name and will be available to the + * odb. + * + * This method will fail if the total number of received bytes + * differs from the size declared with `git_odb_open_wstream()` + * + * @param out pointer to store the resulting object's id + * @param stream the stream + * @return 0 on success, an error code otherwise + */ +GIT_EXTERN(int) git_odb_stream_finalize_write(git_oid *out, git_odb_stream *stream); + +/** + * Read from an odb stream + * + * Most backends don't implement streaming reads + * + * @param stream the stream + * @param buffer a user-allocated buffer to store the data in. + * @param len the buffer's length + * @return 0 if the read succeeded, error code otherwise + */ +GIT_EXTERN(int) git_odb_stream_read(git_odb_stream *stream, char *buffer, size_t len); + +/** + * Free an odb stream + * + * @param stream the stream to free + */ +GIT_EXTERN(void) git_odb_stream_free(git_odb_stream *stream); + +/** + * Open a stream to read an object from the ODB + * + * Note that most backends do *not* support streaming reads + * because they store their objects as compressed/delta'ed blobs. + * + * It's recommended to use `git_odb_read` instead, which is + * assured to work on all backends. + * + * The returned stream will be of type `GIT_STREAM_RDONLY` and + * will have the following methods: + * + * - stream->read: read `n` bytes from the stream + * - stream->free: free the stream + * + * The stream must always be free'd or will leak memory. + * + * @see git_odb_stream + * + * @param out pointer where to store the stream + * @param len pointer where to store the length of the object + * @param type pointer where to store the type of the object + * @param db object database where the stream will read from + * @param oid oid of the object the stream will read from + * @return 0 if the stream was created, error code otherwise + */ +GIT_EXTERN(int) git_odb_open_rstream( + git_odb_stream **out, + size_t *len, + git_object_t *type, + git_odb *db, + const git_oid *oid); + +/** + * Open a stream for writing a pack file to the ODB. + * + * If the ODB layer understands pack files, then the given + * packfile will likely be streamed directly to disk (and a + * corresponding index created). If the ODB layer does not + * understand pack files, the objects will be stored in whatever + * format the ODB layer uses. + * + * @see git_odb_writepack + * + * @param out pointer to the writepack functions + * @param db object database where the stream will read from + * @param progress_cb function to call with progress information. + * Be aware that this is called inline with network and indexing operations, + * so performance may be affected. + * @param progress_payload payload for the progress callback + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_odb_write_pack( + git_odb_writepack **out, + git_odb *db, + git_indexer_progress_cb progress_cb, + void *progress_payload); + +/** + * Write a `multi-pack-index` file from all the `.pack` files in the ODB. + * + * If the ODB layer understands pack files, then this will create a file called + * `multi-pack-index` next to the `.pack` and `.idx` files, which will contain + * an index of all objects stored in `.pack` files. This will allow for + * O(log n) lookup for n objects (regardless of how many packfiles there + * exist). + * + * @param db object database where the `multi-pack-index` file will be written. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_odb_write_multi_pack_index( + git_odb *db); + +/** + * Determine the object-ID (sha1 or sha256 hash) of a data buffer + * + * The resulting OID will be the identifier for the data buffer as if + * the data buffer it were to written to the ODB. + * + * @param out the resulting object-ID. + * @param data data to hash + * @param len size of the data + * @param object_type of the data to hash + * @param oid_type the oid type to hash to + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_odb_hash( + git_oid *out, + const void *data, + size_t len, + git_object_t object_type, + git_oid_t oid_type); +#else +GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_object_t type); +#endif + +/** + * Read a file from disk and fill a git_oid with the object id + * that the file would have if it were written to the Object + * Database as an object of the given type (w/o applying filters). + * Similar functionality to git.git's `git hash-object` without + * the `-w` flag, however, with the --no-filters flag. + * If you need filters, see git_repository_hashfile. + * + * @param out oid structure the result is written into. + * @param path file to read and determine object id for + * @param object_type of the data to hash + * @param oid_type the oid type to hash to + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_odb_hashfile( + git_oid *out, + const char *path, + git_object_t object_type, + git_oid_t oid_type); +#else +GIT_EXTERN(int) git_odb_hashfile(git_oid *out, const char *path, git_object_t type); +#endif + +/** + * Create a copy of an odb_object + * + * The returned copy must be manually freed with `git_odb_object_free`. + * Note that because of an implementation detail, the returned copy will be + * the same pointer as `source`: the object is internally refcounted, so the + * copy still needs to be freed twice. + * + * @param dest pointer where to store the copy + * @param source object to copy + * @return 0 or an error code + */ +GIT_EXTERN(int) git_odb_object_dup(git_odb_object **dest, git_odb_object *source); + +/** + * Close an ODB object + * + * This method must always be called once a `git_odb_object` is no + * longer needed, otherwise memory will leak. + * + * @param object object to close + */ +GIT_EXTERN(void) git_odb_object_free(git_odb_object *object); + +/** + * Return the OID of an ODB object + * + * This is the OID from which the object was read from + * + * @param object the object + * @return a pointer to the OID + */ +GIT_EXTERN(const git_oid *) git_odb_object_id(git_odb_object *object); + +/** + * Return the data of an ODB object + * + * This is the uncompressed, raw data as read from the ODB, + * without the leading header. + * + * This pointer is owned by the object and shall not be free'd. + * + * @param object the object + * @return a pointer to the data + */ +GIT_EXTERN(const void *) git_odb_object_data(git_odb_object *object); + +/** + * Return the size of an ODB object + * + * This is the real size of the `data` buffer, not the + * actual size of the object. + * + * @param object the object + * @return the size + */ +GIT_EXTERN(size_t) git_odb_object_size(git_odb_object *object); + +/** + * Return the type of an ODB object + * + * @param object the object + * @return the type + */ +GIT_EXTERN(git_object_t) git_odb_object_type(git_odb_object *object); + +/** + * Add a custom backend to an existing Object DB + * + * The backends are checked in relative ordering, based on the + * value of the `priority` parameter. + * + * Read for more information. + * + * @param odb database to add the backend to + * @param backend pointer to a git_odb_backend instance + * @param priority Value for ordering the backends queue + * @return 0 on success, error code otherwise + */ +GIT_EXTERN(int) git_odb_add_backend(git_odb *odb, git_odb_backend *backend, int priority); + +/** + * Add a custom backend to an existing Object DB; this + * backend will work as an alternate. + * + * Alternate backends are always checked for objects *after* + * all the main backends have been exhausted. + * + * The backends are checked in relative ordering, based on the + * value of the `priority` parameter. + * + * Writing is disabled on alternate backends. + * + * Read for more information. + * + * @param odb database to add the backend to + * @param backend pointer to a git_odb_backend instance + * @param priority Value for ordering the backends queue + * @return 0 on success, error code otherwise + */ +GIT_EXTERN(int) git_odb_add_alternate(git_odb *odb, git_odb_backend *backend, int priority); + +/** + * Get the number of ODB backend objects + * + * @param odb object database + * @return number of backends in the ODB + */ +GIT_EXTERN(size_t) git_odb_num_backends(git_odb *odb); + +/** + * Lookup an ODB backend object by index + * + * @param out output pointer to ODB backend at pos + * @param odb object database + * @param pos index into object database backend list + * @return 0 on success, GIT_ENOTFOUND if pos is invalid, other errors < 0 + */ +GIT_EXTERN(int) git_odb_get_backend(git_odb_backend **out, git_odb *odb, size_t pos); + +/** + * Set the git commit-graph for the ODB. + * + * After a successful call, the ownership of the cgraph parameter will be + * transferred to libgit2, and the caller should not free it. + * + * The commit-graph can also be unset by explicitly passing NULL as the cgraph + * parameter. + * + * @param odb object database + * @param cgraph the git commit-graph + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_odb_set_commit_graph(git_odb *odb, git_commit_graph *cgraph); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/odb_backend.h b/3rdparty/libgit2/include/git2/odb_backend.h index 12dd0fd..b793420 100644 --- a/3rdparty/libgit2/include/git2/odb_backend.h +++ b/3rdparty/libgit2/include/git2/odb_backend.h @@ -1,223 +1,223 @@ -/* - * 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_odb_backend_h__ -#define INCLUDE_git_odb_backend_h__ - -#include "common.h" -#include "types.h" -#include "indexer.h" - -/** - * @file git2/backend.h - * @brief Git custom backend functions - * @defgroup git_odb Git object database routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/* - * Constructors for in-box ODB backends. - */ - -/** Options for configuring a packfile object backend. */ -typedef struct { - unsigned int version; /**< version for the struct */ - - /** - * Type of object IDs to use for this object database, or - * 0 for default (currently SHA1). - */ - git_oid_t oid_type; -} git_odb_backend_pack_options; - -/* The current version of the diff options structure */ -#define GIT_ODB_BACKEND_PACK_OPTIONS_VERSION 1 - -/* Stack initializer for odb pack backend options. Alternatively use - * `git_odb_backend_pack_options_init` programmatic initialization. - */ -#define GIT_ODB_BACKEND_PACK_OPTIONS_INIT \ - { GIT_ODB_BACKEND_PACK_OPTIONS_VERSION } - -/** - * Create a backend for the packfiles. - * - * @param out location to store the odb backend pointer - * @param objects_dir the Git repository's objects directory - * - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_backend_pack( - git_odb_backend **out, - const char *objects_dir, - const git_odb_backend_pack_options *opts); -#else -GIT_EXTERN(int) git_odb_backend_pack( - git_odb_backend **out, - const char *objects_dir); -#endif - -/** - * Create a backend out of a single packfile - * - * This can be useful for inspecting the contents of a single - * packfile. - * - * @param out location to store the odb backend pointer - * @param index_file path to the packfile's .idx file - * - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_backend_one_pack( - git_odb_backend **out, - const char *index_file, - const git_odb_backend_pack_options *opts); -#else -GIT_EXTERN(int) git_odb_backend_one_pack( - git_odb_backend **out, - const char *index_file); -#endif - -typedef enum { - GIT_ODB_BACKEND_LOOSE_FSYNC = (1 << 0) -} git_odb_backend_loose_flag_t; - -/** Options for configuring a loose object backend. */ -typedef struct { - unsigned int version; /**< version for the struct */ - - /** A combination of the `git_odb_backend_loose_flag_t` types. */ - uint32_t flags; - - /** - * zlib compression level to use (0-9), where 1 is the fastest - * at the expense of larger files, and 9 produces the best - * compression at the expense of speed. 0 indicates that no - * compression should be performed. -1 is the default (currently - * optimizing for speed). - */ - int compression_level; - - /** Permissions to use creating a directory or 0 for defaults */ - unsigned int dir_mode; - - /** Permissions to use creating a file or 0 for defaults */ - unsigned int file_mode; - - /** - * Type of object IDs to use for this object database, or - * 0 for default (currently SHA1). - */ - git_oid_t oid_type; -} git_odb_backend_loose_options; - -/* The current version of the diff options structure */ -#define GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION 1 - -/* Stack initializer for odb loose backend options. Alternatively use - * `git_odb_backend_loose_options_init` programmatic initialization. - */ -#define GIT_ODB_BACKEND_LOOSE_OPTIONS_INIT \ - { GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION, 0, -1 } - -/** - * Create a backend for loose objects - * - * @param out location to store the odb backend pointer - * @param objects_dir the Git repository's objects directory - * @param opts options for the loose object backend or NULL - * - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_backend_loose( - git_odb_backend **out, - const char *objects_dir, - git_odb_backend_loose_options *opts); -#else -GIT_EXTERN(int) git_odb_backend_loose( - git_odb_backend **out, - const char *objects_dir, - int compression_level, - int do_fsync, - unsigned int dir_mode, - unsigned int file_mode); -#endif - -/** Streaming mode */ -typedef enum { - GIT_STREAM_RDONLY = (1 << 1), - GIT_STREAM_WRONLY = (1 << 2), - GIT_STREAM_RW = (GIT_STREAM_RDONLY | GIT_STREAM_WRONLY) -} git_odb_stream_t; - -/** - * A stream to read/write from a backend. - * - * This represents a stream of data being written to or read from a - * backend. When writing, the frontend functions take care of - * calculating the object's id and all `finalize_write` needs to do is - * store the object with the id it is passed. - */ -struct git_odb_stream { - git_odb_backend *backend; - unsigned int mode; - void *hash_ctx; - -#ifdef GIT_EXPERIMENTAL_SHA256 - git_oid_t oid_type; -#endif - - git_object_size_t declared_size; - git_object_size_t received_bytes; - - /** - * Write at most `len` bytes into `buffer` and advance the stream. - */ - int GIT_CALLBACK(read)(git_odb_stream *stream, char *buffer, size_t len); - - /** - * Write `len` bytes from `buffer` into the stream. - */ - int GIT_CALLBACK(write)(git_odb_stream *stream, const char *buffer, size_t len); - - /** - * Store the contents of the stream as an object with the id - * specified in `oid`. - * - * This method might not be invoked if: - * - an error occurs earlier with the `write` callback, - * - the object referred to by `oid` already exists in any backend, or - * - the final number of received bytes differs from the size declared - * with `git_odb_open_wstream()` - */ - int GIT_CALLBACK(finalize_write)(git_odb_stream *stream, const git_oid *oid); - - /** - * Free the stream's memory. - * - * This method might be called without a call to `finalize_write` if - * an error occurs or if the object is already present in the ODB. - */ - void GIT_CALLBACK(free)(git_odb_stream *stream); -}; - -/** A stream to write a pack file to the ODB */ -struct git_odb_writepack { - git_odb_backend *backend; - - int GIT_CALLBACK(append)(git_odb_writepack *writepack, const void *data, size_t size, git_indexer_progress *stats); - int GIT_CALLBACK(commit)(git_odb_writepack *writepack, git_indexer_progress *stats); - void GIT_CALLBACK(free)(git_odb_writepack *writepack); -}; - -GIT_END_DECL - -#endif +/* + * 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_odb_backend_h__ +#define INCLUDE_git_odb_backend_h__ + +#include "common.h" +#include "types.h" +#include "indexer.h" + +/** + * @file git2/backend.h + * @brief Git custom backend functions + * @defgroup git_odb Git object database routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/* + * Constructors for in-box ODB backends. + */ + +/** Options for configuring a packfile object backend. */ +typedef struct { + unsigned int version; /**< version for the struct */ + + /** + * Type of object IDs to use for this object database, or + * 0 for default (currently SHA1). + */ + git_oid_t oid_type; +} git_odb_backend_pack_options; + +/* The current version of the diff options structure */ +#define GIT_ODB_BACKEND_PACK_OPTIONS_VERSION 1 + +/* Stack initializer for odb pack backend options. Alternatively use + * `git_odb_backend_pack_options_init` programmatic initialization. + */ +#define GIT_ODB_BACKEND_PACK_OPTIONS_INIT \ + { GIT_ODB_BACKEND_PACK_OPTIONS_VERSION } + +/** + * Create a backend for the packfiles. + * + * @param out location to store the odb backend pointer + * @param objects_dir the Git repository's objects directory + * + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_odb_backend_pack( + git_odb_backend **out, + const char *objects_dir, + const git_odb_backend_pack_options *opts); +#else +GIT_EXTERN(int) git_odb_backend_pack( + git_odb_backend **out, + const char *objects_dir); +#endif + +/** + * Create a backend out of a single packfile + * + * This can be useful for inspecting the contents of a single + * packfile. + * + * @param out location to store the odb backend pointer + * @param index_file path to the packfile's .idx file + * + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_odb_backend_one_pack( + git_odb_backend **out, + const char *index_file, + const git_odb_backend_pack_options *opts); +#else +GIT_EXTERN(int) git_odb_backend_one_pack( + git_odb_backend **out, + const char *index_file); +#endif + +typedef enum { + GIT_ODB_BACKEND_LOOSE_FSYNC = (1 << 0) +} git_odb_backend_loose_flag_t; + +/** Options for configuring a loose object backend. */ +typedef struct { + unsigned int version; /**< version for the struct */ + + /** A combination of the `git_odb_backend_loose_flag_t` types. */ + uint32_t flags; + + /** + * zlib compression level to use (0-9), where 1 is the fastest + * at the expense of larger files, and 9 produces the best + * compression at the expense of speed. 0 indicates that no + * compression should be performed. -1 is the default (currently + * optimizing for speed). + */ + int compression_level; + + /** Permissions to use creating a directory or 0 for defaults */ + unsigned int dir_mode; + + /** Permissions to use creating a file or 0 for defaults */ + unsigned int file_mode; + + /** + * Type of object IDs to use for this object database, or + * 0 for default (currently SHA1). + */ + git_oid_t oid_type; +} git_odb_backend_loose_options; + +/* The current version of the diff options structure */ +#define GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION 1 + +/* Stack initializer for odb loose backend options. Alternatively use + * `git_odb_backend_loose_options_init` programmatic initialization. + */ +#define GIT_ODB_BACKEND_LOOSE_OPTIONS_INIT \ + { GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION, 0, -1 } + +/** + * Create a backend for loose objects + * + * @param out location to store the odb backend pointer + * @param objects_dir the Git repository's objects directory + * @param opts options for the loose object backend or NULL + * + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_odb_backend_loose( + git_odb_backend **out, + const char *objects_dir, + git_odb_backend_loose_options *opts); +#else +GIT_EXTERN(int) git_odb_backend_loose( + git_odb_backend **out, + const char *objects_dir, + int compression_level, + int do_fsync, + unsigned int dir_mode, + unsigned int file_mode); +#endif + +/** Streaming mode */ +typedef enum { + GIT_STREAM_RDONLY = (1 << 1), + GIT_STREAM_WRONLY = (1 << 2), + GIT_STREAM_RW = (GIT_STREAM_RDONLY | GIT_STREAM_WRONLY) +} git_odb_stream_t; + +/** + * A stream to read/write from a backend. + * + * This represents a stream of data being written to or read from a + * backend. When writing, the frontend functions take care of + * calculating the object's id and all `finalize_write` needs to do is + * store the object with the id it is passed. + */ +struct git_odb_stream { + git_odb_backend *backend; + unsigned int mode; + void *hash_ctx; + +#ifdef GIT_EXPERIMENTAL_SHA256 + git_oid_t oid_type; +#endif + + git_object_size_t declared_size; + git_object_size_t received_bytes; + + /** + * Write at most `len` bytes into `buffer` and advance the stream. + */ + int GIT_CALLBACK(read)(git_odb_stream *stream, char *buffer, size_t len); + + /** + * Write `len` bytes from `buffer` into the stream. + */ + int GIT_CALLBACK(write)(git_odb_stream *stream, const char *buffer, size_t len); + + /** + * Store the contents of the stream as an object with the id + * specified in `oid`. + * + * This method might not be invoked if: + * - an error occurs earlier with the `write` callback, + * - the object referred to by `oid` already exists in any backend, or + * - the final number of received bytes differs from the size declared + * with `git_odb_open_wstream()` + */ + int GIT_CALLBACK(finalize_write)(git_odb_stream *stream, const git_oid *oid); + + /** + * Free the stream's memory. + * + * This method might be called without a call to `finalize_write` if + * an error occurs or if the object is already present in the ODB. + */ + void GIT_CALLBACK(free)(git_odb_stream *stream); +}; + +/** A stream to write a pack file to the ODB */ +struct git_odb_writepack { + git_odb_backend *backend; + + int GIT_CALLBACK(append)(git_odb_writepack *writepack, const void *data, size_t size, git_indexer_progress *stats); + int GIT_CALLBACK(commit)(git_odb_writepack *writepack, git_indexer_progress *stats); + void GIT_CALLBACK(free)(git_odb_writepack *writepack); +}; + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/oid.h b/3rdparty/libgit2/include/git2/oid.h index 35b43ef..7d8432d 100644 --- a/3rdparty/libgit2/include/git2/oid.h +++ b/3rdparty/libgit2/include/git2/oid.h @@ -1,373 +1,373 @@ -/* - * 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_oid_h__ -#define INCLUDE_git_oid_h__ - -#include "common.h" -#include "types.h" -#include "experimental.h" - -/** - * @file git2/oid.h - * @brief Git object id routines - * @defgroup git_oid Git object id routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** The type of object id. */ -typedef enum { - -#ifdef GIT_EXPERIMENTAL_SHA256 - GIT_OID_SHA1 = 1, /**< SHA1 */ - GIT_OID_SHA256 = 2 /**< SHA256 */ -#else - GIT_OID_SHA1 = 1 /**< SHA1 */ -#endif - -} git_oid_t; - -/* - * SHA1 is currently the only supported object ID type. - */ - -/** SHA1 is currently libgit2's default oid type. */ -#define GIT_OID_DEFAULT GIT_OID_SHA1 - -/** Size (in bytes) of a raw/binary sha1 oid */ -#define GIT_OID_SHA1_SIZE 20 -/** Size (in bytes) of a hex formatted sha1 oid */ -#define GIT_OID_SHA1_HEXSIZE (GIT_OID_SHA1_SIZE * 2) - -/** - * The binary representation of the null sha1 object ID. - */ -#ifndef GIT_EXPERIMENTAL_SHA256 -# define GIT_OID_SHA1_ZERO { { 0 } } -#else -# define GIT_OID_SHA1_ZERO { GIT_OID_SHA1, { 0 } } -#endif - -/** - * The string representation of the null sha1 object ID. - */ -#define GIT_OID_SHA1_HEXZERO "0000000000000000000000000000000000000000" - -/* - * Experimental SHA256 support is a breaking change to the API. - * This exists for application compatibility testing. - */ - -#ifdef GIT_EXPERIMENTAL_SHA256 - -/** Size (in bytes) of a raw/binary sha256 oid */ -# define GIT_OID_SHA256_SIZE 32 -/** Size (in bytes) of a hex formatted sha256 oid */ -# define GIT_OID_SHA256_HEXSIZE (GIT_OID_SHA256_SIZE * 2) - -/** - * The binary representation of the null sha256 object ID. - */ -# define GIT_OID_SHA256_ZERO { GIT_OID_SHA256, { 0 } } - -/** - * The string representation of the null sha256 object ID. - */ -# define GIT_OID_SHA256_HEXZERO "0000000000000000000000000000000000000000000000000000000000000000" - -#endif - -/* Maximum possible object ID size in raw / hex string format. */ -#ifndef GIT_EXPERIMENTAL_SHA256 -# define GIT_OID_MAX_SIZE GIT_OID_SHA1_SIZE -# define GIT_OID_MAX_HEXSIZE GIT_OID_SHA1_HEXSIZE -#else -# define GIT_OID_MAX_SIZE GIT_OID_SHA256_SIZE -# define GIT_OID_MAX_HEXSIZE GIT_OID_SHA256_HEXSIZE -#endif - -/** Minimum length (in number of hex characters, - * i.e. packets of 4 bits) of an oid prefix */ -#define GIT_OID_MINPREFIXLEN 4 - -/** Unique identity of any object (commit, tree, blob, tag). */ -typedef struct git_oid { - -#ifdef GIT_EXPERIMENTAL_SHA256 - /** type of object id */ - unsigned char type; -#endif - - /** raw binary formatted id */ - unsigned char id[GIT_OID_MAX_SIZE]; -} git_oid; - -/** - * Parse a hex formatted object id into a git_oid. - * - * The appropriate number of bytes for the given object ID type will - * be read from the string - 40 bytes for SHA1, 64 bytes for SHA256. - * The given string need not be NUL terminated. - * - * @param out oid structure the result is written into. - * @param str input hex string; must be pointing at the start of - * the hex sequence and have at least the number of bytes - * needed for an oid encoded in hex (40 bytes for sha1, - * 256 bytes for sha256). - * @param type the type of object id - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str, git_oid_t type); -#else -GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str); -#endif - -/** - * Parse a hex formatted NUL-terminated string into a git_oid. - * - * @param out oid structure the result is written into. - * @param str input hex string; must be null-terminated. - * @param type the type of object id - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str, git_oid_t type); -#else -GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str); -#endif - -/** - * Parse N characters of a hex formatted object id into a git_oid. - * - * If N is odd, the last byte's high nibble will be read in and the - * low nibble set to zero. - * - * @param out oid structure the result is written into. - * @param str input hex string of at least size `length` - * @param length length of the input string - * @param type the type of object id - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length, git_oid_t type); -#else -GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length); -#endif - -/** - * Copy an already raw oid into a git_oid structure. - * - * @param out oid structure the result is written into. - * @param raw the raw input bytes to be copied. - * @return 0 on success or error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw, git_oid_t type); -#else -GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw); -#endif - -/** - * Format a git_oid into a hex string. - * - * @param out output hex string; must be pointing at the start of - * the hex sequence and have at least the number of bytes - * needed for an oid encoded in hex (40 bytes for SHA1, - * 64 bytes for SHA256). Only the oid digits are written; - * a '\\0' terminator must be added by the caller if it is - * required. - * @param id oid structure to format. - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_oid_fmt(char *out, const git_oid *id); - -/** - * Format a git_oid into a partial hex string. - * - * @param out output hex string; you say how many bytes to write. - * If the number of bytes is > GIT_OID_SHA1_HEXSIZE, extra bytes - * will be zeroed; if not, a '\0' terminator is NOT added. - * @param n number of characters to write into out string - * @param id oid structure to format. - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_oid_nfmt(char *out, size_t n, const git_oid *id); - -/** - * Format a git_oid into a loose-object path string. - * - * The resulting string is "aa/...", where "aa" is the first two - * hex digits of the oid and "..." is the remaining 38 digits. - * - * @param out output hex string; must be pointing at the start of - * the hex sequence and have at least the number of bytes - * needed for an oid encoded in hex (41 bytes for SHA1, - * 65 bytes for SHA256). Only the oid digits are written; - * a '\\0' terminator must be added by the caller if it - * is required. - * @param id oid structure to format. - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_oid_pathfmt(char *out, const git_oid *id); - -/** - * Format a git_oid into a statically allocated c-string. - * - * The c-string is owned by the library and should not be freed - * by the user. If libgit2 is built with thread support, the string - * will be stored in TLS (i.e. one buffer per thread) to allow for - * concurrent calls of the function. - * - * @param oid The oid structure to format - * @return the c-string or NULL on failure - */ -GIT_EXTERN(char *) git_oid_tostr_s(const git_oid *oid); - -/** - * Format a git_oid into a buffer as a hex format c-string. - * - * If the buffer is smaller than the size of a hex-formatted oid string - * plus an additional byte (GIT_OID_SHA_HEXSIZE + 1 for SHA1 or - * GIT_OID_SHA256_HEXSIZE + 1 for SHA256), then the resulting - * oid c-string will be truncated to n-1 characters (but will still be - * NUL-byte terminated). - * - * If there are any input parameter errors (out == NULL, n == 0, oid == - * NULL), then a pointer to an empty string is returned, so that the - * return value can always be printed. - * - * @param out the buffer into which the oid string is output. - * @param n the size of the out buffer. - * @param id the oid structure to format. - * @return the out buffer pointer, assuming no input parameter - * errors, otherwise a pointer to an empty string. - */ -GIT_EXTERN(char *) git_oid_tostr(char *out, size_t n, const git_oid *id); - -/** - * Copy an oid from one structure to another. - * - * @param out oid structure the result is written into. - * @param src oid structure to copy from. - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_oid_cpy(git_oid *out, const git_oid *src); - -/** - * Compare two oid structures. - * - * @param a first oid structure. - * @param b second oid structure. - * @return <0, 0, >0 if a < b, a == b, a > b. - */ -GIT_EXTERN(int) git_oid_cmp(const git_oid *a, const git_oid *b); - -/** - * Compare two oid structures for equality - * - * @param a first oid structure. - * @param b second oid structure. - * @return true if equal, false otherwise - */ -GIT_EXTERN(int) git_oid_equal(const git_oid *a, const git_oid *b); - -/** - * Compare the first 'len' hexadecimal characters (packets of 4 bits) - * of two oid structures. - * - * @param a first oid structure. - * @param b second oid structure. - * @param len the number of hex chars to compare - * @return 0 in case of a match - */ -GIT_EXTERN(int) git_oid_ncmp(const git_oid *a, const git_oid *b, size_t len); - -/** - * Check if an oid equals an hex formatted object id. - * - * @param id oid structure. - * @param str input hex string of an object id. - * @return 0 in case of a match, -1 otherwise. - */ -GIT_EXTERN(int) git_oid_streq(const git_oid *id, const char *str); - -/** - * Compare an oid to an hex formatted object id. - * - * @param id oid structure. - * @param str input hex string of an object id. - * @return -1 if str is not valid, <0 if id sorts before str, - * 0 if id matches str, >0 if id sorts after str. - */ -GIT_EXTERN(int) git_oid_strcmp(const git_oid *id, const char *str); - -/** - * Check is an oid is all zeros. - * - * @return 1 if all zeros, 0 otherwise. - */ -GIT_EXTERN(int) git_oid_is_zero(const git_oid *id); - -/** - * OID Shortener object - */ -typedef struct git_oid_shorten git_oid_shorten; - -/** - * Create a new OID shortener. - * - * The OID shortener is used to process a list of OIDs - * in text form and return the shortest length that would - * uniquely identify all of them. - * - * E.g. look at the result of `git log --abbrev`. - * - * @param min_length The minimal length for all identifiers, - * which will be used even if shorter OIDs would still - * be unique. - * @return a `git_oid_shorten` instance, NULL if OOM - */ -GIT_EXTERN(git_oid_shorten *) git_oid_shorten_new(size_t min_length); - -/** - * Add a new OID to set of shortened OIDs and calculate - * the minimal length to uniquely identify all the OIDs in - * the set. - * - * The OID is expected to be a 40-char hexadecimal string. - * The OID is owned by the user and will not be modified - * or freed. - * - * For performance reasons, there is a hard-limit of how many - * OIDs can be added to a single set (around ~32000, assuming - * a mostly randomized distribution), which should be enough - * for any kind of program, and keeps the algorithm fast and - * memory-efficient. - * - * Attempting to add more than those OIDs will result in a - * GIT_ERROR_INVALID error - * - * @param os a `git_oid_shorten` instance - * @param text_id an OID in text form - * @return the minimal length to uniquely identify all OIDs - * added so far to the set; or an error code (<0) if an - * error occurs. - */ -GIT_EXTERN(int) git_oid_shorten_add(git_oid_shorten *os, const char *text_id); - -/** - * Free an OID shortener instance - * - * @param os a `git_oid_shorten` instance - */ -GIT_EXTERN(void) git_oid_shorten_free(git_oid_shorten *os); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_oid_h__ +#define INCLUDE_git_oid_h__ + +#include "common.h" +#include "types.h" +#include "experimental.h" + +/** + * @file git2/oid.h + * @brief Git object id routines + * @defgroup git_oid Git object id routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** The type of object id. */ +typedef enum { + +#ifdef GIT_EXPERIMENTAL_SHA256 + GIT_OID_SHA1 = 1, /**< SHA1 */ + GIT_OID_SHA256 = 2 /**< SHA256 */ +#else + GIT_OID_SHA1 = 1 /**< SHA1 */ +#endif + +} git_oid_t; + +/* + * SHA1 is currently the only supported object ID type. + */ + +/** SHA1 is currently libgit2's default oid type. */ +#define GIT_OID_DEFAULT GIT_OID_SHA1 + +/** Size (in bytes) of a raw/binary sha1 oid */ +#define GIT_OID_SHA1_SIZE 20 +/** Size (in bytes) of a hex formatted sha1 oid */ +#define GIT_OID_SHA1_HEXSIZE (GIT_OID_SHA1_SIZE * 2) + +/** + * The binary representation of the null sha1 object ID. + */ +#ifndef GIT_EXPERIMENTAL_SHA256 +# define GIT_OID_SHA1_ZERO { { 0 } } +#else +# define GIT_OID_SHA1_ZERO { GIT_OID_SHA1, { 0 } } +#endif + +/** + * The string representation of the null sha1 object ID. + */ +#define GIT_OID_SHA1_HEXZERO "0000000000000000000000000000000000000000" + +/* + * Experimental SHA256 support is a breaking change to the API. + * This exists for application compatibility testing. + */ + +#ifdef GIT_EXPERIMENTAL_SHA256 + +/** Size (in bytes) of a raw/binary sha256 oid */ +# define GIT_OID_SHA256_SIZE 32 +/** Size (in bytes) of a hex formatted sha256 oid */ +# define GIT_OID_SHA256_HEXSIZE (GIT_OID_SHA256_SIZE * 2) + +/** + * The binary representation of the null sha256 object ID. + */ +# define GIT_OID_SHA256_ZERO { GIT_OID_SHA256, { 0 } } + +/** + * The string representation of the null sha256 object ID. + */ +# define GIT_OID_SHA256_HEXZERO "0000000000000000000000000000000000000000000000000000000000000000" + +#endif + +/* Maximum possible object ID size in raw / hex string format. */ +#ifndef GIT_EXPERIMENTAL_SHA256 +# define GIT_OID_MAX_SIZE GIT_OID_SHA1_SIZE +# define GIT_OID_MAX_HEXSIZE GIT_OID_SHA1_HEXSIZE +#else +# define GIT_OID_MAX_SIZE GIT_OID_SHA256_SIZE +# define GIT_OID_MAX_HEXSIZE GIT_OID_SHA256_HEXSIZE +#endif + +/** Minimum length (in number of hex characters, + * i.e. packets of 4 bits) of an oid prefix */ +#define GIT_OID_MINPREFIXLEN 4 + +/** Unique identity of any object (commit, tree, blob, tag). */ +typedef struct git_oid { + +#ifdef GIT_EXPERIMENTAL_SHA256 + /** type of object id */ + unsigned char type; +#endif + + /** raw binary formatted id */ + unsigned char id[GIT_OID_MAX_SIZE]; +} git_oid; + +/** + * Parse a hex formatted object id into a git_oid. + * + * The appropriate number of bytes for the given object ID type will + * be read from the string - 40 bytes for SHA1, 64 bytes for SHA256. + * The given string need not be NUL terminated. + * + * @param out oid structure the result is written into. + * @param str input hex string; must be pointing at the start of + * the hex sequence and have at least the number of bytes + * needed for an oid encoded in hex (40 bytes for sha1, + * 256 bytes for sha256). + * @param type the type of object id + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str, git_oid_t type); +#else +GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str); +#endif + +/** + * Parse a hex formatted NUL-terminated string into a git_oid. + * + * @param out oid structure the result is written into. + * @param str input hex string; must be null-terminated. + * @param type the type of object id + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str, git_oid_t type); +#else +GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str); +#endif + +/** + * Parse N characters of a hex formatted object id into a git_oid. + * + * If N is odd, the last byte's high nibble will be read in and the + * low nibble set to zero. + * + * @param out oid structure the result is written into. + * @param str input hex string of at least size `length` + * @param length length of the input string + * @param type the type of object id + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length, git_oid_t type); +#else +GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length); +#endif + +/** + * Copy an already raw oid into a git_oid structure. + * + * @param out oid structure the result is written into. + * @param raw the raw input bytes to be copied. + * @return 0 on success or error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw, git_oid_t type); +#else +GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw); +#endif + +/** + * Format a git_oid into a hex string. + * + * @param out output hex string; must be pointing at the start of + * the hex sequence and have at least the number of bytes + * needed for an oid encoded in hex (40 bytes for SHA1, + * 64 bytes for SHA256). Only the oid digits are written; + * a '\\0' terminator must be added by the caller if it is + * required. + * @param id oid structure to format. + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_oid_fmt(char *out, const git_oid *id); + +/** + * Format a git_oid into a partial hex string. + * + * @param out output hex string; you say how many bytes to write. + * If the number of bytes is > GIT_OID_SHA1_HEXSIZE, extra bytes + * will be zeroed; if not, a '\0' terminator is NOT added. + * @param n number of characters to write into out string + * @param id oid structure to format. + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_oid_nfmt(char *out, size_t n, const git_oid *id); + +/** + * Format a git_oid into a loose-object path string. + * + * The resulting string is "aa/...", where "aa" is the first two + * hex digits of the oid and "..." is the remaining 38 digits. + * + * @param out output hex string; must be pointing at the start of + * the hex sequence and have at least the number of bytes + * needed for an oid encoded in hex (41 bytes for SHA1, + * 65 bytes for SHA256). Only the oid digits are written; + * a '\\0' terminator must be added by the caller if it + * is required. + * @param id oid structure to format. + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_oid_pathfmt(char *out, const git_oid *id); + +/** + * Format a git_oid into a statically allocated c-string. + * + * The c-string is owned by the library and should not be freed + * by the user. If libgit2 is built with thread support, the string + * will be stored in TLS (i.e. one buffer per thread) to allow for + * concurrent calls of the function. + * + * @param oid The oid structure to format + * @return the c-string or NULL on failure + */ +GIT_EXTERN(char *) git_oid_tostr_s(const git_oid *oid); + +/** + * Format a git_oid into a buffer as a hex format c-string. + * + * If the buffer is smaller than the size of a hex-formatted oid string + * plus an additional byte (GIT_OID_SHA_HEXSIZE + 1 for SHA1 or + * GIT_OID_SHA256_HEXSIZE + 1 for SHA256), then the resulting + * oid c-string will be truncated to n-1 characters (but will still be + * NUL-byte terminated). + * + * If there are any input parameter errors (out == NULL, n == 0, oid == + * NULL), then a pointer to an empty string is returned, so that the + * return value can always be printed. + * + * @param out the buffer into which the oid string is output. + * @param n the size of the out buffer. + * @param id the oid structure to format. + * @return the out buffer pointer, assuming no input parameter + * errors, otherwise a pointer to an empty string. + */ +GIT_EXTERN(char *) git_oid_tostr(char *out, size_t n, const git_oid *id); + +/** + * Copy an oid from one structure to another. + * + * @param out oid structure the result is written into. + * @param src oid structure to copy from. + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_oid_cpy(git_oid *out, const git_oid *src); + +/** + * Compare two oid structures. + * + * @param a first oid structure. + * @param b second oid structure. + * @return <0, 0, >0 if a < b, a == b, a > b. + */ +GIT_EXTERN(int) git_oid_cmp(const git_oid *a, const git_oid *b); + +/** + * Compare two oid structures for equality + * + * @param a first oid structure. + * @param b second oid structure. + * @return true if equal, false otherwise + */ +GIT_EXTERN(int) git_oid_equal(const git_oid *a, const git_oid *b); + +/** + * Compare the first 'len' hexadecimal characters (packets of 4 bits) + * of two oid structures. + * + * @param a first oid structure. + * @param b second oid structure. + * @param len the number of hex chars to compare + * @return 0 in case of a match + */ +GIT_EXTERN(int) git_oid_ncmp(const git_oid *a, const git_oid *b, size_t len); + +/** + * Check if an oid equals an hex formatted object id. + * + * @param id oid structure. + * @param str input hex string of an object id. + * @return 0 in case of a match, -1 otherwise. + */ +GIT_EXTERN(int) git_oid_streq(const git_oid *id, const char *str); + +/** + * Compare an oid to an hex formatted object id. + * + * @param id oid structure. + * @param str input hex string of an object id. + * @return -1 if str is not valid, <0 if id sorts before str, + * 0 if id matches str, >0 if id sorts after str. + */ +GIT_EXTERN(int) git_oid_strcmp(const git_oid *id, const char *str); + +/** + * Check is an oid is all zeros. + * + * @return 1 if all zeros, 0 otherwise. + */ +GIT_EXTERN(int) git_oid_is_zero(const git_oid *id); + +/** + * OID Shortener object + */ +typedef struct git_oid_shorten git_oid_shorten; + +/** + * Create a new OID shortener. + * + * The OID shortener is used to process a list of OIDs + * in text form and return the shortest length that would + * uniquely identify all of them. + * + * E.g. look at the result of `git log --abbrev`. + * + * @param min_length The minimal length for all identifiers, + * which will be used even if shorter OIDs would still + * be unique. + * @return a `git_oid_shorten` instance, NULL if OOM + */ +GIT_EXTERN(git_oid_shorten *) git_oid_shorten_new(size_t min_length); + +/** + * Add a new OID to set of shortened OIDs and calculate + * the minimal length to uniquely identify all the OIDs in + * the set. + * + * The OID is expected to be a 40-char hexadecimal string. + * The OID is owned by the user and will not be modified + * or freed. + * + * For performance reasons, there is a hard-limit of how many + * OIDs can be added to a single set (around ~32000, assuming + * a mostly randomized distribution), which should be enough + * for any kind of program, and keeps the algorithm fast and + * memory-efficient. + * + * Attempting to add more than those OIDs will result in a + * GIT_ERROR_INVALID error + * + * @param os a `git_oid_shorten` instance + * @param text_id an OID in text form + * @return the minimal length to uniquely identify all OIDs + * added so far to the set; or an error code (<0) if an + * error occurs. + */ +GIT_EXTERN(int) git_oid_shorten_add(git_oid_shorten *os, const char *text_id); + +/** + * Free an OID shortener instance + * + * @param os a `git_oid_shorten` instance + */ +GIT_EXTERN(void) git_oid_shorten_free(git_oid_shorten *os); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/oidarray.h b/3rdparty/libgit2/include/git2/oidarray.h index 94fc58d..deba084 100644 --- a/3rdparty/libgit2/include/git2/oidarray.h +++ b/3rdparty/libgit2/include/git2/oidarray.h @@ -1,37 +1,37 @@ -/* - * 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_oidarray_h__ -#define INCLUDE_git_oidarray_h__ - -#include "common.h" -#include "oid.h" - -GIT_BEGIN_DECL - -/** Array of object ids */ -typedef struct git_oidarray { - git_oid *ids; - size_t count; -} git_oidarray; - -/** - * Free the object IDs contained in an oid_array. This method should - * be called on `git_oidarray` objects that were provided by the - * library. Not doing so will result in a memory leak. - * - * This does not free the `git_oidarray` itself, since the library will - * never allocate that object directly itself. - * - * @param array git_oidarray from which to free oid data - */ -GIT_EXTERN(void) git_oidarray_dispose(git_oidarray *array); - -/** @} */ -GIT_END_DECL - -#endif - +/* + * 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_oidarray_h__ +#define INCLUDE_git_oidarray_h__ + +#include "common.h" +#include "oid.h" + +GIT_BEGIN_DECL + +/** Array of object ids */ +typedef struct git_oidarray { + git_oid *ids; + size_t count; +} git_oidarray; + +/** + * Free the object IDs contained in an oid_array. This method should + * be called on `git_oidarray` objects that were provided by the + * library. Not doing so will result in a memory leak. + * + * This does not free the `git_oidarray` itself, since the library will + * never allocate that object directly itself. + * + * @param array git_oidarray from which to free oid data + */ +GIT_EXTERN(void) git_oidarray_dispose(git_oidarray *array); + +/** @} */ +GIT_END_DECL + +#endif + diff --git a/3rdparty/libgit2/include/git2/pack.h b/3rdparty/libgit2/include/git2/pack.h index 0f6bd2a..14f94a1 100644 --- a/3rdparty/libgit2/include/git2/pack.h +++ b/3rdparty/libgit2/include/git2/pack.h @@ -1,267 +1,267 @@ -/* - * 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_pack_h__ -#define INCLUDE_git_pack_h__ - -#include "common.h" -#include "oid.h" -#include "indexer.h" - -/** - * @file git2/pack.h - * @brief Git pack management routines - * - * Packing objects - * --------------- - * - * Creation of packfiles requires two steps: - * - * - First, insert all the objects you want to put into the packfile - * using `git_packbuilder_insert` and `git_packbuilder_insert_tree`. - * It's important to add the objects in recency order ("in the order - * that they are 'reachable' from head"). - * - * "ANY order will give you a working pack, ... [but it is] the thing - * that gives packs good locality. It keeps the objects close to the - * head (whether they are old or new, but they are _reachable_ from the - * head) at the head of the pack. So packs actually have absolutely - * _wonderful_ IO patterns." - Linus Torvalds - * git.git/Documentation/technical/pack-heuristics.txt - * - * - Second, use `git_packbuilder_write` or `git_packbuilder_foreach` to - * write the resulting packfile. - * - * libgit2 will take care of the delta ordering and generation. - * `git_packbuilder_set_threads` can be used to adjust the number of - * threads used for the process. - * - * See tests/pack/packbuilder.c for an example. - * - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Stages that are reported by the packbuilder progress callback. - */ -typedef enum { - GIT_PACKBUILDER_ADDING_OBJECTS = 0, - GIT_PACKBUILDER_DELTAFICATION = 1 -} git_packbuilder_stage_t; - -/** - * Initialize a new packbuilder - * - * @param out The new packbuilder object - * @param repo The repository - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_packbuilder_new(git_packbuilder **out, git_repository *repo); - -/** - * Set number of threads to spawn - * - * By default, libgit2 won't spawn any threads at all; - * when set to 0, libgit2 will autodetect the number of - * CPUs. - * - * @param pb The packbuilder - * @param n Number of threads to spawn - * @return number of actual threads to be used - */ -GIT_EXTERN(unsigned int) git_packbuilder_set_threads(git_packbuilder *pb, unsigned int n); - -/** - * Insert a single object - * - * For an optimal pack it's mandatory to insert objects in recency order, - * commits followed by trees and blobs. - * - * @param pb The packbuilder - * @param id The oid of the commit - * @param name The name; might be NULL - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_packbuilder_insert(git_packbuilder *pb, const git_oid *id, const char *name); - -/** - * Insert a root tree object - * - * This will add the tree as well as all referenced trees and blobs. - * - * @param pb The packbuilder - * @param id The oid of the root tree - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_packbuilder_insert_tree(git_packbuilder *pb, const git_oid *id); - -/** - * Insert a commit object - * - * This will add a commit as well as the completed referenced tree. - * - * @param pb The packbuilder - * @param id The oid of the commit - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_packbuilder_insert_commit(git_packbuilder *pb, const git_oid *id); - -/** - * Insert objects as given by the walk - * - * Those commits and all objects they reference will be inserted into - * the packbuilder. - * - * @param pb the packbuilder - * @param walk the revwalk to use to fill the packbuilder - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_packbuilder_insert_walk(git_packbuilder *pb, git_revwalk *walk); - -/** - * Recursively insert an object and its referenced objects - * - * Insert the object as well as any object it references. - * - * @param pb the packbuilder - * @param id the id of the root object to insert - * @param name optional name for the object - * @return 0 or an error code - */ -GIT_EXTERN(int) git_packbuilder_insert_recur(git_packbuilder *pb, const git_oid *id, const char *name); - -/** - * Write the contents of the packfile to an in-memory buffer - * - * The contents of the buffer will become a valid packfile, even though there - * will be no attached index - * - * @param buf Buffer where to write the packfile - * @param pb The packbuilder - * @return 0 or an error code - */ -GIT_EXTERN(int) git_packbuilder_write_buf(git_buf *buf, git_packbuilder *pb); - -/** - * Write the new pack and corresponding index file to path. - * - * @param pb The packbuilder - * @param path Path to the directory where the packfile and index should be stored, or NULL for default location - * @param mode permissions to use creating a packfile or 0 for defaults - * @param progress_cb function to call with progress information from the indexer (optional) - * @param progress_cb_payload payload for the progress callback (optional) - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_packbuilder_write( - git_packbuilder *pb, - const char *path, - unsigned int mode, - git_indexer_progress_cb progress_cb, - void *progress_cb_payload); - -#ifndef GIT_DEPRECATE_HARD -/** - * Get the packfile's hash - * - * A packfile's name is derived from the sorted hashing of all object - * names. This is only correct after the packfile has been written. - * - * @deprecated use git_packbuilder_name - * @param pb The packbuilder object - * @return 0 or an error code - */ -GIT_EXTERN(const git_oid *) git_packbuilder_hash(git_packbuilder *pb); -#endif - -/** - * Get the unique name for the resulting packfile. - * - * The packfile's name is derived from the packfile's content. - * This is only correct after the packfile has been written. - * - * @param pb the packbuilder instance - * @return a NUL terminated string for the packfile name - */ -GIT_EXTERN(const char *) git_packbuilder_name(git_packbuilder *pb); - -/** - * Callback used to iterate over packed objects - * - * @see git_packbuilder_foreach - * - * @param buf A pointer to the object's data - * @param size The size of the underlying object - * @param payload Payload passed to git_packbuilder_foreach - * @return non-zero to terminate the iteration - */ -typedef int GIT_CALLBACK(git_packbuilder_foreach_cb)(void *buf, size_t size, void *payload); - -/** - * Create the new pack and pass each object to the callback - * - * @param pb the packbuilder - * @param cb the callback to call with each packed object's buffer - * @param payload the callback's data - * @return 0 or an error code - */ -GIT_EXTERN(int) git_packbuilder_foreach(git_packbuilder *pb, git_packbuilder_foreach_cb cb, void *payload); - -/** - * Get the total number of objects the packbuilder will write out - * - * @param pb the packbuilder - * @return the number of objects in the packfile - */ -GIT_EXTERN(size_t) git_packbuilder_object_count(git_packbuilder *pb); - -/** - * Get the number of objects the packbuilder has already written out - * - * @param pb the packbuilder - * @return the number of objects which have already been written - */ -GIT_EXTERN(size_t) git_packbuilder_written(git_packbuilder *pb); - -/** Packbuilder progress notification function */ -typedef int GIT_CALLBACK(git_packbuilder_progress)( - int stage, - uint32_t current, - uint32_t total, - void *payload); - -/** - * Set the callbacks for a packbuilder - * - * @param pb The packbuilder object - * @param progress_cb Function to call with progress information during - * pack building. Be aware that this is called inline with pack building - * operations, so performance may be affected. - * @param progress_cb_payload Payload for progress callback. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_packbuilder_set_callbacks( - git_packbuilder *pb, - git_packbuilder_progress progress_cb, - void *progress_cb_payload); - -/** - * Free the packbuilder and all associated data - * - * @param pb The packbuilder - */ -GIT_EXTERN(void) git_packbuilder_free(git_packbuilder *pb); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_pack_h__ +#define INCLUDE_git_pack_h__ + +#include "common.h" +#include "oid.h" +#include "indexer.h" + +/** + * @file git2/pack.h + * @brief Git pack management routines + * + * Packing objects + * --------------- + * + * Creation of packfiles requires two steps: + * + * - First, insert all the objects you want to put into the packfile + * using `git_packbuilder_insert` and `git_packbuilder_insert_tree`. + * It's important to add the objects in recency order ("in the order + * that they are 'reachable' from head"). + * + * "ANY order will give you a working pack, ... [but it is] the thing + * that gives packs good locality. It keeps the objects close to the + * head (whether they are old or new, but they are _reachable_ from the + * head) at the head of the pack. So packs actually have absolutely + * _wonderful_ IO patterns." - Linus Torvalds + * git.git/Documentation/technical/pack-heuristics.txt + * + * - Second, use `git_packbuilder_write` or `git_packbuilder_foreach` to + * write the resulting packfile. + * + * libgit2 will take care of the delta ordering and generation. + * `git_packbuilder_set_threads` can be used to adjust the number of + * threads used for the process. + * + * See tests/pack/packbuilder.c for an example. + * + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Stages that are reported by the packbuilder progress callback. + */ +typedef enum { + GIT_PACKBUILDER_ADDING_OBJECTS = 0, + GIT_PACKBUILDER_DELTAFICATION = 1 +} git_packbuilder_stage_t; + +/** + * Initialize a new packbuilder + * + * @param out The new packbuilder object + * @param repo The repository + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_packbuilder_new(git_packbuilder **out, git_repository *repo); + +/** + * Set number of threads to spawn + * + * By default, libgit2 won't spawn any threads at all; + * when set to 0, libgit2 will autodetect the number of + * CPUs. + * + * @param pb The packbuilder + * @param n Number of threads to spawn + * @return number of actual threads to be used + */ +GIT_EXTERN(unsigned int) git_packbuilder_set_threads(git_packbuilder *pb, unsigned int n); + +/** + * Insert a single object + * + * For an optimal pack it's mandatory to insert objects in recency order, + * commits followed by trees and blobs. + * + * @param pb The packbuilder + * @param id The oid of the commit + * @param name The name; might be NULL + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_packbuilder_insert(git_packbuilder *pb, const git_oid *id, const char *name); + +/** + * Insert a root tree object + * + * This will add the tree as well as all referenced trees and blobs. + * + * @param pb The packbuilder + * @param id The oid of the root tree + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_packbuilder_insert_tree(git_packbuilder *pb, const git_oid *id); + +/** + * Insert a commit object + * + * This will add a commit as well as the completed referenced tree. + * + * @param pb The packbuilder + * @param id The oid of the commit + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_packbuilder_insert_commit(git_packbuilder *pb, const git_oid *id); + +/** + * Insert objects as given by the walk + * + * Those commits and all objects they reference will be inserted into + * the packbuilder. + * + * @param pb the packbuilder + * @param walk the revwalk to use to fill the packbuilder + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_packbuilder_insert_walk(git_packbuilder *pb, git_revwalk *walk); + +/** + * Recursively insert an object and its referenced objects + * + * Insert the object as well as any object it references. + * + * @param pb the packbuilder + * @param id the id of the root object to insert + * @param name optional name for the object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_packbuilder_insert_recur(git_packbuilder *pb, const git_oid *id, const char *name); + +/** + * Write the contents of the packfile to an in-memory buffer + * + * The contents of the buffer will become a valid packfile, even though there + * will be no attached index + * + * @param buf Buffer where to write the packfile + * @param pb The packbuilder + * @return 0 or an error code + */ +GIT_EXTERN(int) git_packbuilder_write_buf(git_buf *buf, git_packbuilder *pb); + +/** + * Write the new pack and corresponding index file to path. + * + * @param pb The packbuilder + * @param path Path to the directory where the packfile and index should be stored, or NULL for default location + * @param mode permissions to use creating a packfile or 0 for defaults + * @param progress_cb function to call with progress information from the indexer (optional) + * @param progress_cb_payload payload for the progress callback (optional) + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_packbuilder_write( + git_packbuilder *pb, + const char *path, + unsigned int mode, + git_indexer_progress_cb progress_cb, + void *progress_cb_payload); + +#ifndef GIT_DEPRECATE_HARD +/** + * Get the packfile's hash + * + * A packfile's name is derived from the sorted hashing of all object + * names. This is only correct after the packfile has been written. + * + * @deprecated use git_packbuilder_name + * @param pb The packbuilder object + * @return 0 or an error code + */ +GIT_EXTERN(const git_oid *) git_packbuilder_hash(git_packbuilder *pb); +#endif + +/** + * Get the unique name for the resulting packfile. + * + * The packfile's name is derived from the packfile's content. + * This is only correct after the packfile has been written. + * + * @param pb the packbuilder instance + * @return a NUL terminated string for the packfile name + */ +GIT_EXTERN(const char *) git_packbuilder_name(git_packbuilder *pb); + +/** + * Callback used to iterate over packed objects + * + * @see git_packbuilder_foreach + * + * @param buf A pointer to the object's data + * @param size The size of the underlying object + * @param payload Payload passed to git_packbuilder_foreach + * @return non-zero to terminate the iteration + */ +typedef int GIT_CALLBACK(git_packbuilder_foreach_cb)(void *buf, size_t size, void *payload); + +/** + * Create the new pack and pass each object to the callback + * + * @param pb the packbuilder + * @param cb the callback to call with each packed object's buffer + * @param payload the callback's data + * @return 0 or an error code + */ +GIT_EXTERN(int) git_packbuilder_foreach(git_packbuilder *pb, git_packbuilder_foreach_cb cb, void *payload); + +/** + * Get the total number of objects the packbuilder will write out + * + * @param pb the packbuilder + * @return the number of objects in the packfile + */ +GIT_EXTERN(size_t) git_packbuilder_object_count(git_packbuilder *pb); + +/** + * Get the number of objects the packbuilder has already written out + * + * @param pb the packbuilder + * @return the number of objects which have already been written + */ +GIT_EXTERN(size_t) git_packbuilder_written(git_packbuilder *pb); + +/** Packbuilder progress notification function */ +typedef int GIT_CALLBACK(git_packbuilder_progress)( + int stage, + uint32_t current, + uint32_t total, + void *payload); + +/** + * Set the callbacks for a packbuilder + * + * @param pb The packbuilder object + * @param progress_cb Function to call with progress information during + * pack building. Be aware that this is called inline with pack building + * operations, so performance may be affected. + * @param progress_cb_payload Payload for progress callback. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_packbuilder_set_callbacks( + git_packbuilder *pb, + git_packbuilder_progress progress_cb, + void *progress_cb_payload); + +/** + * Free the packbuilder and all associated data + * + * @param pb The packbuilder + */ +GIT_EXTERN(void) git_packbuilder_free(git_packbuilder *pb); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/patch.h b/3rdparty/libgit2/include/git2/patch.h index 9cf758a..8a1586b 100644 --- a/3rdparty/libgit2/include/git2/patch.h +++ b/3rdparty/libgit2/include/git2/patch.h @@ -1,290 +1,290 @@ -/* - * 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_patch_h__ -#define INCLUDE_git_patch_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "diff.h" - -/** - * @file git2/patch.h - * @brief Patch handling routines. - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * The diff patch is used to store all the text diffs for a delta. - * - * You can easily loop over the content of patches and get information about - * them. - */ -typedef struct git_patch git_patch; - -/** - * Get the repository associated with this patch. May be NULL. - * - * @param patch the patch - * @return a pointer to the repository - */ -GIT_EXTERN(git_repository *) git_patch_owner(const git_patch *patch); - -/** - * Return a patch for an entry in the diff list. - * - * The `git_patch` is a newly created object contains the text diffs - * for the delta. You have to call `git_patch_free()` when you are - * done with it. You can use the patch object to loop over all the hunks - * and lines in the diff of the one delta. - * - * For an unchanged file or a binary file, no `git_patch` will be - * created, the output will be set to NULL, and the `binary` flag will be - * set true in the `git_diff_delta` structure. - * - * It is okay to pass NULL for either of the output parameters; if you pass - * NULL for the `git_patch`, then the text diff will not be calculated. - * - * @param out Output parameter for the delta patch object - * @param diff Diff list object - * @param idx Index into diff list - * @return 0 on success, other value < 0 on error - */ -GIT_EXTERN(int) git_patch_from_diff( - git_patch **out, git_diff *diff, size_t idx); - -/** - * Directly generate a patch from the difference between two blobs. - * - * This is just like `git_diff_blobs()` except it generates a patch object - * for the difference instead of directly making callbacks. You can use the - * standard `git_patch` accessor functions to read the patch data, and - * you must call `git_patch_free()` on the patch when done. - * - * @param out The generated patch; NULL on error - * @param old_blob Blob for old side of diff, or NULL for empty blob - * @param old_as_path Treat old blob as if it had this filename; can be NULL - * @param new_blob Blob for new side of diff, or NULL for empty blob - * @param new_as_path Treat new blob as if it had this filename; can be NULL - * @param opts Options for diff, or NULL for default options - * @return 0 on success or error code < 0 - */ -GIT_EXTERN(int) git_patch_from_blobs( - git_patch **out, - const git_blob *old_blob, - const char *old_as_path, - const git_blob *new_blob, - const char *new_as_path, - const git_diff_options *opts); - -/** - * Directly generate a patch from the difference between a blob and a buffer. - * - * This is just like `git_diff_blob_to_buffer()` except it generates a patch - * object for the difference instead of directly making callbacks. You can - * use the standard `git_patch` accessor functions to read the patch - * data, and you must call `git_patch_free()` on the patch when done. - * - * @param out The generated patch; NULL on error - * @param old_blob Blob for old side of diff, or NULL for empty blob - * @param old_as_path Treat old blob as if it had this filename; can be NULL - * @param buffer Raw data for new side of diff, or NULL for empty - * @param buffer_len Length of raw data for new side of diff - * @param buffer_as_path Treat buffer as if it had this filename; can be NULL - * @param opts Options for diff, or NULL for default options - * @return 0 on success or error code < 0 - */ -GIT_EXTERN(int) git_patch_from_blob_and_buffer( - git_patch **out, - const git_blob *old_blob, - const char *old_as_path, - const void *buffer, - size_t buffer_len, - const char *buffer_as_path, - const git_diff_options *opts); - -/** - * Directly generate a patch from the difference between two buffers. - * - * This is just like `git_diff_buffers()` except it generates a patch - * object for the difference instead of directly making callbacks. You can - * use the standard `git_patch` accessor functions to read the patch - * data, and you must call `git_patch_free()` on the patch when done. - * - * @param out The generated patch; NULL on error - * @param old_buffer Raw data for old side of diff, or NULL for empty - * @param old_len Length of the raw data for old side of the diff - * @param old_as_path Treat old buffer as if it had this filename; can be NULL - * @param new_buffer Raw data for new side of diff, or NULL for empty - * @param new_len Length of raw data for new side of diff - * @param new_as_path Treat buffer as if it had this filename; can be NULL - * @param opts Options for diff, or NULL for default options - * @return 0 on success or error code < 0 - */ -GIT_EXTERN(int) git_patch_from_buffers( - git_patch **out, - const void *old_buffer, - size_t old_len, - const char *old_as_path, - const void *new_buffer, - size_t new_len, - const char *new_as_path, - const git_diff_options *opts); - -/** - * Free a git_patch object. - * - * @param patch The patch to free. - */ -GIT_EXTERN(void) git_patch_free(git_patch *patch); - -/** - * Get the delta associated with a patch. This delta points to internal - * data and you do not have to release it when you are done with it. - * - * @param patch The patch in which to get the delta. - * @return The delta associated with the patch. - */ -GIT_EXTERN(const git_diff_delta *) git_patch_get_delta(const git_patch *patch); - -/** - * Get the number of hunks in a patch - * - * @param patch The patch in which to get the number of hunks. - * @return The number of hunks of the patch. - */ -GIT_EXTERN(size_t) git_patch_num_hunks(const git_patch *patch); - -/** - * Get line counts of each type in a patch. - * - * This helps imitate a diff --numstat type of output. For that purpose, - * you only need the `total_additions` and `total_deletions` values, but we - * include the `total_context` line count in case you want the total number - * of lines of diff output that will be generated. - * - * All outputs are optional. Pass NULL if you don't need a particular count. - * - * @param total_context Count of context lines in output, can be NULL. - * @param total_additions Count of addition lines in output, can be NULL. - * @param total_deletions Count of deletion lines in output, can be NULL. - * @param patch The git_patch object - * @return 0 on success, <0 on error - */ -GIT_EXTERN(int) git_patch_line_stats( - size_t *total_context, - size_t *total_additions, - size_t *total_deletions, - const git_patch *patch); - -/** - * Get the information about a hunk in a patch - * - * Given a patch and a hunk index into the patch, this returns detailed - * information about that hunk. Any of the output pointers can be passed - * as NULL if you don't care about that particular piece of information. - * - * @param out Output pointer to git_diff_hunk of hunk - * @param lines_in_hunk Output count of total lines in this hunk - * @param patch Input pointer to patch object - * @param hunk_idx Input index of hunk to get information about - * @return 0 on success, GIT_ENOTFOUND if hunk_idx out of range, <0 on error - */ -GIT_EXTERN(int) git_patch_get_hunk( - const git_diff_hunk **out, - size_t *lines_in_hunk, - git_patch *patch, - size_t hunk_idx); - -/** - * Get the number of lines in a hunk. - * - * @param patch The git_patch object - * @param hunk_idx Index of the hunk - * @return Number of lines in hunk or GIT_ENOTFOUND if invalid hunk index - */ -GIT_EXTERN(int) git_patch_num_lines_in_hunk( - const git_patch *patch, - size_t hunk_idx); - -/** - * Get data about a line in a hunk of a patch. - * - * Given a patch, a hunk index, and a line index in the hunk, this - * will return a lot of details about that line. If you pass a hunk - * index larger than the number of hunks or a line index larger than - * the number of lines in the hunk, this will return -1. - * - * @param out The git_diff_line data for this line - * @param patch The patch to look in - * @param hunk_idx The index of the hunk - * @param line_of_hunk The index of the line in the hunk - * @return 0 on success, <0 on failure - */ -GIT_EXTERN(int) git_patch_get_line_in_hunk( - const git_diff_line **out, - git_patch *patch, - size_t hunk_idx, - size_t line_of_hunk); - -/** - * Look up size of patch diff data in bytes - * - * This returns the raw size of the patch data. This only includes the - * actual data from the lines of the diff, not the file or hunk headers. - * - * If you pass `include_context` as true (non-zero), this will be the size - * of all of the diff output; if you pass it as false (zero), this will - * only include the actual changed lines (as if `context_lines` was 0). - * - * @param patch A git_patch representing changes to one file - * @param include_context Include context lines in size if non-zero - * @param include_hunk_headers Include hunk header lines if non-zero - * @param include_file_headers Include file header lines if non-zero - * @return The number of bytes of data - */ -GIT_EXTERN(size_t) git_patch_size( - git_patch *patch, - int include_context, - int include_hunk_headers, - int include_file_headers); - -/** - * Serialize the patch to text via callback. - * - * Returning a non-zero value from the callback will terminate the iteration - * and return that value to the caller. - * - * @param patch A git_patch representing changes to one file - * @param print_cb Callback function to output lines of the patch. Will be - * called for file headers, hunk headers, and diff lines. - * @param payload Reference pointer that will be passed to your callbacks. - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_patch_print( - git_patch *patch, - git_diff_line_cb print_cb, - void *payload); - -/** - * Get the content of a patch as a single diff text. - * - * @param out The git_buf to be filled in - * @param patch A git_patch representing changes to one file - * @return 0 on success, <0 on failure. - */ -GIT_EXTERN(int) git_patch_to_buf( - git_buf *out, - git_patch *patch); - -GIT_END_DECL - -/**@}*/ - -#endif +/* + * 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_patch_h__ +#define INCLUDE_git_patch_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "diff.h" + +/** + * @file git2/patch.h + * @brief Patch handling routines. + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * The diff patch is used to store all the text diffs for a delta. + * + * You can easily loop over the content of patches and get information about + * them. + */ +typedef struct git_patch git_patch; + +/** + * Get the repository associated with this patch. May be NULL. + * + * @param patch the patch + * @return a pointer to the repository + */ +GIT_EXTERN(git_repository *) git_patch_owner(const git_patch *patch); + +/** + * Return a patch for an entry in the diff list. + * + * The `git_patch` is a newly created object contains the text diffs + * for the delta. You have to call `git_patch_free()` when you are + * done with it. You can use the patch object to loop over all the hunks + * and lines in the diff of the one delta. + * + * For an unchanged file or a binary file, no `git_patch` will be + * created, the output will be set to NULL, and the `binary` flag will be + * set true in the `git_diff_delta` structure. + * + * It is okay to pass NULL for either of the output parameters; if you pass + * NULL for the `git_patch`, then the text diff will not be calculated. + * + * @param out Output parameter for the delta patch object + * @param diff Diff list object + * @param idx Index into diff list + * @return 0 on success, other value < 0 on error + */ +GIT_EXTERN(int) git_patch_from_diff( + git_patch **out, git_diff *diff, size_t idx); + +/** + * Directly generate a patch from the difference between two blobs. + * + * This is just like `git_diff_blobs()` except it generates a patch object + * for the difference instead of directly making callbacks. You can use the + * standard `git_patch` accessor functions to read the patch data, and + * you must call `git_patch_free()` on the patch when done. + * + * @param out The generated patch; NULL on error + * @param old_blob Blob for old side of diff, or NULL for empty blob + * @param old_as_path Treat old blob as if it had this filename; can be NULL + * @param new_blob Blob for new side of diff, or NULL for empty blob + * @param new_as_path Treat new blob as if it had this filename; can be NULL + * @param opts Options for diff, or NULL for default options + * @return 0 on success or error code < 0 + */ +GIT_EXTERN(int) git_patch_from_blobs( + git_patch **out, + const git_blob *old_blob, + const char *old_as_path, + const git_blob *new_blob, + const char *new_as_path, + const git_diff_options *opts); + +/** + * Directly generate a patch from the difference between a blob and a buffer. + * + * This is just like `git_diff_blob_to_buffer()` except it generates a patch + * object for the difference instead of directly making callbacks. You can + * use the standard `git_patch` accessor functions to read the patch + * data, and you must call `git_patch_free()` on the patch when done. + * + * @param out The generated patch; NULL on error + * @param old_blob Blob for old side of diff, or NULL for empty blob + * @param old_as_path Treat old blob as if it had this filename; can be NULL + * @param buffer Raw data for new side of diff, or NULL for empty + * @param buffer_len Length of raw data for new side of diff + * @param buffer_as_path Treat buffer as if it had this filename; can be NULL + * @param opts Options for diff, or NULL for default options + * @return 0 on success or error code < 0 + */ +GIT_EXTERN(int) git_patch_from_blob_and_buffer( + git_patch **out, + const git_blob *old_blob, + const char *old_as_path, + const void *buffer, + size_t buffer_len, + const char *buffer_as_path, + const git_diff_options *opts); + +/** + * Directly generate a patch from the difference between two buffers. + * + * This is just like `git_diff_buffers()` except it generates a patch + * object for the difference instead of directly making callbacks. You can + * use the standard `git_patch` accessor functions to read the patch + * data, and you must call `git_patch_free()` on the patch when done. + * + * @param out The generated patch; NULL on error + * @param old_buffer Raw data for old side of diff, or NULL for empty + * @param old_len Length of the raw data for old side of the diff + * @param old_as_path Treat old buffer as if it had this filename; can be NULL + * @param new_buffer Raw data for new side of diff, or NULL for empty + * @param new_len Length of raw data for new side of diff + * @param new_as_path Treat buffer as if it had this filename; can be NULL + * @param opts Options for diff, or NULL for default options + * @return 0 on success or error code < 0 + */ +GIT_EXTERN(int) git_patch_from_buffers( + git_patch **out, + const void *old_buffer, + size_t old_len, + const char *old_as_path, + const void *new_buffer, + size_t new_len, + const char *new_as_path, + const git_diff_options *opts); + +/** + * Free a git_patch object. + * + * @param patch The patch to free. + */ +GIT_EXTERN(void) git_patch_free(git_patch *patch); + +/** + * Get the delta associated with a patch. This delta points to internal + * data and you do not have to release it when you are done with it. + * + * @param patch The patch in which to get the delta. + * @return The delta associated with the patch. + */ +GIT_EXTERN(const git_diff_delta *) git_patch_get_delta(const git_patch *patch); + +/** + * Get the number of hunks in a patch + * + * @param patch The patch in which to get the number of hunks. + * @return The number of hunks of the patch. + */ +GIT_EXTERN(size_t) git_patch_num_hunks(const git_patch *patch); + +/** + * Get line counts of each type in a patch. + * + * This helps imitate a diff --numstat type of output. For that purpose, + * you only need the `total_additions` and `total_deletions` values, but we + * include the `total_context` line count in case you want the total number + * of lines of diff output that will be generated. + * + * All outputs are optional. Pass NULL if you don't need a particular count. + * + * @param total_context Count of context lines in output, can be NULL. + * @param total_additions Count of addition lines in output, can be NULL. + * @param total_deletions Count of deletion lines in output, can be NULL. + * @param patch The git_patch object + * @return 0 on success, <0 on error + */ +GIT_EXTERN(int) git_patch_line_stats( + size_t *total_context, + size_t *total_additions, + size_t *total_deletions, + const git_patch *patch); + +/** + * Get the information about a hunk in a patch + * + * Given a patch and a hunk index into the patch, this returns detailed + * information about that hunk. Any of the output pointers can be passed + * as NULL if you don't care about that particular piece of information. + * + * @param out Output pointer to git_diff_hunk of hunk + * @param lines_in_hunk Output count of total lines in this hunk + * @param patch Input pointer to patch object + * @param hunk_idx Input index of hunk to get information about + * @return 0 on success, GIT_ENOTFOUND if hunk_idx out of range, <0 on error + */ +GIT_EXTERN(int) git_patch_get_hunk( + const git_diff_hunk **out, + size_t *lines_in_hunk, + git_patch *patch, + size_t hunk_idx); + +/** + * Get the number of lines in a hunk. + * + * @param patch The git_patch object + * @param hunk_idx Index of the hunk + * @return Number of lines in hunk or GIT_ENOTFOUND if invalid hunk index + */ +GIT_EXTERN(int) git_patch_num_lines_in_hunk( + const git_patch *patch, + size_t hunk_idx); + +/** + * Get data about a line in a hunk of a patch. + * + * Given a patch, a hunk index, and a line index in the hunk, this + * will return a lot of details about that line. If you pass a hunk + * index larger than the number of hunks or a line index larger than + * the number of lines in the hunk, this will return -1. + * + * @param out The git_diff_line data for this line + * @param patch The patch to look in + * @param hunk_idx The index of the hunk + * @param line_of_hunk The index of the line in the hunk + * @return 0 on success, <0 on failure + */ +GIT_EXTERN(int) git_patch_get_line_in_hunk( + const git_diff_line **out, + git_patch *patch, + size_t hunk_idx, + size_t line_of_hunk); + +/** + * Look up size of patch diff data in bytes + * + * This returns the raw size of the patch data. This only includes the + * actual data from the lines of the diff, not the file or hunk headers. + * + * If you pass `include_context` as true (non-zero), this will be the size + * of all of the diff output; if you pass it as false (zero), this will + * only include the actual changed lines (as if `context_lines` was 0). + * + * @param patch A git_patch representing changes to one file + * @param include_context Include context lines in size if non-zero + * @param include_hunk_headers Include hunk header lines if non-zero + * @param include_file_headers Include file header lines if non-zero + * @return The number of bytes of data + */ +GIT_EXTERN(size_t) git_patch_size( + git_patch *patch, + int include_context, + int include_hunk_headers, + int include_file_headers); + +/** + * Serialize the patch to text via callback. + * + * Returning a non-zero value from the callback will terminate the iteration + * and return that value to the caller. + * + * @param patch A git_patch representing changes to one file + * @param print_cb Callback function to output lines of the patch. Will be + * called for file headers, hunk headers, and diff lines. + * @param payload Reference pointer that will be passed to your callbacks. + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_patch_print( + git_patch *patch, + git_diff_line_cb print_cb, + void *payload); + +/** + * Get the content of a patch as a single diff text. + * + * @param out The git_buf to be filled in + * @param patch A git_patch representing changes to one file + * @return 0 on success, <0 on failure. + */ +GIT_EXTERN(int) git_patch_to_buf( + git_buf *out, + git_patch *patch); + +GIT_END_DECL + +/**@}*/ + +#endif diff --git a/3rdparty/libgit2/include/git2/pathspec.h b/3rdparty/libgit2/include/git2/pathspec.h index acbd5cd..34512bf 100644 --- a/3rdparty/libgit2/include/git2/pathspec.h +++ b/3rdparty/libgit2/include/git2/pathspec.h @@ -1,280 +1,280 @@ -/* - * 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_pathspec_h__ -#define INCLUDE_git_pathspec_h__ - -#include "common.h" -#include "types.h" -#include "strarray.h" -#include "diff.h" - -GIT_BEGIN_DECL - -/** - * Compiled pathspec - */ -typedef struct git_pathspec git_pathspec; - -/** - * List of filenames matching a pathspec - */ -typedef struct git_pathspec_match_list git_pathspec_match_list; - -/** - * Options controlling how pathspec match should be executed - */ -typedef enum { - GIT_PATHSPEC_DEFAULT = 0, - - /** - * GIT_PATHSPEC_IGNORE_CASE forces match to ignore case; otherwise - * match will use native case sensitivity of platform filesystem - */ - GIT_PATHSPEC_IGNORE_CASE = (1u << 0), - - /** - * GIT_PATHSPEC_USE_CASE forces case sensitive match; otherwise - * match will use native case sensitivity of platform filesystem - */ - GIT_PATHSPEC_USE_CASE = (1u << 1), - - /** - * GIT_PATHSPEC_NO_GLOB disables glob patterns and just uses simple - * string comparison for matching - */ - GIT_PATHSPEC_NO_GLOB = (1u << 2), - - /** - * GIT_PATHSPEC_NO_MATCH_ERROR means the match functions return error - * code GIT_ENOTFOUND if no matches are found; otherwise no matches is - * still success (return 0) but `git_pathspec_match_list_entrycount` - * will indicate 0 matches. - */ - GIT_PATHSPEC_NO_MATCH_ERROR = (1u << 3), - - /** - * GIT_PATHSPEC_FIND_FAILURES means that the `git_pathspec_match_list` - * should track which patterns matched which files so that at the end of - * the match we can identify patterns that did not match any files. - */ - GIT_PATHSPEC_FIND_FAILURES = (1u << 4), - - /** - * GIT_PATHSPEC_FAILURES_ONLY means that the `git_pathspec_match_list` - * does not need to keep the actual matching filenames. Use this to - * just test if there were any matches at all or in combination with - * GIT_PATHSPEC_FIND_FAILURES to validate a pathspec. - */ - GIT_PATHSPEC_FAILURES_ONLY = (1u << 5) -} git_pathspec_flag_t; - -/** - * Compile a pathspec - * - * @param out Output of the compiled pathspec - * @param pathspec A git_strarray of the paths to match - * @return 0 on success, <0 on failure - */ -GIT_EXTERN(int) git_pathspec_new( - git_pathspec **out, const git_strarray *pathspec); - -/** - * Free a pathspec - * - * @param ps The compiled pathspec - */ -GIT_EXTERN(void) git_pathspec_free(git_pathspec *ps); - -/** - * Try to match a path against a pathspec - * - * Unlike most of the other pathspec matching functions, this will not - * fall back on the native case-sensitivity for your platform. You must - * explicitly pass flags to control case sensitivity or else this will - * fall back on being case sensitive. - * - * @param ps The compiled pathspec - * @param flags Combination of git_pathspec_flag_t options to control match - * @param path The pathname to attempt to match - * @return 1 is path matches spec, 0 if it does not - */ -GIT_EXTERN(int) git_pathspec_matches_path( - const git_pathspec *ps, uint32_t flags, const char *path); - -/** - * Match a pathspec against the working directory of a repository. - * - * This matches the pathspec against the current files in the working - * directory of the repository. It is an error to invoke this on a bare - * repo. This handles git ignores (i.e. ignored files will not be - * considered to match the `pathspec` unless the file is tracked in the - * index). - * - * If `out` is not NULL, this returns a `git_patchspec_match_list`. That - * contains the list of all matched filenames (unless you pass the - * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of - * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` - * flag). You must call `git_pathspec_match_list_free()` on this object. - * - * @param out Output list of matches; pass NULL to just get return value - * @param repo The repository in which to match; bare repo is an error - * @param flags Combination of git_pathspec_flag_t options to control match - * @param ps Pathspec to be matched - * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and - * the GIT_PATHSPEC_NO_MATCH_ERROR flag was given - */ -GIT_EXTERN(int) git_pathspec_match_workdir( - git_pathspec_match_list **out, - git_repository *repo, - uint32_t flags, - git_pathspec *ps); - -/** - * Match a pathspec against entries in an index. - * - * This matches the pathspec against the files in the repository index. - * - * NOTE: At the moment, the case sensitivity of this match is controlled - * by the current case-sensitivity of the index object itself and the - * USE_CASE and IGNORE_CASE flags will have no effect. This behavior will - * be corrected in a future release. - * - * If `out` is not NULL, this returns a `git_patchspec_match_list`. That - * contains the list of all matched filenames (unless you pass the - * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of - * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` - * flag). You must call `git_pathspec_match_list_free()` on this object. - * - * @param out Output list of matches; pass NULL to just get return value - * @param index The index to match against - * @param flags Combination of git_pathspec_flag_t options to control match - * @param ps Pathspec to be matched - * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and - * the GIT_PATHSPEC_NO_MATCH_ERROR flag is used - */ -GIT_EXTERN(int) git_pathspec_match_index( - git_pathspec_match_list **out, - git_index *index, - uint32_t flags, - git_pathspec *ps); - -/** - * Match a pathspec against files in a tree. - * - * This matches the pathspec against the files in the given tree. - * - * If `out` is not NULL, this returns a `git_patchspec_match_list`. That - * contains the list of all matched filenames (unless you pass the - * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of - * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` - * flag). You must call `git_pathspec_match_list_free()` on this object. - * - * @param out Output list of matches; pass NULL to just get return value - * @param tree The root-level tree to match against - * @param flags Combination of git_pathspec_flag_t options to control match - * @param ps Pathspec to be matched - * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and - * the GIT_PATHSPEC_NO_MATCH_ERROR flag is used - */ -GIT_EXTERN(int) git_pathspec_match_tree( - git_pathspec_match_list **out, - git_tree *tree, - uint32_t flags, - git_pathspec *ps); - -/** - * Match a pathspec against files in a diff list. - * - * This matches the pathspec against the files in the given diff list. - * - * If `out` is not NULL, this returns a `git_patchspec_match_list`. That - * contains the list of all matched filenames (unless you pass the - * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of - * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` - * flag). You must call `git_pathspec_match_list_free()` on this object. - * - * @param out Output list of matches; pass NULL to just get return value - * @param diff A generated diff list - * @param flags Combination of git_pathspec_flag_t options to control match - * @param ps Pathspec to be matched - * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and - * the GIT_PATHSPEC_NO_MATCH_ERROR flag is used - */ -GIT_EXTERN(int) git_pathspec_match_diff( - git_pathspec_match_list **out, - git_diff *diff, - uint32_t flags, - git_pathspec *ps); - -/** - * Free memory associates with a git_pathspec_match_list - * - * @param m The git_pathspec_match_list to be freed - */ -GIT_EXTERN(void) git_pathspec_match_list_free(git_pathspec_match_list *m); - -/** - * Get the number of items in a match list. - * - * @param m The git_pathspec_match_list object - * @return Number of items in match list - */ -GIT_EXTERN(size_t) git_pathspec_match_list_entrycount( - const git_pathspec_match_list *m); - -/** - * Get a matching filename by position. - * - * This routine cannot be used if the match list was generated by - * `git_pathspec_match_diff`. If so, it will always return NULL. - * - * @param m The git_pathspec_match_list object - * @param pos The index into the list - * @return The filename of the match - */ -GIT_EXTERN(const char *) git_pathspec_match_list_entry( - const git_pathspec_match_list *m, size_t pos); - -/** - * Get a matching diff delta by position. - * - * This routine can only be used if the match list was generated by - * `git_pathspec_match_diff`. Otherwise it will always return NULL. - * - * @param m The git_pathspec_match_list object - * @param pos The index into the list - * @return The filename of the match - */ -GIT_EXTERN(const git_diff_delta *) git_pathspec_match_list_diff_entry( - const git_pathspec_match_list *m, size_t pos); - -/** - * Get the number of pathspec items that did not match. - * - * This will be zero unless you passed GIT_PATHSPEC_FIND_FAILURES when - * generating the git_pathspec_match_list. - * - * @param m The git_pathspec_match_list object - * @return Number of items in original pathspec that had no matches - */ -GIT_EXTERN(size_t) git_pathspec_match_list_failed_entrycount( - const git_pathspec_match_list *m); - -/** - * Get an original pathspec string that had no matches. - * - * This will be return NULL for positions out of range. - * - * @param m The git_pathspec_match_list object - * @param pos The index into the failed items - * @return The pathspec pattern that didn't match anything - */ -GIT_EXTERN(const char *) git_pathspec_match_list_failed_entry( - const git_pathspec_match_list *m, size_t pos); - -GIT_END_DECL -#endif +/* + * 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_pathspec_h__ +#define INCLUDE_git_pathspec_h__ + +#include "common.h" +#include "types.h" +#include "strarray.h" +#include "diff.h" + +GIT_BEGIN_DECL + +/** + * Compiled pathspec + */ +typedef struct git_pathspec git_pathspec; + +/** + * List of filenames matching a pathspec + */ +typedef struct git_pathspec_match_list git_pathspec_match_list; + +/** + * Options controlling how pathspec match should be executed + */ +typedef enum { + GIT_PATHSPEC_DEFAULT = 0, + + /** + * GIT_PATHSPEC_IGNORE_CASE forces match to ignore case; otherwise + * match will use native case sensitivity of platform filesystem + */ + GIT_PATHSPEC_IGNORE_CASE = (1u << 0), + + /** + * GIT_PATHSPEC_USE_CASE forces case sensitive match; otherwise + * match will use native case sensitivity of platform filesystem + */ + GIT_PATHSPEC_USE_CASE = (1u << 1), + + /** + * GIT_PATHSPEC_NO_GLOB disables glob patterns and just uses simple + * string comparison for matching + */ + GIT_PATHSPEC_NO_GLOB = (1u << 2), + + /** + * GIT_PATHSPEC_NO_MATCH_ERROR means the match functions return error + * code GIT_ENOTFOUND if no matches are found; otherwise no matches is + * still success (return 0) but `git_pathspec_match_list_entrycount` + * will indicate 0 matches. + */ + GIT_PATHSPEC_NO_MATCH_ERROR = (1u << 3), + + /** + * GIT_PATHSPEC_FIND_FAILURES means that the `git_pathspec_match_list` + * should track which patterns matched which files so that at the end of + * the match we can identify patterns that did not match any files. + */ + GIT_PATHSPEC_FIND_FAILURES = (1u << 4), + + /** + * GIT_PATHSPEC_FAILURES_ONLY means that the `git_pathspec_match_list` + * does not need to keep the actual matching filenames. Use this to + * just test if there were any matches at all or in combination with + * GIT_PATHSPEC_FIND_FAILURES to validate a pathspec. + */ + GIT_PATHSPEC_FAILURES_ONLY = (1u << 5) +} git_pathspec_flag_t; + +/** + * Compile a pathspec + * + * @param out Output of the compiled pathspec + * @param pathspec A git_strarray of the paths to match + * @return 0 on success, <0 on failure + */ +GIT_EXTERN(int) git_pathspec_new( + git_pathspec **out, const git_strarray *pathspec); + +/** + * Free a pathspec + * + * @param ps The compiled pathspec + */ +GIT_EXTERN(void) git_pathspec_free(git_pathspec *ps); + +/** + * Try to match a path against a pathspec + * + * Unlike most of the other pathspec matching functions, this will not + * fall back on the native case-sensitivity for your platform. You must + * explicitly pass flags to control case sensitivity or else this will + * fall back on being case sensitive. + * + * @param ps The compiled pathspec + * @param flags Combination of git_pathspec_flag_t options to control match + * @param path The pathname to attempt to match + * @return 1 is path matches spec, 0 if it does not + */ +GIT_EXTERN(int) git_pathspec_matches_path( + const git_pathspec *ps, uint32_t flags, const char *path); + +/** + * Match a pathspec against the working directory of a repository. + * + * This matches the pathspec against the current files in the working + * directory of the repository. It is an error to invoke this on a bare + * repo. This handles git ignores (i.e. ignored files will not be + * considered to match the `pathspec` unless the file is tracked in the + * index). + * + * If `out` is not NULL, this returns a `git_patchspec_match_list`. That + * contains the list of all matched filenames (unless you pass the + * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of + * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` + * flag). You must call `git_pathspec_match_list_free()` on this object. + * + * @param out Output list of matches; pass NULL to just get return value + * @param repo The repository in which to match; bare repo is an error + * @param flags Combination of git_pathspec_flag_t options to control match + * @param ps Pathspec to be matched + * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and + * the GIT_PATHSPEC_NO_MATCH_ERROR flag was given + */ +GIT_EXTERN(int) git_pathspec_match_workdir( + git_pathspec_match_list **out, + git_repository *repo, + uint32_t flags, + git_pathspec *ps); + +/** + * Match a pathspec against entries in an index. + * + * This matches the pathspec against the files in the repository index. + * + * NOTE: At the moment, the case sensitivity of this match is controlled + * by the current case-sensitivity of the index object itself and the + * USE_CASE and IGNORE_CASE flags will have no effect. This behavior will + * be corrected in a future release. + * + * If `out` is not NULL, this returns a `git_patchspec_match_list`. That + * contains the list of all matched filenames (unless you pass the + * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of + * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` + * flag). You must call `git_pathspec_match_list_free()` on this object. + * + * @param out Output list of matches; pass NULL to just get return value + * @param index The index to match against + * @param flags Combination of git_pathspec_flag_t options to control match + * @param ps Pathspec to be matched + * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and + * the GIT_PATHSPEC_NO_MATCH_ERROR flag is used + */ +GIT_EXTERN(int) git_pathspec_match_index( + git_pathspec_match_list **out, + git_index *index, + uint32_t flags, + git_pathspec *ps); + +/** + * Match a pathspec against files in a tree. + * + * This matches the pathspec against the files in the given tree. + * + * If `out` is not NULL, this returns a `git_patchspec_match_list`. That + * contains the list of all matched filenames (unless you pass the + * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of + * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` + * flag). You must call `git_pathspec_match_list_free()` on this object. + * + * @param out Output list of matches; pass NULL to just get return value + * @param tree The root-level tree to match against + * @param flags Combination of git_pathspec_flag_t options to control match + * @param ps Pathspec to be matched + * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and + * the GIT_PATHSPEC_NO_MATCH_ERROR flag is used + */ +GIT_EXTERN(int) git_pathspec_match_tree( + git_pathspec_match_list **out, + git_tree *tree, + uint32_t flags, + git_pathspec *ps); + +/** + * Match a pathspec against files in a diff list. + * + * This matches the pathspec against the files in the given diff list. + * + * If `out` is not NULL, this returns a `git_patchspec_match_list`. That + * contains the list of all matched filenames (unless you pass the + * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of + * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` + * flag). You must call `git_pathspec_match_list_free()` on this object. + * + * @param out Output list of matches; pass NULL to just get return value + * @param diff A generated diff list + * @param flags Combination of git_pathspec_flag_t options to control match + * @param ps Pathspec to be matched + * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and + * the GIT_PATHSPEC_NO_MATCH_ERROR flag is used + */ +GIT_EXTERN(int) git_pathspec_match_diff( + git_pathspec_match_list **out, + git_diff *diff, + uint32_t flags, + git_pathspec *ps); + +/** + * Free memory associates with a git_pathspec_match_list + * + * @param m The git_pathspec_match_list to be freed + */ +GIT_EXTERN(void) git_pathspec_match_list_free(git_pathspec_match_list *m); + +/** + * Get the number of items in a match list. + * + * @param m The git_pathspec_match_list object + * @return Number of items in match list + */ +GIT_EXTERN(size_t) git_pathspec_match_list_entrycount( + const git_pathspec_match_list *m); + +/** + * Get a matching filename by position. + * + * This routine cannot be used if the match list was generated by + * `git_pathspec_match_diff`. If so, it will always return NULL. + * + * @param m The git_pathspec_match_list object + * @param pos The index into the list + * @return The filename of the match + */ +GIT_EXTERN(const char *) git_pathspec_match_list_entry( + const git_pathspec_match_list *m, size_t pos); + +/** + * Get a matching diff delta by position. + * + * This routine can only be used if the match list was generated by + * `git_pathspec_match_diff`. Otherwise it will always return NULL. + * + * @param m The git_pathspec_match_list object + * @param pos The index into the list + * @return The filename of the match + */ +GIT_EXTERN(const git_diff_delta *) git_pathspec_match_list_diff_entry( + const git_pathspec_match_list *m, size_t pos); + +/** + * Get the number of pathspec items that did not match. + * + * This will be zero unless you passed GIT_PATHSPEC_FIND_FAILURES when + * generating the git_pathspec_match_list. + * + * @param m The git_pathspec_match_list object + * @return Number of items in original pathspec that had no matches + */ +GIT_EXTERN(size_t) git_pathspec_match_list_failed_entrycount( + const git_pathspec_match_list *m); + +/** + * Get an original pathspec string that had no matches. + * + * This will be return NULL for positions out of range. + * + * @param m The git_pathspec_match_list object + * @param pos The index into the failed items + * @return The pathspec pattern that didn't match anything + */ +GIT_EXTERN(const char *) git_pathspec_match_list_failed_entry( + const git_pathspec_match_list *m, size_t pos); + +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/proxy.h b/3rdparty/libgit2/include/git2/proxy.h index cfc0c64..123fcc0 100644 --- a/3rdparty/libgit2/include/git2/proxy.h +++ b/3rdparty/libgit2/include/git2/proxy.h @@ -1,98 +1,98 @@ -/* - * 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_proxy_h__ -#define INCLUDE_git_proxy_h__ - -#include "common.h" - -#include "cert.h" -#include "credential.h" - -GIT_BEGIN_DECL - -/** - * The type of proxy to use. - */ -typedef enum { - /** - * Do not attempt to connect through a proxy - * - * If built against libcurl, it itself may attempt to connect - * to a proxy if the environment variables specify it. - */ - GIT_PROXY_NONE, - /** - * Try to auto-detect the proxy from the git configuration. - */ - GIT_PROXY_AUTO, - /** - * Connect via the URL given in the options - */ - GIT_PROXY_SPECIFIED -} git_proxy_t; - -/** - * Options for connecting through a proxy - * - * Note that not all types may be supported, depending on the platform - * and compilation options. - */ -typedef struct { - unsigned int version; - - /** - * The type of proxy to use, by URL, auto-detect. - */ - git_proxy_t type; - - /** - * The URL of the proxy. - */ - const char *url; - - /** - * This will be called if the remote host requires - * authentication in order to connect to it. - * - * Returning GIT_PASSTHROUGH will make libgit2 behave as - * though this field isn't set. - */ - git_credential_acquire_cb credentials; - - /** - * If cert verification fails, this will be called to let the - * user make the final decision of whether to allow the - * connection to proceed. Returns 0 to allow the connection - * or a negative value to indicate an error. - */ - git_transport_certificate_check_cb certificate_check; - - /** - * Payload to be provided to the credentials and certificate - * check callbacks. - */ - void *payload; -} git_proxy_options; - -#define GIT_PROXY_OPTIONS_VERSION 1 -#define GIT_PROXY_OPTIONS_INIT {GIT_PROXY_OPTIONS_VERSION} - -/** - * Initialize git_proxy_options structure - * - * Initializes a `git_proxy_options` with default values. Equivalent to - * creating an instance with `GIT_PROXY_OPTIONS_INIT`. - * - * @param opts The `git_proxy_options` struct to initialize. - * @param version The struct version; pass `GIT_PROXY_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_proxy_options_init(git_proxy_options *opts, unsigned int version); - -GIT_END_DECL - -#endif +/* + * 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_proxy_h__ +#define INCLUDE_git_proxy_h__ + +#include "common.h" + +#include "cert.h" +#include "credential.h" + +GIT_BEGIN_DECL + +/** + * The type of proxy to use. + */ +typedef enum { + /** + * Do not attempt to connect through a proxy + * + * If built against libcurl, it itself may attempt to connect + * to a proxy if the environment variables specify it. + */ + GIT_PROXY_NONE, + /** + * Try to auto-detect the proxy from the git configuration. + */ + GIT_PROXY_AUTO, + /** + * Connect via the URL given in the options + */ + GIT_PROXY_SPECIFIED +} git_proxy_t; + +/** + * Options for connecting through a proxy + * + * Note that not all types may be supported, depending on the platform + * and compilation options. + */ +typedef struct { + unsigned int version; + + /** + * The type of proxy to use, by URL, auto-detect. + */ + git_proxy_t type; + + /** + * The URL of the proxy. + */ + const char *url; + + /** + * This will be called if the remote host requires + * authentication in order to connect to it. + * + * Returning GIT_PASSTHROUGH will make libgit2 behave as + * though this field isn't set. + */ + git_credential_acquire_cb credentials; + + /** + * If cert verification fails, this will be called to let the + * user make the final decision of whether to allow the + * connection to proceed. Returns 0 to allow the connection + * or a negative value to indicate an error. + */ + git_transport_certificate_check_cb certificate_check; + + /** + * Payload to be provided to the credentials and certificate + * check callbacks. + */ + void *payload; +} git_proxy_options; + +#define GIT_PROXY_OPTIONS_VERSION 1 +#define GIT_PROXY_OPTIONS_INIT {GIT_PROXY_OPTIONS_VERSION} + +/** + * Initialize git_proxy_options structure + * + * Initializes a `git_proxy_options` with default values. Equivalent to + * creating an instance with `GIT_PROXY_OPTIONS_INIT`. + * + * @param opts The `git_proxy_options` struct to initialize. + * @param version The struct version; pass `GIT_PROXY_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_proxy_options_init(git_proxy_options *opts, unsigned int version); + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/rebase.h b/3rdparty/libgit2/include/git2/rebase.h index b1ac71f..83a4c48 100644 --- a/3rdparty/libgit2/include/git2/rebase.h +++ b/3rdparty/libgit2/include/git2/rebase.h @@ -1,399 +1,399 @@ -/* - * 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_rebase_h__ -#define INCLUDE_git_rebase_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "annotated_commit.h" -#include "merge.h" -#include "checkout.h" -#include "commit.h" - -/** - * @file git2/rebase.h - * @brief Git rebase routines - * @defgroup git_rebase Git merge routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Rebase options - * - * Use to tell the rebase machinery how to operate. - */ -typedef struct { - unsigned int version; - - /** - * Used by `git_rebase_init`, this will instruct other clients working - * on this rebase that you want a quiet rebase experience, which they - * may choose to provide in an application-specific manner. This has no - * effect upon libgit2 directly, but is provided for interoperability - * between Git tools. - */ - int quiet; - - /** - * Used by `git_rebase_init`, this will begin an in-memory rebase, - * which will allow callers to step through the rebase operations and - * commit the rebased changes, but will not rewind HEAD or update the - * repository to be in a rebasing state. This will not interfere with - * the working directory (if there is one). - */ - int inmemory; - - /** - * Used by `git_rebase_finish`, this is the name of the notes reference - * used to rewrite notes for rebased commits when finishing the rebase; - * if NULL, the contents of the configuration option `notes.rewriteRef` - * is examined, unless the configuration option `notes.rewrite.rebase` - * is set to false. If `notes.rewriteRef` is also NULL, notes will - * not be rewritten. - */ - const char *rewrite_notes_ref; - - /** - * Options to control how trees are merged during `git_rebase_next`. - */ - git_merge_options merge_options; - - /** - * Options to control how files are written during `git_rebase_init`, - * `git_rebase_next` and `git_rebase_abort`. Note that a minimum - * strategy of `GIT_CHECKOUT_SAFE` is defaulted in `init` and `next`, - * and a minimum strategy of `GIT_CHECKOUT_FORCE` is defaulted in - * `abort` to match git semantics. - */ - git_checkout_options checkout_options; - - /** - * Optional callback that allows users to override commit - * creation in `git_rebase_commit`. If specified, users can - * create their own commit and provide the commit ID, which - * may be useful for signing commits or otherwise customizing - * the commit creation. - * - * If this callback returns `GIT_PASSTHROUGH`, then - * `git_rebase_commit` will continue to create the commit. - */ - git_commit_create_cb commit_create_cb; - -#ifdef GIT_DEPRECATE_HARD - void *reserved; -#else - /** - * If provided, this will be called with the commit content, allowing - * a signature to be added to the rebase commit. Can be skipped with - * GIT_PASSTHROUGH. If GIT_PASSTHROUGH is returned, a commit will be made - * without a signature. - * - * This field is only used when performing git_rebase_commit. - * - * This callback is not invoked if a `git_commit_create_cb` is - * specified. - * - * This callback is deprecated; users should provide a - * creation callback as `commit_create_cb` that produces a - * commit buffer, signs it, and commits it. - */ - int (*signing_cb)(git_buf *, git_buf *, const char *, void *); -#endif - - /** - * This will be passed to each of the callbacks in this struct - * as the last parameter. - */ - void *payload; -} git_rebase_options; - -/** - * Type of rebase operation in-progress after calling `git_rebase_next`. - */ -typedef enum { - /** - * The given commit is to be cherry-picked. The client should commit - * the changes and continue if there are no conflicts. - */ - GIT_REBASE_OPERATION_PICK = 0, - - /** - * The given commit is to be cherry-picked, but the client should prompt - * the user to provide an updated commit message. - */ - GIT_REBASE_OPERATION_REWORD, - - /** - * The given commit is to be cherry-picked, but the client should stop - * to allow the user to edit the changes before committing them. - */ - GIT_REBASE_OPERATION_EDIT, - - /** - * The given commit is to be squashed into the previous commit. The - * commit message will be merged with the previous message. - */ - GIT_REBASE_OPERATION_SQUASH, - - /** - * The given commit is to be squashed into the previous commit. The - * commit message from this commit will be discarded. - */ - GIT_REBASE_OPERATION_FIXUP, - - /** - * No commit will be cherry-picked. The client should run the given - * command and (if successful) continue. - */ - GIT_REBASE_OPERATION_EXEC -} git_rebase_operation_t; - -#define GIT_REBASE_OPTIONS_VERSION 1 -#define GIT_REBASE_OPTIONS_INIT \ - { GIT_REBASE_OPTIONS_VERSION, 0, 0, NULL, GIT_MERGE_OPTIONS_INIT, \ - GIT_CHECKOUT_OPTIONS_INIT, NULL, NULL } - -/** Indicates that a rebase operation is not (yet) in progress. */ -#define GIT_REBASE_NO_OPERATION SIZE_MAX - -/** - * A rebase operation - * - * Describes a single instruction/operation to be performed during the - * rebase. - */ -typedef struct { - /** The type of rebase operation. */ - git_rebase_operation_t type; - - /** - * The commit ID being cherry-picked. This will be populated for - * all operations except those of type `GIT_REBASE_OPERATION_EXEC`. - */ - const git_oid id; - - /** - * The executable the user has requested be run. This will only - * be populated for operations of type `GIT_REBASE_OPERATION_EXEC`. - */ - const char *exec; -} git_rebase_operation; - -/** - * Initialize git_rebase_options structure - * - * Initializes a `git_rebase_options` with default values. Equivalent to - * creating an instance with `GIT_REBASE_OPTIONS_INIT`. - * - * @param opts The `git_rebase_options` struct to initialize. - * @param version The struct version; pass `GIT_REBASE_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_rebase_options_init( - git_rebase_options *opts, - unsigned int version); - -/** - * Initializes a rebase operation to rebase the changes in `branch` - * relative to `upstream` onto another branch. To begin the rebase - * process, call `git_rebase_next`. When you have finished with this - * object, call `git_rebase_free`. - * - * @param out Pointer to store the rebase object - * @param repo The repository to perform the rebase - * @param branch The terminal commit to rebase, or NULL to rebase the - * current branch - * @param upstream The commit to begin rebasing from, or NULL to rebase all - * reachable commits - * @param onto The branch to rebase onto, or NULL to rebase onto the given - * upstream - * @param opts Options to specify how rebase is performed, or NULL - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_rebase_init( - git_rebase **out, - git_repository *repo, - const git_annotated_commit *branch, - const git_annotated_commit *upstream, - const git_annotated_commit *onto, - const git_rebase_options *opts); - -/** - * Opens an existing rebase that was previously started by either an - * invocation of `git_rebase_init` or by another client. - * - * @param out Pointer to store the rebase object - * @param repo The repository that has a rebase in-progress - * @param opts Options to specify how rebase is performed - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_rebase_open( - git_rebase **out, - git_repository *repo, - const git_rebase_options *opts); - -/** - * Gets the original `HEAD` ref name for merge rebases. - * - * @param rebase The in-progress rebase. - * @return The original `HEAD` ref name - */ -GIT_EXTERN(const char *) git_rebase_orig_head_name(git_rebase *rebase); - -/** - * Gets the original `HEAD` id for merge rebases. - * - * @param rebase The in-progress rebase. - * @return The original `HEAD` id - */ -GIT_EXTERN(const git_oid *) git_rebase_orig_head_id(git_rebase *rebase); - -/** - * Gets the `onto` ref name for merge rebases. - * - * @param rebase The in-progress rebase. - * @return The `onto` ref name - */ -GIT_EXTERN(const char *) git_rebase_onto_name(git_rebase *rebase); - -/** - * Gets the `onto` id for merge rebases. - * - * @param rebase The in-progress rebase. - * @return The `onto` id - */ -GIT_EXTERN(const git_oid *) git_rebase_onto_id(git_rebase *rebase); - -/** - * Gets the count of rebase operations that are to be applied. - * - * @param rebase The in-progress rebase - * @return The number of rebase operations in total - */ -GIT_EXTERN(size_t) git_rebase_operation_entrycount(git_rebase *rebase); - -/** - * Gets the index of the rebase operation that is currently being applied. - * If the first operation has not yet been applied (because you have - * called `init` but not yet `next`) then this returns - * `GIT_REBASE_NO_OPERATION`. - * - * @param rebase The in-progress rebase - * @return The index of the rebase operation currently being applied. - */ -GIT_EXTERN(size_t) git_rebase_operation_current(git_rebase *rebase); - -/** - * Gets the rebase operation specified by the given index. - * - * @param rebase The in-progress rebase - * @param idx The index of the rebase operation to retrieve - * @return The rebase operation or NULL if `idx` was out of bounds - */ -GIT_EXTERN(git_rebase_operation *) git_rebase_operation_byindex( - git_rebase *rebase, - size_t idx); - -/** - * Performs the next rebase operation and returns the information about it. - * If the operation is one that applies a patch (which is any operation except - * GIT_REBASE_OPERATION_EXEC) then the patch will be applied and the index and - * working directory will be updated with the changes. If there are conflicts, - * you will need to address those before committing the changes. - * - * @param operation Pointer to store the rebase operation that is to be performed next - * @param rebase The rebase in progress - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_rebase_next( - git_rebase_operation **operation, - git_rebase *rebase); - -/** - * Gets the index produced by the last operation, which is the result - * of `git_rebase_next` and which will be committed by the next - * invocation of `git_rebase_commit`. This is useful for resolving - * conflicts in an in-memory rebase before committing them. You must - * call `git_index_free` when you are finished with this. - * - * This is only applicable for in-memory rebases; for rebases within - * a working directory, the changes were applied to the repository's - * index. - * - * @param index The result index of the last operation. - * @param rebase The in-progress rebase. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_rebase_inmemory_index( - git_index **index, - git_rebase *rebase); - -/** - * Commits the current patch. You must have resolved any conflicts that - * were introduced during the patch application from the `git_rebase_next` - * invocation. - * - * @param id Pointer in which to store the OID of the newly created commit - * @param rebase The rebase that is in-progress - * @param author The author of the updated commit, or NULL to keep the - * author from the original commit - * @param committer The committer of the rebase - * @param message_encoding The encoding for the message in the commit, - * represented with a standard encoding name. If message is NULL, - * this should also be NULL, and the encoding from the original - * commit will be maintained. If message is specified, this may be - * NULL to indicate that "UTF-8" is to be used. - * @param message The message for this commit, or NULL to use the message - * from the original commit. - * @return Zero on success, GIT_EUNMERGED if there are unmerged changes in - * the index, GIT_EAPPLIED if the current commit has already - * been applied to the upstream and there is nothing to commit, - * -1 on failure. - */ -GIT_EXTERN(int) git_rebase_commit( - git_oid *id, - git_rebase *rebase, - const git_signature *author, - const git_signature *committer, - const char *message_encoding, - const char *message); - -/** - * Aborts a rebase that is currently in progress, resetting the repository - * and working directory to their state before rebase began. - * - * @param rebase The rebase that is in-progress - * @return Zero on success; GIT_ENOTFOUND if a rebase is not in progress, - * -1 on other errors. - */ -GIT_EXTERN(int) git_rebase_abort(git_rebase *rebase); - -/** - * Finishes a rebase that is currently in progress once all patches have - * been applied. - * - * @param rebase The rebase that is in-progress - * @param signature The identity that is finishing the rebase (optional) - * @return Zero on success; -1 on error - */ -GIT_EXTERN(int) git_rebase_finish( - git_rebase *rebase, - const git_signature *signature); - -/** - * Frees the `git_rebase` object. - * - * @param rebase The rebase object - */ -GIT_EXTERN(void) git_rebase_free(git_rebase *rebase); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_rebase_h__ +#define INCLUDE_git_rebase_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "annotated_commit.h" +#include "merge.h" +#include "checkout.h" +#include "commit.h" + +/** + * @file git2/rebase.h + * @brief Git rebase routines + * @defgroup git_rebase Git merge routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Rebase options + * + * Use to tell the rebase machinery how to operate. + */ +typedef struct { + unsigned int version; + + /** + * Used by `git_rebase_init`, this will instruct other clients working + * on this rebase that you want a quiet rebase experience, which they + * may choose to provide in an application-specific manner. This has no + * effect upon libgit2 directly, but is provided for interoperability + * between Git tools. + */ + int quiet; + + /** + * Used by `git_rebase_init`, this will begin an in-memory rebase, + * which will allow callers to step through the rebase operations and + * commit the rebased changes, but will not rewind HEAD or update the + * repository to be in a rebasing state. This will not interfere with + * the working directory (if there is one). + */ + int inmemory; + + /** + * Used by `git_rebase_finish`, this is the name of the notes reference + * used to rewrite notes for rebased commits when finishing the rebase; + * if NULL, the contents of the configuration option `notes.rewriteRef` + * is examined, unless the configuration option `notes.rewrite.rebase` + * is set to false. If `notes.rewriteRef` is also NULL, notes will + * not be rewritten. + */ + const char *rewrite_notes_ref; + + /** + * Options to control how trees are merged during `git_rebase_next`. + */ + git_merge_options merge_options; + + /** + * Options to control how files are written during `git_rebase_init`, + * `git_rebase_next` and `git_rebase_abort`. Note that a minimum + * strategy of `GIT_CHECKOUT_SAFE` is defaulted in `init` and `next`, + * and a minimum strategy of `GIT_CHECKOUT_FORCE` is defaulted in + * `abort` to match git semantics. + */ + git_checkout_options checkout_options; + + /** + * Optional callback that allows users to override commit + * creation in `git_rebase_commit`. If specified, users can + * create their own commit and provide the commit ID, which + * may be useful for signing commits or otherwise customizing + * the commit creation. + * + * If this callback returns `GIT_PASSTHROUGH`, then + * `git_rebase_commit` will continue to create the commit. + */ + git_commit_create_cb commit_create_cb; + +#ifdef GIT_DEPRECATE_HARD + void *reserved; +#else + /** + * If provided, this will be called with the commit content, allowing + * a signature to be added to the rebase commit. Can be skipped with + * GIT_PASSTHROUGH. If GIT_PASSTHROUGH is returned, a commit will be made + * without a signature. + * + * This field is only used when performing git_rebase_commit. + * + * This callback is not invoked if a `git_commit_create_cb` is + * specified. + * + * This callback is deprecated; users should provide a + * creation callback as `commit_create_cb` that produces a + * commit buffer, signs it, and commits it. + */ + int (*signing_cb)(git_buf *, git_buf *, const char *, void *); +#endif + + /** + * This will be passed to each of the callbacks in this struct + * as the last parameter. + */ + void *payload; +} git_rebase_options; + +/** + * Type of rebase operation in-progress after calling `git_rebase_next`. + */ +typedef enum { + /** + * The given commit is to be cherry-picked. The client should commit + * the changes and continue if there are no conflicts. + */ + GIT_REBASE_OPERATION_PICK = 0, + + /** + * The given commit is to be cherry-picked, but the client should prompt + * the user to provide an updated commit message. + */ + GIT_REBASE_OPERATION_REWORD, + + /** + * The given commit is to be cherry-picked, but the client should stop + * to allow the user to edit the changes before committing them. + */ + GIT_REBASE_OPERATION_EDIT, + + /** + * The given commit is to be squashed into the previous commit. The + * commit message will be merged with the previous message. + */ + GIT_REBASE_OPERATION_SQUASH, + + /** + * The given commit is to be squashed into the previous commit. The + * commit message from this commit will be discarded. + */ + GIT_REBASE_OPERATION_FIXUP, + + /** + * No commit will be cherry-picked. The client should run the given + * command and (if successful) continue. + */ + GIT_REBASE_OPERATION_EXEC +} git_rebase_operation_t; + +#define GIT_REBASE_OPTIONS_VERSION 1 +#define GIT_REBASE_OPTIONS_INIT \ + { GIT_REBASE_OPTIONS_VERSION, 0, 0, NULL, GIT_MERGE_OPTIONS_INIT, \ + GIT_CHECKOUT_OPTIONS_INIT, NULL, NULL } + +/** Indicates that a rebase operation is not (yet) in progress. */ +#define GIT_REBASE_NO_OPERATION SIZE_MAX + +/** + * A rebase operation + * + * Describes a single instruction/operation to be performed during the + * rebase. + */ +typedef struct { + /** The type of rebase operation. */ + git_rebase_operation_t type; + + /** + * The commit ID being cherry-picked. This will be populated for + * all operations except those of type `GIT_REBASE_OPERATION_EXEC`. + */ + const git_oid id; + + /** + * The executable the user has requested be run. This will only + * be populated for operations of type `GIT_REBASE_OPERATION_EXEC`. + */ + const char *exec; +} git_rebase_operation; + +/** + * Initialize git_rebase_options structure + * + * Initializes a `git_rebase_options` with default values. Equivalent to + * creating an instance with `GIT_REBASE_OPTIONS_INIT`. + * + * @param opts The `git_rebase_options` struct to initialize. + * @param version The struct version; pass `GIT_REBASE_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_rebase_options_init( + git_rebase_options *opts, + unsigned int version); + +/** + * Initializes a rebase operation to rebase the changes in `branch` + * relative to `upstream` onto another branch. To begin the rebase + * process, call `git_rebase_next`. When you have finished with this + * object, call `git_rebase_free`. + * + * @param out Pointer to store the rebase object + * @param repo The repository to perform the rebase + * @param branch The terminal commit to rebase, or NULL to rebase the + * current branch + * @param upstream The commit to begin rebasing from, or NULL to rebase all + * reachable commits + * @param onto The branch to rebase onto, or NULL to rebase onto the given + * upstream + * @param opts Options to specify how rebase is performed, or NULL + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_rebase_init( + git_rebase **out, + git_repository *repo, + const git_annotated_commit *branch, + const git_annotated_commit *upstream, + const git_annotated_commit *onto, + const git_rebase_options *opts); + +/** + * Opens an existing rebase that was previously started by either an + * invocation of `git_rebase_init` or by another client. + * + * @param out Pointer to store the rebase object + * @param repo The repository that has a rebase in-progress + * @param opts Options to specify how rebase is performed + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_rebase_open( + git_rebase **out, + git_repository *repo, + const git_rebase_options *opts); + +/** + * Gets the original `HEAD` ref name for merge rebases. + * + * @param rebase The in-progress rebase. + * @return The original `HEAD` ref name + */ +GIT_EXTERN(const char *) git_rebase_orig_head_name(git_rebase *rebase); + +/** + * Gets the original `HEAD` id for merge rebases. + * + * @param rebase The in-progress rebase. + * @return The original `HEAD` id + */ +GIT_EXTERN(const git_oid *) git_rebase_orig_head_id(git_rebase *rebase); + +/** + * Gets the `onto` ref name for merge rebases. + * + * @param rebase The in-progress rebase. + * @return The `onto` ref name + */ +GIT_EXTERN(const char *) git_rebase_onto_name(git_rebase *rebase); + +/** + * Gets the `onto` id for merge rebases. + * + * @param rebase The in-progress rebase. + * @return The `onto` id + */ +GIT_EXTERN(const git_oid *) git_rebase_onto_id(git_rebase *rebase); + +/** + * Gets the count of rebase operations that are to be applied. + * + * @param rebase The in-progress rebase + * @return The number of rebase operations in total + */ +GIT_EXTERN(size_t) git_rebase_operation_entrycount(git_rebase *rebase); + +/** + * Gets the index of the rebase operation that is currently being applied. + * If the first operation has not yet been applied (because you have + * called `init` but not yet `next`) then this returns + * `GIT_REBASE_NO_OPERATION`. + * + * @param rebase The in-progress rebase + * @return The index of the rebase operation currently being applied. + */ +GIT_EXTERN(size_t) git_rebase_operation_current(git_rebase *rebase); + +/** + * Gets the rebase operation specified by the given index. + * + * @param rebase The in-progress rebase + * @param idx The index of the rebase operation to retrieve + * @return The rebase operation or NULL if `idx` was out of bounds + */ +GIT_EXTERN(git_rebase_operation *) git_rebase_operation_byindex( + git_rebase *rebase, + size_t idx); + +/** + * Performs the next rebase operation and returns the information about it. + * If the operation is one that applies a patch (which is any operation except + * GIT_REBASE_OPERATION_EXEC) then the patch will be applied and the index and + * working directory will be updated with the changes. If there are conflicts, + * you will need to address those before committing the changes. + * + * @param operation Pointer to store the rebase operation that is to be performed next + * @param rebase The rebase in progress + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_rebase_next( + git_rebase_operation **operation, + git_rebase *rebase); + +/** + * Gets the index produced by the last operation, which is the result + * of `git_rebase_next` and which will be committed by the next + * invocation of `git_rebase_commit`. This is useful for resolving + * conflicts in an in-memory rebase before committing them. You must + * call `git_index_free` when you are finished with this. + * + * This is only applicable for in-memory rebases; for rebases within + * a working directory, the changes were applied to the repository's + * index. + * + * @param index The result index of the last operation. + * @param rebase The in-progress rebase. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_rebase_inmemory_index( + git_index **index, + git_rebase *rebase); + +/** + * Commits the current patch. You must have resolved any conflicts that + * were introduced during the patch application from the `git_rebase_next` + * invocation. + * + * @param id Pointer in which to store the OID of the newly created commit + * @param rebase The rebase that is in-progress + * @param author The author of the updated commit, or NULL to keep the + * author from the original commit + * @param committer The committer of the rebase + * @param message_encoding The encoding for the message in the commit, + * represented with a standard encoding name. If message is NULL, + * this should also be NULL, and the encoding from the original + * commit will be maintained. If message is specified, this may be + * NULL to indicate that "UTF-8" is to be used. + * @param message The message for this commit, or NULL to use the message + * from the original commit. + * @return Zero on success, GIT_EUNMERGED if there are unmerged changes in + * the index, GIT_EAPPLIED if the current commit has already + * been applied to the upstream and there is nothing to commit, + * -1 on failure. + */ +GIT_EXTERN(int) git_rebase_commit( + git_oid *id, + git_rebase *rebase, + const git_signature *author, + const git_signature *committer, + const char *message_encoding, + const char *message); + +/** + * Aborts a rebase that is currently in progress, resetting the repository + * and working directory to their state before rebase began. + * + * @param rebase The rebase that is in-progress + * @return Zero on success; GIT_ENOTFOUND if a rebase is not in progress, + * -1 on other errors. + */ +GIT_EXTERN(int) git_rebase_abort(git_rebase *rebase); + +/** + * Finishes a rebase that is currently in progress once all patches have + * been applied. + * + * @param rebase The rebase that is in-progress + * @param signature The identity that is finishing the rebase (optional) + * @return Zero on success; -1 on error + */ +GIT_EXTERN(int) git_rebase_finish( + git_rebase *rebase, + const git_signature *signature); + +/** + * Frees the `git_rebase` object. + * + * @param rebase The rebase object + */ +GIT_EXTERN(void) git_rebase_free(git_rebase *rebase); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/refdb.h b/3rdparty/libgit2/include/git2/refdb.h index c4849ab..faf5541 100644 --- a/3rdparty/libgit2/include/git2/refdb.h +++ b/3rdparty/libgit2/include/git2/refdb.h @@ -1,71 +1,71 @@ -/* - * 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_refdb_h__ -#define INCLUDE_git_refdb_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "refs.h" - -/** - * @file git2/refdb.h - * @brief Git custom refs backend functions - * @defgroup git_refdb Git custom refs backend API - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Create a new reference database with no backends. - * - * Before the Ref DB can be used for read/writing, a custom database - * backend must be manually set using `git_refdb_set_backend()` - * - * @param out location to store the database pointer, if opened. - * Set to NULL if the open failed. - * @param repo the repository - * @return 0 or an error code - */ -GIT_EXTERN(int) git_refdb_new(git_refdb **out, git_repository *repo); - -/** - * Create a new reference database and automatically add - * the default backends: - * - * - git_refdb_dir: read and write loose and packed refs - * from disk, assuming the repository dir as the folder - * - * @param out location to store the database pointer, if opened. - * Set to NULL if the open failed. - * @param repo the repository - * @return 0 or an error code - */ -GIT_EXTERN(int) git_refdb_open(git_refdb **out, git_repository *repo); - -/** - * Suggests that the given refdb compress or optimize its references. - * This mechanism is implementation specific. For on-disk reference - * databases, for example, this may pack all loose references. - * - * @param refdb The reference database to optimize. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_refdb_compress(git_refdb *refdb); - -/** - * Close an open reference database. - * - * @param refdb reference database pointer or NULL - */ -GIT_EXTERN(void) git_refdb_free(git_refdb *refdb); - -/** @} */ -GIT_END_DECL - -#endif +/* + * 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_refdb_h__ +#define INCLUDE_git_refdb_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "refs.h" + +/** + * @file git2/refdb.h + * @brief Git custom refs backend functions + * @defgroup git_refdb Git custom refs backend API + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a new reference database with no backends. + * + * Before the Ref DB can be used for read/writing, a custom database + * backend must be manually set using `git_refdb_set_backend()` + * + * @param out location to store the database pointer, if opened. + * Set to NULL if the open failed. + * @param repo the repository + * @return 0 or an error code + */ +GIT_EXTERN(int) git_refdb_new(git_refdb **out, git_repository *repo); + +/** + * Create a new reference database and automatically add + * the default backends: + * + * - git_refdb_dir: read and write loose and packed refs + * from disk, assuming the repository dir as the folder + * + * @param out location to store the database pointer, if opened. + * Set to NULL if the open failed. + * @param repo the repository + * @return 0 or an error code + */ +GIT_EXTERN(int) git_refdb_open(git_refdb **out, git_repository *repo); + +/** + * Suggests that the given refdb compress or optimize its references. + * This mechanism is implementation specific. For on-disk reference + * databases, for example, this may pack all loose references. + * + * @param refdb The reference database to optimize. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_refdb_compress(git_refdb *refdb); + +/** + * Close an open reference database. + * + * @param refdb reference database pointer or NULL + */ +GIT_EXTERN(void) git_refdb_free(git_refdb *refdb); + +/** @} */ +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/reflog.h b/3rdparty/libgit2/include/git2/reflog.h index ec365c1..318ab97 100644 --- a/3rdparty/libgit2/include/git2/reflog.h +++ b/3rdparty/libgit2/include/git2/reflog.h @@ -1,170 +1,170 @@ -/* - * 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_reflog_h__ -#define INCLUDE_git_reflog_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" - -/** - * @file git2/reflog.h - * @brief Git reflog management routines - * @defgroup git_reflog Git reflog management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Read the reflog for the given reference - * - * If there is no reflog file for the given - * reference yet, an empty reflog object will - * be returned. - * - * The reflog must be freed manually by using - * git_reflog_free(). - * - * @param out pointer to reflog - * @param repo the repository - * @param name reference to look up - * @return 0 or an error code - */ -GIT_EXTERN(int) git_reflog_read(git_reflog **out, git_repository *repo, const char *name); - -/** - * Write an existing in-memory reflog object back to disk - * using an atomic file lock. - * - * @param reflog an existing reflog object - * @return 0 or an error code - */ -GIT_EXTERN(int) git_reflog_write(git_reflog *reflog); - -/** - * Add a new entry to the in-memory reflog. - * - * `msg` is optional and can be NULL. - * - * @param reflog an existing reflog object - * @param id the OID the reference is now pointing to - * @param committer the signature of the committer - * @param msg the reflog message - * @return 0 or an error code - */ -GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *id, const git_signature *committer, const char *msg); - -/** - * Rename a reflog - * - * The reflog to be renamed is expected to already exist - * - * The new name will be checked for validity. - * See `git_reference_create_symbolic()` for rules about valid names. - * - * @param repo the repository - * @param old_name the old name of the reference - * @param name the new name of the reference - * @return 0 on success, GIT_EINVALIDSPEC or an error code - */ -GIT_EXTERN(int) git_reflog_rename(git_repository *repo, const char *old_name, const char *name); - -/** - * Delete the reflog for the given reference - * - * @param repo the repository - * @param name the reflog to delete - * @return 0 or an error code - */ -GIT_EXTERN(int) git_reflog_delete(git_repository *repo, const char *name); - -/** - * Get the number of log entries in a reflog - * - * @param reflog the previously loaded reflog - * @return the number of log entries - */ -GIT_EXTERN(size_t) git_reflog_entrycount(git_reflog *reflog); - -/** - * Lookup an entry by its index - * - * Requesting the reflog entry with an index of 0 (zero) will - * return the most recently created entry. - * - * @param reflog a previously loaded reflog - * @param idx the position of the entry to lookup. Should be greater than or - * equal to 0 (zero) and less than `git_reflog_entrycount()`. - * @return the entry; NULL if not found - */ -GIT_EXTERN(const git_reflog_entry *) git_reflog_entry_byindex(const git_reflog *reflog, size_t idx); - -/** - * Remove an entry from the reflog by its index - * - * To ensure there's no gap in the log history, set `rewrite_previous_entry` - * param value to 1. When deleting entry `n`, member old_oid of entry `n-1` - * (if any) will be updated with the value of member new_oid of entry `n+1`. - * - * @param reflog a previously loaded reflog. - * - * @param idx the position of the entry to remove. Should be greater than or - * equal to 0 (zero) and less than `git_reflog_entrycount()`. - * - * @param rewrite_previous_entry 1 to rewrite the history; 0 otherwise. - * - * @return 0 on success, GIT_ENOTFOUND if the entry doesn't exist - * or an error code. - */ -GIT_EXTERN(int) git_reflog_drop( - git_reflog *reflog, - size_t idx, - int rewrite_previous_entry); - -/** - * Get the old oid - * - * @param entry a reflog entry - * @return the old oid - */ -GIT_EXTERN(const git_oid *) git_reflog_entry_id_old(const git_reflog_entry *entry); - -/** - * Get the new oid - * - * @param entry a reflog entry - * @return the new oid at this time - */ -GIT_EXTERN(const git_oid *) git_reflog_entry_id_new(const git_reflog_entry *entry); - -/** - * Get the committer of this entry - * - * @param entry a reflog entry - * @return the committer - */ -GIT_EXTERN(const git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry); - -/** - * Get the log message - * - * @param entry a reflog entry - * @return the log msg - */ -GIT_EXTERN(const char *) git_reflog_entry_message(const git_reflog_entry *entry); - -/** - * Free the reflog - * - * @param reflog reflog to free - */ -GIT_EXTERN(void) git_reflog_free(git_reflog *reflog); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_reflog_h__ +#define INCLUDE_git_reflog_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" + +/** + * @file git2/reflog.h + * @brief Git reflog management routines + * @defgroup git_reflog Git reflog management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Read the reflog for the given reference + * + * If there is no reflog file for the given + * reference yet, an empty reflog object will + * be returned. + * + * The reflog must be freed manually by using + * git_reflog_free(). + * + * @param out pointer to reflog + * @param repo the repository + * @param name reference to look up + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reflog_read(git_reflog **out, git_repository *repo, const char *name); + +/** + * Write an existing in-memory reflog object back to disk + * using an atomic file lock. + * + * @param reflog an existing reflog object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reflog_write(git_reflog *reflog); + +/** + * Add a new entry to the in-memory reflog. + * + * `msg` is optional and can be NULL. + * + * @param reflog an existing reflog object + * @param id the OID the reference is now pointing to + * @param committer the signature of the committer + * @param msg the reflog message + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *id, const git_signature *committer, const char *msg); + +/** + * Rename a reflog + * + * The reflog to be renamed is expected to already exist + * + * The new name will be checked for validity. + * See `git_reference_create_symbolic()` for rules about valid names. + * + * @param repo the repository + * @param old_name the old name of the reference + * @param name the new name of the reference + * @return 0 on success, GIT_EINVALIDSPEC or an error code + */ +GIT_EXTERN(int) git_reflog_rename(git_repository *repo, const char *old_name, const char *name); + +/** + * Delete the reflog for the given reference + * + * @param repo the repository + * @param name the reflog to delete + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reflog_delete(git_repository *repo, const char *name); + +/** + * Get the number of log entries in a reflog + * + * @param reflog the previously loaded reflog + * @return the number of log entries + */ +GIT_EXTERN(size_t) git_reflog_entrycount(git_reflog *reflog); + +/** + * Lookup an entry by its index + * + * Requesting the reflog entry with an index of 0 (zero) will + * return the most recently created entry. + * + * @param reflog a previously loaded reflog + * @param idx the position of the entry to lookup. Should be greater than or + * equal to 0 (zero) and less than `git_reflog_entrycount()`. + * @return the entry; NULL if not found + */ +GIT_EXTERN(const git_reflog_entry *) git_reflog_entry_byindex(const git_reflog *reflog, size_t idx); + +/** + * Remove an entry from the reflog by its index + * + * To ensure there's no gap in the log history, set `rewrite_previous_entry` + * param value to 1. When deleting entry `n`, member old_oid of entry `n-1` + * (if any) will be updated with the value of member new_oid of entry `n+1`. + * + * @param reflog a previously loaded reflog. + * + * @param idx the position of the entry to remove. Should be greater than or + * equal to 0 (zero) and less than `git_reflog_entrycount()`. + * + * @param rewrite_previous_entry 1 to rewrite the history; 0 otherwise. + * + * @return 0 on success, GIT_ENOTFOUND if the entry doesn't exist + * or an error code. + */ +GIT_EXTERN(int) git_reflog_drop( + git_reflog *reflog, + size_t idx, + int rewrite_previous_entry); + +/** + * Get the old oid + * + * @param entry a reflog entry + * @return the old oid + */ +GIT_EXTERN(const git_oid *) git_reflog_entry_id_old(const git_reflog_entry *entry); + +/** + * Get the new oid + * + * @param entry a reflog entry + * @return the new oid at this time + */ +GIT_EXTERN(const git_oid *) git_reflog_entry_id_new(const git_reflog_entry *entry); + +/** + * Get the committer of this entry + * + * @param entry a reflog entry + * @return the committer + */ +GIT_EXTERN(const git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry); + +/** + * Get the log message + * + * @param entry a reflog entry + * @return the log msg + */ +GIT_EXTERN(const char *) git_reflog_entry_message(const git_reflog_entry *entry); + +/** + * Free the reflog + * + * @param reflog reflog to free + */ +GIT_EXTERN(void) git_reflog_free(git_reflog *reflog); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/refs.h b/3rdparty/libgit2/include/git2/refs.h index 06f8bb9..5912e30 100644 --- a/3rdparty/libgit2/include/git2/refs.h +++ b/3rdparty/libgit2/include/git2/refs.h @@ -1,771 +1,771 @@ -/* - * 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_refs_h__ -#define INCLUDE_git_refs_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "strarray.h" - -/** - * @file git2/refs.h - * @brief Git reference management routines - * @defgroup git_reference Git reference management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Lookup a reference by name in a repository. - * - * The returned reference must be freed by the user. - * - * The name will be checked for validity. - * See `git_reference_symbolic_create()` for rules about valid names. - * - * @param out pointer to the looked-up reference - * @param repo the repository to look up the reference - * @param name the long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...) - * @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code. - */ -GIT_EXTERN(int) git_reference_lookup(git_reference **out, git_repository *repo, const char *name); - -/** - * Lookup a reference by name and resolve immediately to OID. - * - * This function provides a quick way to resolve a reference name straight - * through to the object id that it refers to. This avoids having to - * allocate or free any `git_reference` objects for simple situations. - * - * The name will be checked for validity. - * See `git_reference_symbolic_create()` for rules about valid names. - * - * @param out Pointer to oid to be filled in - * @param repo The repository in which to look up the reference - * @param name The long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...) - * @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code. - */ -GIT_EXTERN(int) git_reference_name_to_id( - git_oid *out, git_repository *repo, const char *name); - -/** - * Lookup a reference by DWIMing its short name - * - * Apply the git precedence rules to the given shorthand to determine - * which reference the user is referring to. - * - * @param out pointer in which to store the reference - * @param repo the repository in which to look - * @param shorthand the short name for the reference - * @return 0 or an error code - */ -GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, const char *shorthand); - -/** - * Conditionally create a new symbolic reference. - * - * A symbolic reference is a reference name that refers to another - * reference name. If the other name moves, the symbolic name will move, - * too. As a simple example, the "HEAD" reference might refer to - * "refs/heads/master" while on the "master" branch of a repository. - * - * The symbolic reference will be created in the repository and written to - * the disk. The generated reference object must be freed by the user. - * - * Valid reference names must follow one of two patterns: - * - * 1. Top-level names must contain only capital letters and underscores, - * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). - * 2. Names prefixed with "refs/" can be almost anything. You must avoid - * the characters '~', '^', ':', '\\', '?', '[', and '*', and the - * sequences ".." and "@{" which have special meaning to revparse. - * - * This function will return an error if a reference already exists with the - * given name unless `force` is true, in which case it will be overwritten. - * - * The message for the reflog will be ignored if the reference does - * not belong in the standard set (HEAD, branches and remote-tracking - * branches) and it does not have a reflog. - * - * It will return GIT_EMODIFIED if the reference's value at the time - * of updating does not match the one passed through `current_value` - * (i.e. if the ref has changed since the user read it). - * - * If `current_value` is all zeros, this function will return GIT_EMODIFIED - * if the ref already exists. - * - * @param out Pointer to the newly created reference - * @param repo Repository where that reference will live - * @param name The name of the reference - * @param target The target of the reference - * @param force Overwrite existing references - * @param current_value The expected value of the reference when updating - * @param log_message The one line long message to be appended to the reflog - * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC, GIT_EMODIFIED or an error code - */ -GIT_EXTERN(int) git_reference_symbolic_create_matching(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *current_value, const char *log_message); - -/** - * Create a new symbolic reference. - * - * A symbolic reference is a reference name that refers to another - * reference name. If the other name moves, the symbolic name will move, - * too. As a simple example, the "HEAD" reference might refer to - * "refs/heads/master" while on the "master" branch of a repository. - * - * The symbolic reference will be created in the repository and written to - * the disk. The generated reference object must be freed by the user. - * - * Valid reference names must follow one of two patterns: - * - * 1. Top-level names must contain only capital letters and underscores, - * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). - * 2. Names prefixed with "refs/" can be almost anything. You must avoid - * the characters '~', '^', ':', '\\', '?', '[', and '*', and the - * sequences ".." and "@{" which have special meaning to revparse. - * - * This function will return an error if a reference already exists with the - * given name unless `force` is true, in which case it will be overwritten. - * - * The message for the reflog will be ignored if the reference does - * not belong in the standard set (HEAD, branches and remote-tracking - * branches) and it does not have a reflog. - * - * @param out Pointer to the newly created reference - * @param repo Repository where that reference will live - * @param name The name of the reference - * @param target The target of the reference - * @param force Overwrite existing references - * @param log_message The one line long message to be appended to the reflog - * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code - */ -GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *log_message); - -/** - * Create a new direct reference. - * - * A direct reference (also called an object id reference) refers directly - * to a specific object id (a.k.a. OID or SHA) in the repository. The id - * permanently refers to the object (although the reference itself can be - * moved). For example, in libgit2 the direct ref "refs/tags/v0.17.0" - * refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977. - * - * The direct reference will be created in the repository and written to - * the disk. The generated reference object must be freed by the user. - * - * Valid reference names must follow one of two patterns: - * - * 1. Top-level names must contain only capital letters and underscores, - * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). - * 2. Names prefixed with "refs/" can be almost anything. You must avoid - * the characters '~', '^', ':', '\\', '?', '[', and '*', and the - * sequences ".." and "@{" which have special meaning to revparse. - * - * This function will return an error if a reference already exists with the - * given name unless `force` is true, in which case it will be overwritten. - * - * The message for the reflog will be ignored if the reference does - * not belong in the standard set (HEAD, branches and remote-tracking - * branches) and it does not have a reflog. - * - * @param out Pointer to the newly created reference - * @param repo Repository where that reference will live - * @param name The name of the reference - * @param id The object id pointed to by the reference. - * @param force Overwrite existing references - * @param log_message The one line long message to be appended to the reflog - * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code - */ -GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const char *log_message); - -/** - * Conditionally create new direct reference - * - * A direct reference (also called an object id reference) refers directly - * to a specific object id (a.k.a. OID or SHA) in the repository. The id - * permanently refers to the object (although the reference itself can be - * moved). For example, in libgit2 the direct ref "refs/tags/v0.17.0" - * refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977. - * - * The direct reference will be created in the repository and written to - * the disk. The generated reference object must be freed by the user. - * - * Valid reference names must follow one of two patterns: - * - * 1. Top-level names must contain only capital letters and underscores, - * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). - * 2. Names prefixed with "refs/" can be almost anything. You must avoid - * the characters '~', '^', ':', '\\', '?', '[', and '*', and the - * sequences ".." and "@{" which have special meaning to revparse. - * - * This function will return an error if a reference already exists with the - * given name unless `force` is true, in which case it will be overwritten. - * - * The message for the reflog will be ignored if the reference does - * not belong in the standard set (HEAD, branches and remote-tracking - * branches) and it does not have a reflog. - * - * It will return GIT_EMODIFIED if the reference's value at the time - * of updating does not match the one passed through `current_id` - * (i.e. if the ref has changed since the user read it). - * - * @param out Pointer to the newly created reference - * @param repo Repository where that reference will live - * @param name The name of the reference - * @param id The object id pointed to by the reference. - * @param force Overwrite existing references - * @param current_id The expected value of the reference at the time of update - * @param log_message The one line long message to be appended to the reflog - * @return 0 on success, GIT_EMODIFIED if the value of the reference - * has changed, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code - */ -GIT_EXTERN(int) git_reference_create_matching(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const git_oid *current_id, const char *log_message); - -/** - * Get the OID pointed to by a direct reference. - * - * Only available if the reference is direct (i.e. an object id reference, - * not a symbolic one). - * - * To find the OID of a symbolic ref, call `git_reference_resolve()` and - * then this function (or maybe use `git_reference_name_to_id()` to - * directly resolve a reference name all the way through to an OID). - * - * @param ref The reference - * @return a pointer to the oid if available, NULL otherwise - */ -GIT_EXTERN(const git_oid *) git_reference_target(const git_reference *ref); - -/** - * Return the peeled OID target of this reference. - * - * This peeled OID only applies to direct references that point to - * a hard Tag object: it is the result of peeling such Tag. - * - * @param ref The reference - * @return a pointer to the oid if available, NULL otherwise - */ -GIT_EXTERN(const git_oid *) git_reference_target_peel(const git_reference *ref); - -/** - * Get full name to the reference pointed to by a symbolic reference. - * - * Only available if the reference is symbolic. - * - * @param ref The reference - * @return a pointer to the name if available, NULL otherwise - */ -GIT_EXTERN(const char *) git_reference_symbolic_target(const git_reference *ref); - -/** - * Get the type of a reference. - * - * Either direct (GIT_REFERENCE_DIRECT) or symbolic (GIT_REFERENCE_SYMBOLIC) - * - * @param ref The reference - * @return the type - */ -GIT_EXTERN(git_reference_t) git_reference_type(const git_reference *ref); - -/** - * Get the full name of a reference. - * - * See `git_reference_symbolic_create()` for rules about valid names. - * - * @param ref The reference - * @return the full name for the ref - */ -GIT_EXTERN(const char *) git_reference_name(const git_reference *ref); - -/** - * Resolve a symbolic reference to a direct reference. - * - * This method iteratively peels a symbolic reference until it resolves to - * a direct reference to an OID. - * - * The peeled reference is returned in the `resolved_ref` argument, and - * must be freed manually once it's no longer needed. - * - * If a direct reference is passed as an argument, a copy of that - * reference is returned. This copy must be manually freed too. - * - * @param out Pointer to the peeled reference - * @param ref The reference - * @return 0 or an error code - */ -GIT_EXTERN(int) git_reference_resolve(git_reference **out, const git_reference *ref); - -/** - * Get the repository where a reference resides. - * - * @param ref The reference - * @return a pointer to the repo - */ -GIT_EXTERN(git_repository *) git_reference_owner(const git_reference *ref); - -/** - * Create a new reference with the same name as the given reference but a - * different symbolic target. The reference must be a symbolic reference, - * otherwise this will fail. - * - * The new reference will be written to disk, overwriting the given reference. - * - * The target name will be checked for validity. - * See `git_reference_symbolic_create()` for rules about valid names. - * - * The message for the reflog will be ignored if the reference does - * not belong in the standard set (HEAD, branches and remote-tracking - * branches) and it does not have a reflog. - * - * @param out Pointer to the newly created reference - * @param ref The reference - * @param target The new target for the reference - * @param log_message The one line long message to be appended to the reflog - * @return 0 on success, GIT_EINVALIDSPEC or an error code - */ -GIT_EXTERN(int) git_reference_symbolic_set_target( - git_reference **out, - git_reference *ref, - const char *target, - const char *log_message); - -/** - * Conditionally create a new reference with the same name as the given reference but a - * different OID target. The reference must be a direct reference, otherwise - * this will fail. - * - * The new reference will be written to disk, overwriting the given reference. - * - * @param out Pointer to the newly created reference - * @param ref The reference - * @param id The new target OID for the reference - * @param log_message The one line long message to be appended to the reflog - * @return 0 on success, GIT_EMODIFIED if the value of the reference - * has changed since it was read, or an error code - */ -GIT_EXTERN(int) git_reference_set_target( - git_reference **out, - git_reference *ref, - const git_oid *id, - const char *log_message); - -/** - * Rename an existing reference. - * - * This method works for both direct and symbolic references. - * - * The new name will be checked for validity. - * See `git_reference_symbolic_create()` for rules about valid names. - * - * If the `force` flag is not enabled, and there's already - * a reference with the given name, the renaming will fail. - * - * IMPORTANT: - * The user needs to write a proper reflog entry if the - * reflog is enabled for the repository. We only rename - * the reflog if it exists. - * - * @param ref The reference to rename - * @param new_name The new name for the reference - * @param force Overwrite an existing reference - * @param log_message The one line long message to be appended to the reflog - * @return 0 on success, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code - * - */ -GIT_EXTERN(int) git_reference_rename( - git_reference **new_ref, - git_reference *ref, - const char *new_name, - int force, - const char *log_message); - -/** - * Delete an existing reference. - * - * This method works for both direct and symbolic references. The reference - * will be immediately removed on disk but the memory will not be freed. - * Callers must call `git_reference_free`. - * - * This function will return an error if the reference has changed - * from the time it was looked up. - * - * @param ref The reference to remove - * @return 0, GIT_EMODIFIED or an error code - */ -GIT_EXTERN(int) git_reference_delete(git_reference *ref); - -/** - * Delete an existing reference by name - * - * This method removes the named reference from the repository without - * looking at its old value. - * - * @param name The reference to remove - * @return 0 or an error code - */ -GIT_EXTERN(int) git_reference_remove(git_repository *repo, const char *name); - -/** - * Fill a list with all the references that can be found in a repository. - * - * The string array will be filled with the names of all references; these - * values are owned by the user and should be free'd manually when no - * longer needed, using `git_strarray_free()`. - * - * @param array Pointer to a git_strarray structure where - * the reference names will be stored - * @param repo Repository where to find the refs - * @return 0 or an error code - */ -GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo); - -/** - * Callback used to iterate over references - * - * @see git_reference_foreach - * - * @param reference The reference object - * @param payload Payload passed to git_reference_foreach - * @return non-zero to terminate the iteration - */ -typedef int GIT_CALLBACK(git_reference_foreach_cb)(git_reference *reference, void *payload); - -/** - * Callback used to iterate over reference names - * - * @see git_reference_foreach_name - * - * @param name The reference name - * @param payload Payload passed to git_reference_foreach_name - * @return non-zero to terminate the iteration - */ -typedef int GIT_CALLBACK(git_reference_foreach_name_cb)(const char *name, void *payload); - -/** - * Perform a callback on each reference in the repository. - * - * The `callback` function will be called for each reference in the - * repository, receiving the reference object and the `payload` value - * passed to this method. Returning a non-zero value from the callback - * will terminate the iteration. - * - * Note that the callback function is responsible to call `git_reference_free` - * on each reference passed to it. - * - * @param repo Repository where to find the refs - * @param callback Function which will be called for every listed ref - * @param payload Additional data to pass to the callback - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_reference_foreach( - git_repository *repo, - git_reference_foreach_cb callback, - void *payload); - -/** - * Perform a callback on the fully-qualified name of each reference. - * - * The `callback` function will be called for each reference in the - * repository, receiving the name of the reference and the `payload` value - * passed to this method. Returning a non-zero value from the callback - * will terminate the iteration. - * - * @param repo Repository where to find the refs - * @param callback Function which will be called for every listed ref name - * @param payload Additional data to pass to the callback - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_reference_foreach_name( - git_repository *repo, - git_reference_foreach_name_cb callback, - void *payload); - -/** - * Create a copy of an existing reference. - * - * Call `git_reference_free` to free the data. - * - * @param dest pointer where to store the copy - * @param source object to copy - * @return 0 or an error code - */ -GIT_EXTERN(int) git_reference_dup(git_reference **dest, git_reference *source); - -/** - * Free the given reference. - * - * @param ref git_reference - */ -GIT_EXTERN(void) git_reference_free(git_reference *ref); - -/** - * Compare two references. - * - * @param ref1 The first git_reference - * @param ref2 The second git_reference - * @return 0 if the same, else a stable but meaningless ordering. - */ -GIT_EXTERN(int) git_reference_cmp( - const git_reference *ref1, - const git_reference *ref2); - -/** - * Create an iterator for the repo's references - * - * @param out pointer in which to store the iterator - * @param repo the repository - * @return 0 or an error code - */ -GIT_EXTERN(int) git_reference_iterator_new( - git_reference_iterator **out, - git_repository *repo); - -/** - * Create an iterator for the repo's references that match the - * specified glob - * - * @param out pointer in which to store the iterator - * @param repo the repository - * @param glob the glob to match against the reference names - * @return 0 or an error code - */ -GIT_EXTERN(int) git_reference_iterator_glob_new( - git_reference_iterator **out, - git_repository *repo, - const char *glob); - -/** - * Get the next reference - * - * @param out pointer in which to store the reference - * @param iter the iterator - * @return 0, GIT_ITEROVER if there are no more; or an error code - */ -GIT_EXTERN(int) git_reference_next(git_reference **out, git_reference_iterator *iter); - -/** - * Get the next reference's name - * - * This function is provided for convenience in case only the names - * are interesting as it avoids the allocation of the `git_reference` - * object which `git_reference_next()` needs. - * - * @param out pointer in which to store the string - * @param iter the iterator - * @return 0, GIT_ITEROVER if there are no more; or an error code - */ -GIT_EXTERN(int) git_reference_next_name(const char **out, git_reference_iterator *iter); - -/** - * Free the iterator and its associated resources - * - * @param iter the iterator to free - */ -GIT_EXTERN(void) git_reference_iterator_free(git_reference_iterator *iter); - -/** - * Perform a callback on each reference in the repository whose name - * matches the given pattern. - * - * This function acts like `git_reference_foreach()` with an additional - * pattern match being applied to the reference name before issuing the - * callback function. See that function for more information. - * - * The pattern is matched using fnmatch or "glob" style where a '*' matches - * any sequence of letters, a '?' matches any letter, and square brackets - * can be used to define character ranges (such as "[0-9]" for digits). - * - * @param repo Repository where to find the refs - * @param glob Pattern to match (fnmatch-style) against reference name. - * @param callback Function which will be called for every listed ref - * @param payload Additional data to pass to the callback - * @return 0 on success, GIT_EUSER on non-zero callback, or error code - */ -GIT_EXTERN(int) git_reference_foreach_glob( - git_repository *repo, - const char *glob, - git_reference_foreach_name_cb callback, - void *payload); - -/** - * Check if a reflog exists for the specified reference. - * - * @param repo the repository - * @param refname the reference's name - * @return 0 when no reflog can be found, 1 when it exists; - * otherwise an error code. - */ -GIT_EXTERN(int) git_reference_has_log(git_repository *repo, const char *refname); - -/** - * Ensure there is a reflog for a particular reference. - * - * Make sure that successive updates to the reference will append to - * its log. - * - * @param repo the repository - * @param refname the reference's name - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_reference_ensure_log(git_repository *repo, const char *refname); - -/** - * Check if a reference is a local branch. - * - * @param ref A git reference - * - * @return 1 when the reference lives in the refs/heads - * namespace; 0 otherwise. - */ -GIT_EXTERN(int) git_reference_is_branch(const git_reference *ref); - -/** - * Check if a reference is a remote tracking branch - * - * @param ref A git reference - * - * @return 1 when the reference lives in the refs/remotes - * namespace; 0 otherwise. - */ -GIT_EXTERN(int) git_reference_is_remote(const git_reference *ref); - -/** - * Check if a reference is a tag - * - * @param ref A git reference - * - * @return 1 when the reference lives in the refs/tags - * namespace; 0 otherwise. - */ -GIT_EXTERN(int) git_reference_is_tag(const git_reference *ref); - -/** - * Check if a reference is a note - * - * @param ref A git reference - * - * @return 1 when the reference lives in the refs/notes - * namespace; 0 otherwise. - */ -GIT_EXTERN(int) git_reference_is_note(const git_reference *ref); - -/** - * Normalization options for reference lookup - */ -typedef enum { - /** - * No particular normalization. - */ - GIT_REFERENCE_FORMAT_NORMAL = 0u, - - /** - * Control whether one-level refnames are accepted - * (i.e., refnames that do not contain multiple /-separated - * components). Those are expected to be written only using - * uppercase letters and underscore (FETCH_HEAD, ...) - */ - GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL = (1u << 0), - - /** - * Interpret the provided name as a reference pattern for a - * refspec (as used with remote repositories). If this option - * is enabled, the name is allowed to contain a single * () - * in place of a one full pathname component - * (e.g., foo//bar but not foo/bar). - */ - GIT_REFERENCE_FORMAT_REFSPEC_PATTERN = (1u << 1), - - /** - * Interpret the name as part of a refspec in shorthand form - * so the `ONELEVEL` naming rules aren't enforced and 'master' - * becomes a valid name. - */ - GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND = (1u << 2) -} git_reference_format_t; - -/** - * Normalize reference name and check validity. - * - * This will normalize the reference name by removing any leading slash - * '/' characters and collapsing runs of adjacent slashes between name - * components into a single slash. - * - * Once normalized, if the reference name is valid, it will be returned in - * the user allocated buffer. - * - * See `git_reference_symbolic_create()` for rules about valid names. - * - * @param buffer_out User allocated buffer to store normalized name - * @param buffer_size Size of buffer_out - * @param name Reference name to be checked. - * @param flags Flags to constrain name validation rules - see the - * GIT_REFERENCE_FORMAT constants above. - * @return 0 on success, GIT_EBUFS if buffer is too small, GIT_EINVALIDSPEC - * or an error code. - */ -GIT_EXTERN(int) git_reference_normalize_name( - char *buffer_out, - size_t buffer_size, - const char *name, - unsigned int flags); - -/** - * Recursively peel reference until object of the specified type is found. - * - * The retrieved `peeled` object is owned by the repository - * and should be closed with the `git_object_free` method. - * - * If you pass `GIT_OBJECT_ANY` as the target type, then the object - * will be peeled until a non-tag object is met. - * - * @param out Pointer to the peeled git_object - * @param ref The reference to be processed - * @param type The type of the requested object (GIT_OBJECT_COMMIT, - * GIT_OBJECT_TAG, GIT_OBJECT_TREE, GIT_OBJECT_BLOB or GIT_OBJECT_ANY). - * @return 0 on success, GIT_EAMBIGUOUS, GIT_ENOTFOUND or an error code - */ -GIT_EXTERN(int) git_reference_peel( - git_object **out, - const git_reference *ref, - git_object_t type); - -/** - * Ensure the reference name is well-formed. - * - * Valid reference names must follow one of two patterns: - * - * 1. Top-level names must contain only capital letters and underscores, - * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). - * 2. Names prefixed with "refs/" can be almost anything. You must avoid - * the characters '~', '^', ':', '\\', '?', '[', and '*', and the - * sequences ".." and "@{" which have special meaning to revparse. - * - * @param valid output pointer to set with validity of given reference name - * @param refname name to be checked. - * @return 0 on success or an error code - */ -GIT_EXTERN(int) git_reference_name_is_valid(int *valid, const char *refname); - -/** - * Get the reference's short name - * - * This will transform the reference name into a name "human-readable" - * version. If no shortname is appropriate, it will return the full - * name. - * - * The memory is owned by the reference and must not be freed. - * - * @param ref a reference - * @return the human-readable version of the name - */ -GIT_EXTERN(const char *) git_reference_shorthand(const git_reference *ref); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_refs_h__ +#define INCLUDE_git_refs_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "strarray.h" + +/** + * @file git2/refs.h + * @brief Git reference management routines + * @defgroup git_reference Git reference management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Lookup a reference by name in a repository. + * + * The returned reference must be freed by the user. + * + * The name will be checked for validity. + * See `git_reference_symbolic_create()` for rules about valid names. + * + * @param out pointer to the looked-up reference + * @param repo the repository to look up the reference + * @param name the long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...) + * @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code. + */ +GIT_EXTERN(int) git_reference_lookup(git_reference **out, git_repository *repo, const char *name); + +/** + * Lookup a reference by name and resolve immediately to OID. + * + * This function provides a quick way to resolve a reference name straight + * through to the object id that it refers to. This avoids having to + * allocate or free any `git_reference` objects for simple situations. + * + * The name will be checked for validity. + * See `git_reference_symbolic_create()` for rules about valid names. + * + * @param out Pointer to oid to be filled in + * @param repo The repository in which to look up the reference + * @param name The long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...) + * @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code. + */ +GIT_EXTERN(int) git_reference_name_to_id( + git_oid *out, git_repository *repo, const char *name); + +/** + * Lookup a reference by DWIMing its short name + * + * Apply the git precedence rules to the given shorthand to determine + * which reference the user is referring to. + * + * @param out pointer in which to store the reference + * @param repo the repository in which to look + * @param shorthand the short name for the reference + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, const char *shorthand); + +/** + * Conditionally create a new symbolic reference. + * + * A symbolic reference is a reference name that refers to another + * reference name. If the other name moves, the symbolic name will move, + * too. As a simple example, the "HEAD" reference might refer to + * "refs/heads/master" while on the "master" branch of a repository. + * + * The symbolic reference will be created in the repository and written to + * the disk. The generated reference object must be freed by the user. + * + * Valid reference names must follow one of two patterns: + * + * 1. Top-level names must contain only capital letters and underscores, + * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). + * 2. Names prefixed with "refs/" can be almost anything. You must avoid + * the characters '~', '^', ':', '\\', '?', '[', and '*', and the + * sequences ".." and "@{" which have special meaning to revparse. + * + * This function will return an error if a reference already exists with the + * given name unless `force` is true, in which case it will be overwritten. + * + * The message for the reflog will be ignored if the reference does + * not belong in the standard set (HEAD, branches and remote-tracking + * branches) and it does not have a reflog. + * + * It will return GIT_EMODIFIED if the reference's value at the time + * of updating does not match the one passed through `current_value` + * (i.e. if the ref has changed since the user read it). + * + * If `current_value` is all zeros, this function will return GIT_EMODIFIED + * if the ref already exists. + * + * @param out Pointer to the newly created reference + * @param repo Repository where that reference will live + * @param name The name of the reference + * @param target The target of the reference + * @param force Overwrite existing references + * @param current_value The expected value of the reference when updating + * @param log_message The one line long message to be appended to the reflog + * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC, GIT_EMODIFIED or an error code + */ +GIT_EXTERN(int) git_reference_symbolic_create_matching(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *current_value, const char *log_message); + +/** + * Create a new symbolic reference. + * + * A symbolic reference is a reference name that refers to another + * reference name. If the other name moves, the symbolic name will move, + * too. As a simple example, the "HEAD" reference might refer to + * "refs/heads/master" while on the "master" branch of a repository. + * + * The symbolic reference will be created in the repository and written to + * the disk. The generated reference object must be freed by the user. + * + * Valid reference names must follow one of two patterns: + * + * 1. Top-level names must contain only capital letters and underscores, + * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). + * 2. Names prefixed with "refs/" can be almost anything. You must avoid + * the characters '~', '^', ':', '\\', '?', '[', and '*', and the + * sequences ".." and "@{" which have special meaning to revparse. + * + * This function will return an error if a reference already exists with the + * given name unless `force` is true, in which case it will be overwritten. + * + * The message for the reflog will be ignored if the reference does + * not belong in the standard set (HEAD, branches and remote-tracking + * branches) and it does not have a reflog. + * + * @param out Pointer to the newly created reference + * @param repo Repository where that reference will live + * @param name The name of the reference + * @param target The target of the reference + * @param force Overwrite existing references + * @param log_message The one line long message to be appended to the reflog + * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code + */ +GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *log_message); + +/** + * Create a new direct reference. + * + * A direct reference (also called an object id reference) refers directly + * to a specific object id (a.k.a. OID or SHA) in the repository. The id + * permanently refers to the object (although the reference itself can be + * moved). For example, in libgit2 the direct ref "refs/tags/v0.17.0" + * refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977. + * + * The direct reference will be created in the repository and written to + * the disk. The generated reference object must be freed by the user. + * + * Valid reference names must follow one of two patterns: + * + * 1. Top-level names must contain only capital letters and underscores, + * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). + * 2. Names prefixed with "refs/" can be almost anything. You must avoid + * the characters '~', '^', ':', '\\', '?', '[', and '*', and the + * sequences ".." and "@{" which have special meaning to revparse. + * + * This function will return an error if a reference already exists with the + * given name unless `force` is true, in which case it will be overwritten. + * + * The message for the reflog will be ignored if the reference does + * not belong in the standard set (HEAD, branches and remote-tracking + * branches) and it does not have a reflog. + * + * @param out Pointer to the newly created reference + * @param repo Repository where that reference will live + * @param name The name of the reference + * @param id The object id pointed to by the reference. + * @param force Overwrite existing references + * @param log_message The one line long message to be appended to the reflog + * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code + */ +GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const char *log_message); + +/** + * Conditionally create new direct reference + * + * A direct reference (also called an object id reference) refers directly + * to a specific object id (a.k.a. OID or SHA) in the repository. The id + * permanently refers to the object (although the reference itself can be + * moved). For example, in libgit2 the direct ref "refs/tags/v0.17.0" + * refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977. + * + * The direct reference will be created in the repository and written to + * the disk. The generated reference object must be freed by the user. + * + * Valid reference names must follow one of two patterns: + * + * 1. Top-level names must contain only capital letters and underscores, + * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). + * 2. Names prefixed with "refs/" can be almost anything. You must avoid + * the characters '~', '^', ':', '\\', '?', '[', and '*', and the + * sequences ".." and "@{" which have special meaning to revparse. + * + * This function will return an error if a reference already exists with the + * given name unless `force` is true, in which case it will be overwritten. + * + * The message for the reflog will be ignored if the reference does + * not belong in the standard set (HEAD, branches and remote-tracking + * branches) and it does not have a reflog. + * + * It will return GIT_EMODIFIED if the reference's value at the time + * of updating does not match the one passed through `current_id` + * (i.e. if the ref has changed since the user read it). + * + * @param out Pointer to the newly created reference + * @param repo Repository where that reference will live + * @param name The name of the reference + * @param id The object id pointed to by the reference. + * @param force Overwrite existing references + * @param current_id The expected value of the reference at the time of update + * @param log_message The one line long message to be appended to the reflog + * @return 0 on success, GIT_EMODIFIED if the value of the reference + * has changed, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code + */ +GIT_EXTERN(int) git_reference_create_matching(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const git_oid *current_id, const char *log_message); + +/** + * Get the OID pointed to by a direct reference. + * + * Only available if the reference is direct (i.e. an object id reference, + * not a symbolic one). + * + * To find the OID of a symbolic ref, call `git_reference_resolve()` and + * then this function (or maybe use `git_reference_name_to_id()` to + * directly resolve a reference name all the way through to an OID). + * + * @param ref The reference + * @return a pointer to the oid if available, NULL otherwise + */ +GIT_EXTERN(const git_oid *) git_reference_target(const git_reference *ref); + +/** + * Return the peeled OID target of this reference. + * + * This peeled OID only applies to direct references that point to + * a hard Tag object: it is the result of peeling such Tag. + * + * @param ref The reference + * @return a pointer to the oid if available, NULL otherwise + */ +GIT_EXTERN(const git_oid *) git_reference_target_peel(const git_reference *ref); + +/** + * Get full name to the reference pointed to by a symbolic reference. + * + * Only available if the reference is symbolic. + * + * @param ref The reference + * @return a pointer to the name if available, NULL otherwise + */ +GIT_EXTERN(const char *) git_reference_symbolic_target(const git_reference *ref); + +/** + * Get the type of a reference. + * + * Either direct (GIT_REFERENCE_DIRECT) or symbolic (GIT_REFERENCE_SYMBOLIC) + * + * @param ref The reference + * @return the type + */ +GIT_EXTERN(git_reference_t) git_reference_type(const git_reference *ref); + +/** + * Get the full name of a reference. + * + * See `git_reference_symbolic_create()` for rules about valid names. + * + * @param ref The reference + * @return the full name for the ref + */ +GIT_EXTERN(const char *) git_reference_name(const git_reference *ref); + +/** + * Resolve a symbolic reference to a direct reference. + * + * This method iteratively peels a symbolic reference until it resolves to + * a direct reference to an OID. + * + * The peeled reference is returned in the `resolved_ref` argument, and + * must be freed manually once it's no longer needed. + * + * If a direct reference is passed as an argument, a copy of that + * reference is returned. This copy must be manually freed too. + * + * @param out Pointer to the peeled reference + * @param ref The reference + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reference_resolve(git_reference **out, const git_reference *ref); + +/** + * Get the repository where a reference resides. + * + * @param ref The reference + * @return a pointer to the repo + */ +GIT_EXTERN(git_repository *) git_reference_owner(const git_reference *ref); + +/** + * Create a new reference with the same name as the given reference but a + * different symbolic target. The reference must be a symbolic reference, + * otherwise this will fail. + * + * The new reference will be written to disk, overwriting the given reference. + * + * The target name will be checked for validity. + * See `git_reference_symbolic_create()` for rules about valid names. + * + * The message for the reflog will be ignored if the reference does + * not belong in the standard set (HEAD, branches and remote-tracking + * branches) and it does not have a reflog. + * + * @param out Pointer to the newly created reference + * @param ref The reference + * @param target The new target for the reference + * @param log_message The one line long message to be appended to the reflog + * @return 0 on success, GIT_EINVALIDSPEC or an error code + */ +GIT_EXTERN(int) git_reference_symbolic_set_target( + git_reference **out, + git_reference *ref, + const char *target, + const char *log_message); + +/** + * Conditionally create a new reference with the same name as the given reference but a + * different OID target. The reference must be a direct reference, otherwise + * this will fail. + * + * The new reference will be written to disk, overwriting the given reference. + * + * @param out Pointer to the newly created reference + * @param ref The reference + * @param id The new target OID for the reference + * @param log_message The one line long message to be appended to the reflog + * @return 0 on success, GIT_EMODIFIED if the value of the reference + * has changed since it was read, or an error code + */ +GIT_EXTERN(int) git_reference_set_target( + git_reference **out, + git_reference *ref, + const git_oid *id, + const char *log_message); + +/** + * Rename an existing reference. + * + * This method works for both direct and symbolic references. + * + * The new name will be checked for validity. + * See `git_reference_symbolic_create()` for rules about valid names. + * + * If the `force` flag is not enabled, and there's already + * a reference with the given name, the renaming will fail. + * + * IMPORTANT: + * The user needs to write a proper reflog entry if the + * reflog is enabled for the repository. We only rename + * the reflog if it exists. + * + * @param ref The reference to rename + * @param new_name The new name for the reference + * @param force Overwrite an existing reference + * @param log_message The one line long message to be appended to the reflog + * @return 0 on success, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code + * + */ +GIT_EXTERN(int) git_reference_rename( + git_reference **new_ref, + git_reference *ref, + const char *new_name, + int force, + const char *log_message); + +/** + * Delete an existing reference. + * + * This method works for both direct and symbolic references. The reference + * will be immediately removed on disk but the memory will not be freed. + * Callers must call `git_reference_free`. + * + * This function will return an error if the reference has changed + * from the time it was looked up. + * + * @param ref The reference to remove + * @return 0, GIT_EMODIFIED or an error code + */ +GIT_EXTERN(int) git_reference_delete(git_reference *ref); + +/** + * Delete an existing reference by name + * + * This method removes the named reference from the repository without + * looking at its old value. + * + * @param name The reference to remove + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reference_remove(git_repository *repo, const char *name); + +/** + * Fill a list with all the references that can be found in a repository. + * + * The string array will be filled with the names of all references; these + * values are owned by the user and should be free'd manually when no + * longer needed, using `git_strarray_free()`. + * + * @param array Pointer to a git_strarray structure where + * the reference names will be stored + * @param repo Repository where to find the refs + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo); + +/** + * Callback used to iterate over references + * + * @see git_reference_foreach + * + * @param reference The reference object + * @param payload Payload passed to git_reference_foreach + * @return non-zero to terminate the iteration + */ +typedef int GIT_CALLBACK(git_reference_foreach_cb)(git_reference *reference, void *payload); + +/** + * Callback used to iterate over reference names + * + * @see git_reference_foreach_name + * + * @param name The reference name + * @param payload Payload passed to git_reference_foreach_name + * @return non-zero to terminate the iteration + */ +typedef int GIT_CALLBACK(git_reference_foreach_name_cb)(const char *name, void *payload); + +/** + * Perform a callback on each reference in the repository. + * + * The `callback` function will be called for each reference in the + * repository, receiving the reference object and the `payload` value + * passed to this method. Returning a non-zero value from the callback + * will terminate the iteration. + * + * Note that the callback function is responsible to call `git_reference_free` + * on each reference passed to it. + * + * @param repo Repository where to find the refs + * @param callback Function which will be called for every listed ref + * @param payload Additional data to pass to the callback + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_reference_foreach( + git_repository *repo, + git_reference_foreach_cb callback, + void *payload); + +/** + * Perform a callback on the fully-qualified name of each reference. + * + * The `callback` function will be called for each reference in the + * repository, receiving the name of the reference and the `payload` value + * passed to this method. Returning a non-zero value from the callback + * will terminate the iteration. + * + * @param repo Repository where to find the refs + * @param callback Function which will be called for every listed ref name + * @param payload Additional data to pass to the callback + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_reference_foreach_name( + git_repository *repo, + git_reference_foreach_name_cb callback, + void *payload); + +/** + * Create a copy of an existing reference. + * + * Call `git_reference_free` to free the data. + * + * @param dest pointer where to store the copy + * @param source object to copy + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reference_dup(git_reference **dest, git_reference *source); + +/** + * Free the given reference. + * + * @param ref git_reference + */ +GIT_EXTERN(void) git_reference_free(git_reference *ref); + +/** + * Compare two references. + * + * @param ref1 The first git_reference + * @param ref2 The second git_reference + * @return 0 if the same, else a stable but meaningless ordering. + */ +GIT_EXTERN(int) git_reference_cmp( + const git_reference *ref1, + const git_reference *ref2); + +/** + * Create an iterator for the repo's references + * + * @param out pointer in which to store the iterator + * @param repo the repository + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reference_iterator_new( + git_reference_iterator **out, + git_repository *repo); + +/** + * Create an iterator for the repo's references that match the + * specified glob + * + * @param out pointer in which to store the iterator + * @param repo the repository + * @param glob the glob to match against the reference names + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reference_iterator_glob_new( + git_reference_iterator **out, + git_repository *repo, + const char *glob); + +/** + * Get the next reference + * + * @param out pointer in which to store the reference + * @param iter the iterator + * @return 0, GIT_ITEROVER if there are no more; or an error code + */ +GIT_EXTERN(int) git_reference_next(git_reference **out, git_reference_iterator *iter); + +/** + * Get the next reference's name + * + * This function is provided for convenience in case only the names + * are interesting as it avoids the allocation of the `git_reference` + * object which `git_reference_next()` needs. + * + * @param out pointer in which to store the string + * @param iter the iterator + * @return 0, GIT_ITEROVER if there are no more; or an error code + */ +GIT_EXTERN(int) git_reference_next_name(const char **out, git_reference_iterator *iter); + +/** + * Free the iterator and its associated resources + * + * @param iter the iterator to free + */ +GIT_EXTERN(void) git_reference_iterator_free(git_reference_iterator *iter); + +/** + * Perform a callback on each reference in the repository whose name + * matches the given pattern. + * + * This function acts like `git_reference_foreach()` with an additional + * pattern match being applied to the reference name before issuing the + * callback function. See that function for more information. + * + * The pattern is matched using fnmatch or "glob" style where a '*' matches + * any sequence of letters, a '?' matches any letter, and square brackets + * can be used to define character ranges (such as "[0-9]" for digits). + * + * @param repo Repository where to find the refs + * @param glob Pattern to match (fnmatch-style) against reference name. + * @param callback Function which will be called for every listed ref + * @param payload Additional data to pass to the callback + * @return 0 on success, GIT_EUSER on non-zero callback, or error code + */ +GIT_EXTERN(int) git_reference_foreach_glob( + git_repository *repo, + const char *glob, + git_reference_foreach_name_cb callback, + void *payload); + +/** + * Check if a reflog exists for the specified reference. + * + * @param repo the repository + * @param refname the reference's name + * @return 0 when no reflog can be found, 1 when it exists; + * otherwise an error code. + */ +GIT_EXTERN(int) git_reference_has_log(git_repository *repo, const char *refname); + +/** + * Ensure there is a reflog for a particular reference. + * + * Make sure that successive updates to the reference will append to + * its log. + * + * @param repo the repository + * @param refname the reference's name + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_reference_ensure_log(git_repository *repo, const char *refname); + +/** + * Check if a reference is a local branch. + * + * @param ref A git reference + * + * @return 1 when the reference lives in the refs/heads + * namespace; 0 otherwise. + */ +GIT_EXTERN(int) git_reference_is_branch(const git_reference *ref); + +/** + * Check if a reference is a remote tracking branch + * + * @param ref A git reference + * + * @return 1 when the reference lives in the refs/remotes + * namespace; 0 otherwise. + */ +GIT_EXTERN(int) git_reference_is_remote(const git_reference *ref); + +/** + * Check if a reference is a tag + * + * @param ref A git reference + * + * @return 1 when the reference lives in the refs/tags + * namespace; 0 otherwise. + */ +GIT_EXTERN(int) git_reference_is_tag(const git_reference *ref); + +/** + * Check if a reference is a note + * + * @param ref A git reference + * + * @return 1 when the reference lives in the refs/notes + * namespace; 0 otherwise. + */ +GIT_EXTERN(int) git_reference_is_note(const git_reference *ref); + +/** + * Normalization options for reference lookup + */ +typedef enum { + /** + * No particular normalization. + */ + GIT_REFERENCE_FORMAT_NORMAL = 0u, + + /** + * Control whether one-level refnames are accepted + * (i.e., refnames that do not contain multiple /-separated + * components). Those are expected to be written only using + * uppercase letters and underscore (FETCH_HEAD, ...) + */ + GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL = (1u << 0), + + /** + * Interpret the provided name as a reference pattern for a + * refspec (as used with remote repositories). If this option + * is enabled, the name is allowed to contain a single * () + * in place of a one full pathname component + * (e.g., foo//bar but not foo/bar). + */ + GIT_REFERENCE_FORMAT_REFSPEC_PATTERN = (1u << 1), + + /** + * Interpret the name as part of a refspec in shorthand form + * so the `ONELEVEL` naming rules aren't enforced and 'master' + * becomes a valid name. + */ + GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND = (1u << 2) +} git_reference_format_t; + +/** + * Normalize reference name and check validity. + * + * This will normalize the reference name by removing any leading slash + * '/' characters and collapsing runs of adjacent slashes between name + * components into a single slash. + * + * Once normalized, if the reference name is valid, it will be returned in + * the user allocated buffer. + * + * See `git_reference_symbolic_create()` for rules about valid names. + * + * @param buffer_out User allocated buffer to store normalized name + * @param buffer_size Size of buffer_out + * @param name Reference name to be checked. + * @param flags Flags to constrain name validation rules - see the + * GIT_REFERENCE_FORMAT constants above. + * @return 0 on success, GIT_EBUFS if buffer is too small, GIT_EINVALIDSPEC + * or an error code. + */ +GIT_EXTERN(int) git_reference_normalize_name( + char *buffer_out, + size_t buffer_size, + const char *name, + unsigned int flags); + +/** + * Recursively peel reference until object of the specified type is found. + * + * The retrieved `peeled` object is owned by the repository + * and should be closed with the `git_object_free` method. + * + * If you pass `GIT_OBJECT_ANY` as the target type, then the object + * will be peeled until a non-tag object is met. + * + * @param out Pointer to the peeled git_object + * @param ref The reference to be processed + * @param type The type of the requested object (GIT_OBJECT_COMMIT, + * GIT_OBJECT_TAG, GIT_OBJECT_TREE, GIT_OBJECT_BLOB or GIT_OBJECT_ANY). + * @return 0 on success, GIT_EAMBIGUOUS, GIT_ENOTFOUND or an error code + */ +GIT_EXTERN(int) git_reference_peel( + git_object **out, + const git_reference *ref, + git_object_t type); + +/** + * Ensure the reference name is well-formed. + * + * Valid reference names must follow one of two patterns: + * + * 1. Top-level names must contain only capital letters and underscores, + * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). + * 2. Names prefixed with "refs/" can be almost anything. You must avoid + * the characters '~', '^', ':', '\\', '?', '[', and '*', and the + * sequences ".." and "@{" which have special meaning to revparse. + * + * @param valid output pointer to set with validity of given reference name + * @param refname name to be checked. + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_reference_name_is_valid(int *valid, const char *refname); + +/** + * Get the reference's short name + * + * This will transform the reference name into a name "human-readable" + * version. If no shortname is appropriate, it will return the full + * name. + * + * The memory is owned by the reference and must not be freed. + * + * @param ref a reference + * @return the human-readable version of the name + */ +GIT_EXTERN(const char *) git_reference_shorthand(const git_reference *ref); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/refspec.h b/3rdparty/libgit2/include/git2/refspec.h index eaf7747..7ffcd73 100644 --- a/3rdparty/libgit2/include/git2/refspec.h +++ b/3rdparty/libgit2/include/git2/refspec.h @@ -1,121 +1,121 @@ -/* - * 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_refspec_h__ -#define INCLUDE_git_refspec_h__ - -#include "common.h" -#include "types.h" -#include "net.h" -#include "buffer.h" - -/** - * @file git2/refspec.h - * @brief Git refspec attributes - * @defgroup git_refspec Git refspec attributes - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Parse a given refspec string - * - * @param refspec a pointer to hold the refspec handle - * @param input the refspec string - * @param is_fetch is this a refspec for a fetch - * @return 0 if the refspec string could be parsed, -1 otherwise - */ -GIT_EXTERN(int) git_refspec_parse(git_refspec **refspec, const char *input, int is_fetch); - -/** - * Free a refspec object which has been created by git_refspec_parse - * - * @param refspec the refspec object - */ -GIT_EXTERN(void) git_refspec_free(git_refspec *refspec); - -/** - * Get the source specifier - * - * @param refspec the refspec - * @return the refspec's source specifier - */ -GIT_EXTERN(const char *) git_refspec_src(const git_refspec *refspec); - -/** - * Get the destination specifier - * - * @param refspec the refspec - * @return the refspec's destination specifier - */ -GIT_EXTERN(const char *) git_refspec_dst(const git_refspec *refspec); - -/** - * Get the refspec's string - * - * @param refspec the refspec - * @returns the refspec's original string - */ -GIT_EXTERN(const char *) git_refspec_string(const git_refspec *refspec); - -/** - * Get the force update setting - * - * @param refspec the refspec - * @return 1 if force update has been set, 0 otherwise - */ -GIT_EXTERN(int) git_refspec_force(const git_refspec *refspec); - -/** - * Get the refspec's direction. - * - * @param spec refspec - * @return GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH - */ -GIT_EXTERN(git_direction) git_refspec_direction(const git_refspec *spec); - -/** - * Check if a refspec's source descriptor matches a reference - * - * @param refspec the refspec - * @param refname the name of the reference to check - * @return 1 if the refspec matches, 0 otherwise - */ -GIT_EXTERN(int) git_refspec_src_matches(const git_refspec *refspec, const char *refname); - -/** - * Check if a refspec's destination descriptor matches a reference - * - * @param refspec the refspec - * @param refname the name of the reference to check - * @return 1 if the refspec matches, 0 otherwise - */ -GIT_EXTERN(int) git_refspec_dst_matches(const git_refspec *refspec, const char *refname); - -/** - * Transform a reference to its target following the refspec's rules - * - * @param out where to store the target name - * @param spec the refspec - * @param name the name of the reference to transform - * @return 0, GIT_EBUFS or another error - */ -GIT_EXTERN(int) git_refspec_transform(git_buf *out, const git_refspec *spec, const char *name); - -/** - * Transform a target reference to its source reference following the refspec's rules - * - * @param out where to store the source reference name - * @param spec the refspec - * @param name the name of the reference to transform - * @return 0, GIT_EBUFS or another error - */ -GIT_EXTERN(int) git_refspec_rtransform(git_buf *out, const git_refspec *spec, const char *name); - -GIT_END_DECL - -#endif +/* + * 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_refspec_h__ +#define INCLUDE_git_refspec_h__ + +#include "common.h" +#include "types.h" +#include "net.h" +#include "buffer.h" + +/** + * @file git2/refspec.h + * @brief Git refspec attributes + * @defgroup git_refspec Git refspec attributes + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Parse a given refspec string + * + * @param refspec a pointer to hold the refspec handle + * @param input the refspec string + * @param is_fetch is this a refspec for a fetch + * @return 0 if the refspec string could be parsed, -1 otherwise + */ +GIT_EXTERN(int) git_refspec_parse(git_refspec **refspec, const char *input, int is_fetch); + +/** + * Free a refspec object which has been created by git_refspec_parse + * + * @param refspec the refspec object + */ +GIT_EXTERN(void) git_refspec_free(git_refspec *refspec); + +/** + * Get the source specifier + * + * @param refspec the refspec + * @return the refspec's source specifier + */ +GIT_EXTERN(const char *) git_refspec_src(const git_refspec *refspec); + +/** + * Get the destination specifier + * + * @param refspec the refspec + * @return the refspec's destination specifier + */ +GIT_EXTERN(const char *) git_refspec_dst(const git_refspec *refspec); + +/** + * Get the refspec's string + * + * @param refspec the refspec + * @returns the refspec's original string + */ +GIT_EXTERN(const char *) git_refspec_string(const git_refspec *refspec); + +/** + * Get the force update setting + * + * @param refspec the refspec + * @return 1 if force update has been set, 0 otherwise + */ +GIT_EXTERN(int) git_refspec_force(const git_refspec *refspec); + +/** + * Get the refspec's direction. + * + * @param spec refspec + * @return GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH + */ +GIT_EXTERN(git_direction) git_refspec_direction(const git_refspec *spec); + +/** + * Check if a refspec's source descriptor matches a reference + * + * @param refspec the refspec + * @param refname the name of the reference to check + * @return 1 if the refspec matches, 0 otherwise + */ +GIT_EXTERN(int) git_refspec_src_matches(const git_refspec *refspec, const char *refname); + +/** + * Check if a refspec's destination descriptor matches a reference + * + * @param refspec the refspec + * @param refname the name of the reference to check + * @return 1 if the refspec matches, 0 otherwise + */ +GIT_EXTERN(int) git_refspec_dst_matches(const git_refspec *refspec, const char *refname); + +/** + * Transform a reference to its target following the refspec's rules + * + * @param out where to store the target name + * @param spec the refspec + * @param name the name of the reference to transform + * @return 0, GIT_EBUFS or another error + */ +GIT_EXTERN(int) git_refspec_transform(git_buf *out, const git_refspec *spec, const char *name); + +/** + * Transform a target reference to its source reference following the refspec's rules + * + * @param out where to store the source reference name + * @param spec the refspec + * @param name the name of the reference to transform + * @return 0, GIT_EBUFS or another error + */ +GIT_EXTERN(int) git_refspec_rtransform(git_buf *out, const git_refspec *spec, const char *name); + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/remote.h b/3rdparty/libgit2/include/git2/remote.h index 7067c88..038a401 100644 --- a/3rdparty/libgit2/include/git2/remote.h +++ b/3rdparty/libgit2/include/git2/remote.h @@ -1,1195 +1,1195 @@ -/* - * 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_remote_h__ -#define INCLUDE_git_remote_h__ - -#include "common.h" -#include "repository.h" -#include "refspec.h" -#include "net.h" -#include "indexer.h" -#include "strarray.h" -#include "transport.h" -#include "pack.h" -#include "proxy.h" - -/** - * @file git2/remote.h - * @brief Git remote management functions - * @defgroup git_remote remote management functions - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Add a remote with the default fetch refspec to the repository's configuration. - * - * @param out the resulting remote - * @param repo the repository in which to create the remote - * @param name the remote's name - * @param url the remote's url - * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code - */ -GIT_EXTERN(int) git_remote_create( - git_remote **out, - git_repository *repo, - const char *name, - const char *url); - -/** - * Remote redirection settings; whether redirects to another host - * are permitted. By default, git will follow a redirect on the - * initial request (`/info/refs`), but not subsequent requests. - */ -typedef enum { - /** - * Do not follow any off-site redirects at any stage of - * the fetch or push. - */ - GIT_REMOTE_REDIRECT_NONE = (1 << 0), - - /** - * Allow off-site redirects only upon the initial request. - * This is the default. - */ - GIT_REMOTE_REDIRECT_INITIAL = (1 << 1), - - /** - * Allow redirects at any stage in the fetch or push. - */ - GIT_REMOTE_REDIRECT_ALL = (1 << 2) -} git_remote_redirect_t; - -/** - * Remote creation options flags - */ -typedef enum { - /** Ignore the repository apply.insteadOf configuration */ - GIT_REMOTE_CREATE_SKIP_INSTEADOF = (1 << 0), - - /** Don't build a fetchspec from the name if none is set */ - GIT_REMOTE_CREATE_SKIP_DEFAULT_FETCHSPEC = (1 << 1) -} git_remote_create_flags; - -/** - * How to handle reference updates. - */ -typedef enum { - /* Write the fetch results to FETCH_HEAD. */ - GIT_REMOTE_UPDATE_FETCHHEAD = (1 << 0), - - /* Report unchanged tips in the update_tips callback. */ - GIT_REMOTE_UPDATE_REPORT_UNCHANGED = (1 << 1) -} git_remote_update_flags; - -/** - * Remote creation options structure - * - * Initialize with `GIT_REMOTE_CREATE_OPTIONS_INIT`. Alternatively, you can - * use `git_remote_create_options_init`. - * - */ -typedef struct git_remote_create_options { - unsigned int version; - - /** - * The repository that should own the remote. - * Setting this to NULL results in a detached remote. - */ - git_repository *repository; - - /** - * The remote's name. - * Setting this to NULL results in an in-memory/anonymous remote. - */ - const char *name; - - /** The fetchspec the remote should use. */ - const char *fetchspec; - - /** Additional flags for the remote. See git_remote_create_flags. */ - unsigned int flags; -} git_remote_create_options; - -#define GIT_REMOTE_CREATE_OPTIONS_VERSION 1 -#define GIT_REMOTE_CREATE_OPTIONS_INIT {GIT_REMOTE_CREATE_OPTIONS_VERSION} - -/** - * Initialize git_remote_create_options structure - * - * Initializes a `git_remote_create_options` with default values. Equivalent to - * creating an instance with `GIT_REMOTE_CREATE_OPTIONS_INIT`. - * - * @param opts The `git_remote_create_options` struct to initialize. - * @param version The struct version; pass `GIT_REMOTE_CREATE_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_remote_create_options_init( - git_remote_create_options *opts, - unsigned int version); - -/** - * Create a remote, with options. - * - * This function allows more fine-grained control over the remote creation. - * - * Passing NULL as the opts argument will result in a detached remote. - * - * @param out the resulting remote - * @param url the remote's url - * @param opts the remote creation options - * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code - */ -GIT_EXTERN(int) git_remote_create_with_opts( - git_remote **out, - const char *url, - const git_remote_create_options *opts); - -/** - * Add a remote with the provided fetch refspec (or default if NULL) to the repository's - * configuration. - * - * @param out the resulting remote - * @param repo the repository in which to create the remote - * @param name the remote's name - * @param url the remote's url - * @param fetch the remote fetch value - * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code - */ -GIT_EXTERN(int) git_remote_create_with_fetchspec( - git_remote **out, - git_repository *repo, - const char *name, - const char *url, - const char *fetch); - -/** - * Create an anonymous remote - * - * Create a remote with the given url in-memory. You can use this when - * you have a URL instead of a remote's name. - * - * @param out pointer to the new remote objects - * @param repo the associated repository - * @param url the remote repository's URL - * @return 0 or an error code - */ -GIT_EXTERN(int) git_remote_create_anonymous( - git_remote **out, - git_repository *repo, - const char *url); - -/** - * Create a remote without a connected local repo - * - * Create a remote with the given url in-memory. You can use this when - * you have a URL instead of a remote's name. - * - * Contrasted with git_remote_create_anonymous, a detached remote - * will not consider any repo configuration values (such as insteadof url - * substitutions). - * - * @param out pointer to the new remote objects - * @param url the remote repository's URL - * @return 0 or an error code - */ -GIT_EXTERN(int) git_remote_create_detached( - git_remote **out, - const char *url); - -/** - * Get the information for a particular remote - * - * The name will be checked for validity. - * See `git_tag_create()` for rules about valid names. - * - * @param out pointer to the new remote object - * @param repo the associated repository - * @param name the remote's name - * @return 0, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code - */ -GIT_EXTERN(int) git_remote_lookup(git_remote **out, git_repository *repo, const char *name); - -/** - * Create a copy of an existing remote. All internal strings are also - * duplicated. Callbacks are not duplicated. - * - * Call `git_remote_free` to free the data. - * - * @param dest pointer where to store the copy - * @param source object to copy - * @return 0 or an error code - */ -GIT_EXTERN(int) git_remote_dup(git_remote **dest, git_remote *source); - -/** - * Get the remote's repository - * - * @param remote the remote - * @return a pointer to the repository - */ -GIT_EXTERN(git_repository *) git_remote_owner(const git_remote *remote); - -/** - * Get the remote's name - * - * @param remote the remote - * @return a pointer to the name or NULL for in-memory remotes - */ -GIT_EXTERN(const char *) git_remote_name(const git_remote *remote); - -/** - * Get the remote's url - * - * If url.*.insteadOf has been configured for this URL, it will - * return the modified URL. If `git_remote_set_instance_pushurl` - * has been called for this remote, then that URL will be returned. - * - * @param remote the remote - * @return a pointer to the url - */ -GIT_EXTERN(const char *) git_remote_url(const git_remote *remote); - -/** - * Get the remote's url for pushing. - * - * If url.*.pushInsteadOf has been configured for this URL, it - * will return the modified URL. If `git_remote_set_instance_pushurl` - * has been called for this remote, then that URL will be returned. - * - * @param remote the remote - * @return a pointer to the url or NULL if no special url for pushing is set - */ -GIT_EXTERN(const char *) git_remote_pushurl(const git_remote *remote); - -/** - * Set the remote's url in the configuration - * - * Remote objects already in memory will not be affected. This assumes - * the common case of a single-url remote and will otherwise return an error. - * - * @param repo the repository in which to perform the change - * @param remote the remote's name - * @param url the url to set - * @return 0 or an error value - */ -GIT_EXTERN(int) git_remote_set_url(git_repository *repo, const char *remote, const char *url); - -/** - * Set the remote's url for pushing in the configuration. - * - * Remote objects already in memory will not be affected. This assumes - * the common case of a single-url remote and will otherwise return an error. - * - * - * @param repo the repository in which to perform the change - * @param remote the remote's name - * @param url the url to set - * @return 0, or an error code - */ -GIT_EXTERN(int) git_remote_set_pushurl(git_repository *repo, const char *remote, const char *url); - -/** - * Set the url for this particular url instance. The URL in the - * configuration will be ignored, and will not be changed. - * - * @param remote the remote's name - * @param url the url to set - * @return 0 or an error value - */ -GIT_EXTERN(int) git_remote_set_instance_url(git_remote *remote, const char *url); - -/** - * Set the push url for this particular url instance. The URL in the - * configuration will be ignored, and will not be changed. - * - * @param remote the remote's name - * @param url the url to set - * @return 0 or an error value - */ -GIT_EXTERN(int) git_remote_set_instance_pushurl(git_remote *remote, const char *url); - -/** - * Add a fetch refspec to the remote's configuration - * - * Add the given refspec to the fetch list in the configuration. No - * loaded remote instances will be affected. - * - * @param repo the repository in which to change the configuration - * @param remote the name of the remote to change - * @param refspec the new fetch refspec - * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value - */ -GIT_EXTERN(int) git_remote_add_fetch(git_repository *repo, const char *remote, const char *refspec); - -/** - * Get the remote's list of fetch refspecs - * - * The memory is owned by the user and should be freed with - * `git_strarray_free`. - * - * @param array pointer to the array in which to store the strings - * @param remote the remote to query - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_remote_get_fetch_refspecs(git_strarray *array, const git_remote *remote); - -/** - * Add a push refspec to the remote's configuration - * - * Add the given refspec to the push list in the configuration. No - * loaded remote instances will be affected. - * - * @param repo the repository in which to change the configuration - * @param remote the name of the remote to change - * @param refspec the new push refspec - * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value - */ -GIT_EXTERN(int) git_remote_add_push(git_repository *repo, const char *remote, const char *refspec); - -/** - * Get the remote's list of push refspecs - * - * The memory is owned by the user and should be freed with - * `git_strarray_free`. - * - * @param array pointer to the array in which to store the strings - * @param remote the remote to query - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_remote_get_push_refspecs(git_strarray *array, const git_remote *remote); - -/** - * Get the number of refspecs for a remote - * - * @param remote the remote - * @return the amount of refspecs configured in this remote - */ -GIT_EXTERN(size_t) git_remote_refspec_count(const git_remote *remote); - -/** - * Get a refspec from the remote - * - * @param remote the remote to query - * @param n the refspec to get - * @return the nth refspec - */ -GIT_EXTERN(const git_refspec *)git_remote_get_refspec(const git_remote *remote, size_t n); - -/** - * Get the remote repository's reference advertisement list - * - * Get the list of references with which the server responds to a new - * connection. - * - * The remote (or more exactly its transport) must have connected to - * the remote repository. This list is available as soon as the - * connection to the remote is initiated and it remains available - * after disconnecting. - * - * The memory belongs to the remote. The pointer will be valid as long - * as a new connection is not initiated, but it is recommended that - * you make a copy in order to make use of the data. - * - * @param out pointer to the array - * @param size the number of remote heads - * @param remote the remote - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_remote_ls(const git_remote_head ***out, size_t *size, git_remote *remote); - -/** - * Check whether the remote is connected - * - * Check whether the remote's underlying transport is connected to the - * remote host. - * - * @param remote the remote - * @return 1 if it's connected, 0 otherwise. - */ -GIT_EXTERN(int) git_remote_connected(const git_remote *remote); - -/** - * Cancel the operation - * - * At certain points in its operation, the network code checks whether - * the operation has been cancelled and if so stops the operation. - * - * @param remote the remote - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_remote_stop(git_remote *remote); - -/** - * Disconnect from the remote - * - * Close the connection to the remote. - * - * @param remote the remote to disconnect from - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_remote_disconnect(git_remote *remote); - -/** - * Free the memory associated with a remote - * - * This also disconnects from the remote, if the connection - * has not been closed yet (using git_remote_disconnect). - * - * @param remote the remote to free - */ -GIT_EXTERN(void) git_remote_free(git_remote *remote); - -/** - * Get a list of the configured remotes for a repo - * - * The string array must be freed by the user. - * - * @param out a string array which receives the names of the remotes - * @param repo the repository to query - * @return 0 or an error code - */ -GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo); - -/** - * Argument to the completion callback which tells it which operation - * finished. - */ -typedef enum git_remote_completion_t { - GIT_REMOTE_COMPLETION_DOWNLOAD, - GIT_REMOTE_COMPLETION_INDEXING, - GIT_REMOTE_COMPLETION_ERROR -} git_remote_completion_t; - -/** Push network progress notification function */ -typedef int GIT_CALLBACK(git_push_transfer_progress_cb)( - unsigned int current, - unsigned int total, - size_t bytes, - void *payload); - -/** - * Represents an update which will be performed on the remote during push - */ -typedef struct { - /** - * The source name of the reference - */ - char *src_refname; - /** - * The name of the reference to update on the server - */ - char *dst_refname; - /** - * The current target of the reference - */ - git_oid src; - /** - * The new target for the reference - */ - git_oid dst; -} git_push_update; - -/** - * Callback used to inform of upcoming updates. - * - * @param updates an array containing the updates which will be sent - * as commands to the destination. - * @param len number of elements in `updates` - * @param payload Payload provided by the caller - */ -typedef int GIT_CALLBACK(git_push_negotiation)(const git_push_update **updates, size_t len, void *payload); - -/** - * Callback used to inform of the update status from the remote. - * - * Called for each updated reference on push. If `status` is - * not `NULL`, the update was rejected by the remote server - * and `status` contains the reason given. - * - * @param refname refname specifying to the remote ref - * @param status status message sent from the remote - * @param data data provided by the caller - * @return 0 on success, otherwise an error - */ -typedef int GIT_CALLBACK(git_push_update_reference_cb)(const char *refname, const char *status, void *data); - -#ifndef GIT_DEPRECATE_HARD -/** - * Callback to resolve URLs before connecting to remote - * - * If you return GIT_PASSTHROUGH, you don't need to write anything to - * url_resolved. - * - * @param url_resolved The buffer to write the resolved URL to - * @param url The URL to resolve - * @param direction GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH - * @param payload Payload provided by the caller - * @return 0 on success, GIT_PASSTHROUGH or an error - * @deprecated Use `git_remote_set_instance_url` - */ -typedef int GIT_CALLBACK(git_url_resolve_cb)(git_buf *url_resolved, const char *url, int direction, void *payload); -#endif - -/** - * Callback invoked immediately before we attempt to connect to the - * given url. Callers may change the URL before the connection by - * calling `git_remote_set_instance_url` in the callback. - * - * @param remote The remote to be connected - * @param direction GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH - * @param payload Payload provided by the caller - * @return 0 on success, or an error - */ -typedef int GIT_CALLBACK(git_remote_ready_cb)(git_remote *remote, int direction, void *payload); - -/** - * The callback settings structure - * - * Set the callbacks to be called by the remote when informing the user - * about the progress of the network operations. - */ -struct git_remote_callbacks { - unsigned int version; /**< The version */ - - /** - * Textual progress from the remote. Text send over the - * progress side-band will be passed to this function (this is - * the 'counting objects' output). - */ - git_transport_message_cb sideband_progress; - - /** - * Completion is called when different parts of the download - * process are done (currently unused). - */ - int GIT_CALLBACK(completion)(git_remote_completion_t type, void *data); - - /** - * This will be called if the remote host requires - * authentication in order to connect to it. - * - * Returning GIT_PASSTHROUGH will make libgit2 behave as - * though this field isn't set. - */ - git_credential_acquire_cb credentials; - - /** - * If cert verification fails, this will be called to let the - * user make the final decision of whether to allow the - * connection to proceed. Returns 0 to allow the connection - * or a negative value to indicate an error. - */ - git_transport_certificate_check_cb certificate_check; - - /** - * During the download of new data, this will be regularly - * called with the current count of progress done by the - * indexer. - */ - git_indexer_progress_cb transfer_progress; - - /** - * Each time a reference is updated locally, this function - * will be called with information about it. - */ - int GIT_CALLBACK(update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data); - - /** - * Function to call with progress information during pack - * building. Be aware that this is called inline with pack - * building operations, so performance may be affected. - */ - git_packbuilder_progress pack_progress; - - /** - * Function to call with progress information during the - * upload portion of a push. Be aware that this is called - * inline with pack building operations, so performance may be - * affected. - */ - git_push_transfer_progress_cb push_transfer_progress; - - /** - * See documentation of git_push_update_reference_cb - */ - git_push_update_reference_cb push_update_reference; - - /** - * Called once between the negotiation step and the upload. It - * provides information about what updates will be performed. - */ - git_push_negotiation push_negotiation; - - /** - * Create the transport to use for this operation. Leave NULL - * to auto-detect. - */ - git_transport_cb transport; - - /** - * Callback when the remote is ready to connect. - */ - git_remote_ready_cb remote_ready; - - /** - * This will be passed to each of the callbacks in this struct - * as the last parameter. - */ - void *payload; - -#ifdef GIT_DEPRECATE_HARD - void *reserved; -#else - /** - * Resolve URL before connecting to remote. - * The returned URL will be used to connect to the remote instead. - * - * This callback is deprecated; users should use - * git_remote_ready_cb and configure the instance URL instead. - */ - git_url_resolve_cb resolve_url; -#endif -}; - -#define GIT_REMOTE_CALLBACKS_VERSION 1 -#define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION} - -/** - * Initializes a `git_remote_callbacks` with default values. Equivalent to - * creating an instance with GIT_REMOTE_CALLBACKS_INIT. - * - * @param opts the `git_remote_callbacks` struct to initialize - * @param version Version of struct; pass `GIT_REMOTE_CALLBACKS_VERSION` - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_remote_init_callbacks( - git_remote_callbacks *opts, - unsigned int version); - -/** Acceptable prune settings when fetching */ -typedef enum { - /** - * Use the setting from the configuration - */ - GIT_FETCH_PRUNE_UNSPECIFIED, - /** - * Force pruning on - */ - GIT_FETCH_PRUNE, - /** - * Force pruning off - */ - GIT_FETCH_NO_PRUNE -} git_fetch_prune_t; - -/** - * Automatic tag following option - * - * Lets us select the --tags option to use. - */ -typedef enum { - /** - * Use the setting from the configuration. - */ - GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED = 0, - /** - * Ask the server for tags pointing to objects we're already - * downloading. - */ - GIT_REMOTE_DOWNLOAD_TAGS_AUTO, - /** - * Don't ask for any tags beyond the refspecs. - */ - GIT_REMOTE_DOWNLOAD_TAGS_NONE, - /** - * Ask for the all the tags. - */ - GIT_REMOTE_DOWNLOAD_TAGS_ALL -} git_remote_autotag_option_t; - -/** Constants for fetch depth (shallowness of fetch). */ -typedef enum { - /** The fetch is "full" (not shallow). This is the default. */ - GIT_FETCH_DEPTH_FULL = 0, - - /** The fetch should "unshallow" and fetch missing data. */ - GIT_FETCH_DEPTH_UNSHALLOW = 2147483647 -} git_fetch_depth_t; - -/** - * Fetch options structure. - * - * Zero out for defaults. Initialize with `GIT_FETCH_OPTIONS_INIT` macro to - * correctly set the `version` field. E.g. - * - * git_fetch_options opts = GIT_FETCH_OPTIONS_INIT; - */ -typedef struct { - int version; - - /** - * Callbacks to use for this fetch operation - */ - git_remote_callbacks callbacks; - - /** - * Whether to perform a prune after the fetch - */ - git_fetch_prune_t prune; - - /** - * How to handle reference updates; see `git_remote_update_flags`. - */ - unsigned int update_fetchhead : 1, - report_unchanged : 1; - - /** - * Determines how to behave regarding tags on the remote, such - * as auto-downloading tags for objects we're downloading or - * downloading all of them. - * - * The default is to auto-follow tags. - */ - git_remote_autotag_option_t download_tags; - - /** - * Proxy options to use, by default no proxy is used. - */ - git_proxy_options proxy_opts; - - /** - * Depth of the fetch to perform, or `GIT_FETCH_DEPTH_FULL` - * (or `0`) for full history, or `GIT_FETCH_DEPTH_UNSHALLOW` - * to "unshallow" a shallow repository. - * - * The default is full (`GIT_FETCH_DEPTH_FULL` or `0`). - */ - int depth; - - /** - * Whether to allow off-site redirects. If this is not - * specified, the `http.followRedirects` configuration setting - * will be consulted. - */ - git_remote_redirect_t follow_redirects; - - /** - * Extra headers for this fetch operation - */ - git_strarray custom_headers; -} git_fetch_options; - -#define GIT_FETCH_OPTIONS_VERSION 1 -#define GIT_FETCH_OPTIONS_INIT { \ - GIT_FETCH_OPTIONS_VERSION, \ - GIT_REMOTE_CALLBACKS_INIT, \ - GIT_FETCH_PRUNE_UNSPECIFIED, \ - 1, \ - 0, \ - GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED, \ - GIT_PROXY_OPTIONS_INIT } - -/** - * Initialize git_fetch_options structure - * - * Initializes a `git_fetch_options` with default values. Equivalent to - * creating an instance with `GIT_FETCH_OPTIONS_INIT`. - * - * @param opts The `git_fetch_options` struct to initialize. - * @param version The struct version; pass `GIT_FETCH_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_fetch_options_init( - git_fetch_options *opts, - unsigned int version); - - -/** - * Controls the behavior of a git_push object. - */ -typedef struct { - unsigned int version; - - /** - * If the transport being used to push to the remote requires the creation - * of a pack file, this controls the number of worker threads used by - * the packbuilder when creating that pack file to be sent to the remote. - * - * If set to 0, the packbuilder will auto-detect the number of threads - * to create. The default value is 1. - */ - unsigned int pb_parallelism; - - /** - * Callbacks to use for this push operation - */ - git_remote_callbacks callbacks; - - /** - * Proxy options to use, by default no proxy is used. - */ - git_proxy_options proxy_opts; - - /** - * Whether to allow off-site redirects. If this is not - * specified, the `http.followRedirects` configuration setting - * will be consulted. - */ - git_remote_redirect_t follow_redirects; - - /** - * Extra headers for this push operation - */ - git_strarray custom_headers; - - /** - * "Push options" to deliver to the remote. - */ - git_strarray remote_push_options; -} git_push_options; - -#define GIT_PUSH_OPTIONS_VERSION 1 -#define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 1, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT } - -/** - * Initialize git_push_options structure - * - * Initializes a `git_push_options` with default values. Equivalent to - * creating an instance with `GIT_PUSH_OPTIONS_INIT`. - * - * @param opts The `git_push_options` struct to initialize. - * @param version The struct version; pass `GIT_PUSH_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_push_options_init( - git_push_options *opts, - unsigned int version); - -/** - * Remote creation options structure - * - * Initialize with `GIT_REMOTE_CREATE_OPTIONS_INIT`. Alternatively, you can - * use `git_remote_create_options_init`. - * - */ -typedef struct { - unsigned int version; - - /** Callbacks to use for this connection */ - git_remote_callbacks callbacks; - - /** HTTP Proxy settings */ - git_proxy_options proxy_opts; - - /** - * Whether to allow off-site redirects. If this is not - * specified, the `http.followRedirects` configuration setting - * will be consulted. - */ - git_remote_redirect_t follow_redirects; - - /** Extra HTTP headers to use in this connection */ - git_strarray custom_headers; -} git_remote_connect_options; - -#define GIT_REMOTE_CONNECT_OPTIONS_VERSION 1 -#define GIT_REMOTE_CONNECT_OPTIONS_INIT { \ - GIT_REMOTE_CONNECT_OPTIONS_VERSION, \ - GIT_REMOTE_CALLBACKS_INIT, \ - GIT_PROXY_OPTIONS_INIT } - -/** - * Initialize git_remote_connect_options structure. - * - * Initializes a `git_remote_connect_options` with default values. - * Equivalent to creating an instance with - * `GIT_REMOTE_CONNECT_OPTIONS_INIT`. - * - * @param opts The `git_remote_connect_options` struct to initialize. - * @param version The struct version; pass `GIT_REMOTE_CONNECT_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_remote_connect_options_init( - git_remote_connect_options *opts, - unsigned int version); - -/** - * Open a connection to a remote. - * - * The transport is selected based on the URL; the direction argument - * is due to a limitation of the git protocol which starts up a - * specific binary which can only do the one or the other. - * - * @param remote the remote to connect to - * @param direction GIT_DIRECTION_FETCH if you want to fetch or - * GIT_DIRECTION_PUSH if you want to push - * @param callbacks the callbacks to use for this connection - * @param proxy_opts proxy settings - * @param custom_headers extra HTTP headers to use in this connection - * @return 0 or an error code - */ -GIT_EXTERN(int) git_remote_connect( - git_remote *remote, - git_direction direction, - const git_remote_callbacks *callbacks, - const git_proxy_options *proxy_opts, - const git_strarray *custom_headers); - -/** - * Open a connection to a remote with extended options. - * - * The transport is selected based on the URL; the direction argument - * is due to a limitation of the git protocol which starts up a - * specific binary which can only do the one or the other. - * - * The given options structure will form the defaults for connection - * options and callback setup. Callers may override these defaults - * by specifying `git_fetch_options` or `git_push_options` in - * subsequent calls. - * - * @param remote the remote to connect to - * @param direction GIT_DIRECTION_FETCH if you want to fetch or - * GIT_DIRECTION_PUSH if you want to push - * @param opts the remote connection options - * @return 0 or an error code - */ -GIT_EXTERN(int) git_remote_connect_ext( - git_remote *remote, - git_direction direction, - const git_remote_connect_options *opts); - -/** - * Download and index the packfile. - * - * Connect to the remote if it hasn't been done yet, negotiate with - * the remote git which objects are missing, download and index the - * packfile. - * - * The .idx file will be created and both it and the packfile with be - * renamed to their final name. - * - * If options are specified and this remote is already connected then - * the existing remote connection options will be discarded and the - * remote will now use the new options. - * - * @param remote the remote - * @param refspecs the refspecs to use for this negotiation and - * download. Use NULL or an empty array to use the base refspecs - * @param opts the options to use for this fetch or NULL - * @return 0 or an error code - */ - GIT_EXTERN(int) git_remote_download( - git_remote *remote, - const git_strarray *refspecs, - const git_fetch_options *opts); - -/** - * Create a packfile and send it to the server - * - * Connect to the remote if it hasn't been done yet, negotiate with - * the remote git which objects are missing, create a packfile with - * the missing objects and send it. - * - * If options are specified and this remote is already connected then - * the existing remote connection options will be discarded and the - * remote will now use the new options. - * - * @param remote the remote - * @param refspecs the refspecs to use for this negotiation and - * upload. Use NULL or an empty array to use the base refspecs - * @param opts the options to use for this push - * @return 0 or an error code - */ -GIT_EXTERN(int) git_remote_upload( - git_remote *remote, - const git_strarray *refspecs, - const git_push_options *opts); - -/** - * Update the tips to the new state. - * - * If callbacks are not specified then the callbacks specified to - * `git_remote_connect` will be used (if it was called). - * - * @param remote the remote to update - * @param reflog_message The message to insert into the reflogs. If - * NULL and fetching, the default is "fetch ", where is - * the name of the remote (or its url, for in-memory remotes). This - * parameter is ignored when pushing. - * @param callbacks pointer to the callback structure to use or NULL - * @param update_flags the git_remote_update_flags for these tips. - * @param download_tags what the behaviour for downloading tags is for this fetch. This is - * ignored for push. This must be the same value passed to `git_remote_download()`. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_remote_update_tips( - git_remote *remote, - const git_remote_callbacks *callbacks, - unsigned int update_flags, - git_remote_autotag_option_t download_tags, - const char *reflog_message); - -/** - * Download new data and update tips. - * - * Convenience function to connect to a remote, download the data, - * disconnect and update the remote-tracking branches. - * - * If options are specified and this remote is already connected then - * the existing remote connection options will be discarded and the - * remote will now use the new options. - * - * @param remote the remote to fetch from - * @param refspecs the refspecs to use for this fetch. Pass NULL or an - * empty array to use the base refspecs. - * @param opts options to use for this fetch or NULL - * @param reflog_message The message to insert into the reflogs. If NULL, the - * default is "fetch" - * @return 0 or an error code - */ -GIT_EXTERN(int) git_remote_fetch( - git_remote *remote, - const git_strarray *refspecs, - const git_fetch_options *opts, - const char *reflog_message); - -/** - * Prune tracking refs that are no longer present on remote. - * - * If callbacks are not specified then the callbacks specified to - * `git_remote_connect` will be used (if it was called). - * - * @param remote the remote to prune - * @param callbacks callbacks to use for this prune - * @return 0 or an error code - */ -GIT_EXTERN(int) git_remote_prune( - git_remote *remote, - const git_remote_callbacks *callbacks); - -/** - * Perform a push. - * - * If options are specified and this remote is already connected then - * the existing remote connection options will be discarded and the - * remote will now use the new options. - * - * @param remote the remote to push to - * @param refspecs the refspecs to use for pushing. If NULL or an empty - * array, the configured refspecs will be used - * @param opts options to use for this push - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_remote_push( - git_remote *remote, - const git_strarray *refspecs, - const git_push_options *opts); - -/** - * Get the statistics structure that is filled in by the fetch operation. - */ -GIT_EXTERN(const git_indexer_progress *) git_remote_stats(git_remote *remote); - -/** - * Retrieve the tag auto-follow setting - * - * @param remote the remote to query - * @return the auto-follow setting - */ -GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(const git_remote *remote); - -/** - * Set the remote's tag following setting. - * - * The change will be made in the configuration. No loaded remotes - * will be affected. - * - * @param repo the repository in which to make the change - * @param remote the name of the remote - * @param value the new value to take. - * @return 0, or an error code. - */ -GIT_EXTERN(int) git_remote_set_autotag(git_repository *repo, const char *remote, git_remote_autotag_option_t value); - -/** - * Retrieve the ref-prune setting - * - * @param remote the remote to query - * @return the ref-prune setting - */ -GIT_EXTERN(int) git_remote_prune_refs(const git_remote *remote); - -/** - * Give the remote a new name - * - * All remote-tracking branches and configuration settings - * for the remote are updated. - * - * The new name will be checked for validity. - * See `git_tag_create()` for rules about valid names. - * - * No loaded instances of a the remote with the old name will change - * their name or their list of refspecs. - * - * @param problems non-default refspecs cannot be renamed and will be - * stored here for further processing by the caller. Always free this - * strarray on successful return. - * @param repo the repository in which to rename - * @param name the current name of the remote - * @param new_name the new name the remote should bear - * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code - */ -GIT_EXTERN(int) git_remote_rename( - git_strarray *problems, - git_repository *repo, - const char *name, - const char *new_name); - -/** - * Ensure the remote name is well-formed. - * - * @param valid output pointer to set with validity of given remote name - * @param remote_name name to be checked. - * @return 0 on success or an error code - */ -GIT_EXTERN(int) git_remote_name_is_valid(int *valid, const char *remote_name); - -/** -* Delete an existing persisted remote. -* -* All remote-tracking branches and configuration settings -* for the remote will be removed. -* -* @param repo the repository in which to act -* @param name the name of the remote to delete -* @return 0 on success, or an error code. -*/ -GIT_EXTERN(int) git_remote_delete(git_repository *repo, const char *name); - -/** - * Retrieve the name of the remote's default branch - * - * The default branch of a repository is the branch which HEAD points - * to. If the remote does not support reporting this information - * directly, it performs the guess as git does; that is, if there are - * multiple branches which point to the same commit, the first one is - * chosen. If the master branch is a candidate, it wins. - * - * This function must only be called after connecting. - * - * @param out the buffer in which to store the reference name - * @param remote the remote - * @return 0, GIT_ENOTFOUND if the remote does not have any references - * or none of them point to HEAD's commit, or an error message. - */ -GIT_EXTERN(int) git_remote_default_branch(git_buf *out, git_remote *remote); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_remote_h__ +#define INCLUDE_git_remote_h__ + +#include "common.h" +#include "repository.h" +#include "refspec.h" +#include "net.h" +#include "indexer.h" +#include "strarray.h" +#include "transport.h" +#include "pack.h" +#include "proxy.h" + +/** + * @file git2/remote.h + * @brief Git remote management functions + * @defgroup git_remote remote management functions + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Add a remote with the default fetch refspec to the repository's configuration. + * + * @param out the resulting remote + * @param repo the repository in which to create the remote + * @param name the remote's name + * @param url the remote's url + * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code + */ +GIT_EXTERN(int) git_remote_create( + git_remote **out, + git_repository *repo, + const char *name, + const char *url); + +/** + * Remote redirection settings; whether redirects to another host + * are permitted. By default, git will follow a redirect on the + * initial request (`/info/refs`), but not subsequent requests. + */ +typedef enum { + /** + * Do not follow any off-site redirects at any stage of + * the fetch or push. + */ + GIT_REMOTE_REDIRECT_NONE = (1 << 0), + + /** + * Allow off-site redirects only upon the initial request. + * This is the default. + */ + GIT_REMOTE_REDIRECT_INITIAL = (1 << 1), + + /** + * Allow redirects at any stage in the fetch or push. + */ + GIT_REMOTE_REDIRECT_ALL = (1 << 2) +} git_remote_redirect_t; + +/** + * Remote creation options flags + */ +typedef enum { + /** Ignore the repository apply.insteadOf configuration */ + GIT_REMOTE_CREATE_SKIP_INSTEADOF = (1 << 0), + + /** Don't build a fetchspec from the name if none is set */ + GIT_REMOTE_CREATE_SKIP_DEFAULT_FETCHSPEC = (1 << 1) +} git_remote_create_flags; + +/** + * How to handle reference updates. + */ +typedef enum { + /* Write the fetch results to FETCH_HEAD. */ + GIT_REMOTE_UPDATE_FETCHHEAD = (1 << 0), + + /* Report unchanged tips in the update_tips callback. */ + GIT_REMOTE_UPDATE_REPORT_UNCHANGED = (1 << 1) +} git_remote_update_flags; + +/** + * Remote creation options structure + * + * Initialize with `GIT_REMOTE_CREATE_OPTIONS_INIT`. Alternatively, you can + * use `git_remote_create_options_init`. + * + */ +typedef struct git_remote_create_options { + unsigned int version; + + /** + * The repository that should own the remote. + * Setting this to NULL results in a detached remote. + */ + git_repository *repository; + + /** + * The remote's name. + * Setting this to NULL results in an in-memory/anonymous remote. + */ + const char *name; + + /** The fetchspec the remote should use. */ + const char *fetchspec; + + /** Additional flags for the remote. See git_remote_create_flags. */ + unsigned int flags; +} git_remote_create_options; + +#define GIT_REMOTE_CREATE_OPTIONS_VERSION 1 +#define GIT_REMOTE_CREATE_OPTIONS_INIT {GIT_REMOTE_CREATE_OPTIONS_VERSION} + +/** + * Initialize git_remote_create_options structure + * + * Initializes a `git_remote_create_options` with default values. Equivalent to + * creating an instance with `GIT_REMOTE_CREATE_OPTIONS_INIT`. + * + * @param opts The `git_remote_create_options` struct to initialize. + * @param version The struct version; pass `GIT_REMOTE_CREATE_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_remote_create_options_init( + git_remote_create_options *opts, + unsigned int version); + +/** + * Create a remote, with options. + * + * This function allows more fine-grained control over the remote creation. + * + * Passing NULL as the opts argument will result in a detached remote. + * + * @param out the resulting remote + * @param url the remote's url + * @param opts the remote creation options + * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code + */ +GIT_EXTERN(int) git_remote_create_with_opts( + git_remote **out, + const char *url, + const git_remote_create_options *opts); + +/** + * Add a remote with the provided fetch refspec (or default if NULL) to the repository's + * configuration. + * + * @param out the resulting remote + * @param repo the repository in which to create the remote + * @param name the remote's name + * @param url the remote's url + * @param fetch the remote fetch value + * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code + */ +GIT_EXTERN(int) git_remote_create_with_fetchspec( + git_remote **out, + git_repository *repo, + const char *name, + const char *url, + const char *fetch); + +/** + * Create an anonymous remote + * + * Create a remote with the given url in-memory. You can use this when + * you have a URL instead of a remote's name. + * + * @param out pointer to the new remote objects + * @param repo the associated repository + * @param url the remote repository's URL + * @return 0 or an error code + */ +GIT_EXTERN(int) git_remote_create_anonymous( + git_remote **out, + git_repository *repo, + const char *url); + +/** + * Create a remote without a connected local repo + * + * Create a remote with the given url in-memory. You can use this when + * you have a URL instead of a remote's name. + * + * Contrasted with git_remote_create_anonymous, a detached remote + * will not consider any repo configuration values (such as insteadof url + * substitutions). + * + * @param out pointer to the new remote objects + * @param url the remote repository's URL + * @return 0 or an error code + */ +GIT_EXTERN(int) git_remote_create_detached( + git_remote **out, + const char *url); + +/** + * Get the information for a particular remote + * + * The name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * + * @param out pointer to the new remote object + * @param repo the associated repository + * @param name the remote's name + * @return 0, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code + */ +GIT_EXTERN(int) git_remote_lookup(git_remote **out, git_repository *repo, const char *name); + +/** + * Create a copy of an existing remote. All internal strings are also + * duplicated. Callbacks are not duplicated. + * + * Call `git_remote_free` to free the data. + * + * @param dest pointer where to store the copy + * @param source object to copy + * @return 0 or an error code + */ +GIT_EXTERN(int) git_remote_dup(git_remote **dest, git_remote *source); + +/** + * Get the remote's repository + * + * @param remote the remote + * @return a pointer to the repository + */ +GIT_EXTERN(git_repository *) git_remote_owner(const git_remote *remote); + +/** + * Get the remote's name + * + * @param remote the remote + * @return a pointer to the name or NULL for in-memory remotes + */ +GIT_EXTERN(const char *) git_remote_name(const git_remote *remote); + +/** + * Get the remote's url + * + * If url.*.insteadOf has been configured for this URL, it will + * return the modified URL. If `git_remote_set_instance_pushurl` + * has been called for this remote, then that URL will be returned. + * + * @param remote the remote + * @return a pointer to the url + */ +GIT_EXTERN(const char *) git_remote_url(const git_remote *remote); + +/** + * Get the remote's url for pushing. + * + * If url.*.pushInsteadOf has been configured for this URL, it + * will return the modified URL. If `git_remote_set_instance_pushurl` + * has been called for this remote, then that URL will be returned. + * + * @param remote the remote + * @return a pointer to the url or NULL if no special url for pushing is set + */ +GIT_EXTERN(const char *) git_remote_pushurl(const git_remote *remote); + +/** + * Set the remote's url in the configuration + * + * Remote objects already in memory will not be affected. This assumes + * the common case of a single-url remote and will otherwise return an error. + * + * @param repo the repository in which to perform the change + * @param remote the remote's name + * @param url the url to set + * @return 0 or an error value + */ +GIT_EXTERN(int) git_remote_set_url(git_repository *repo, const char *remote, const char *url); + +/** + * Set the remote's url for pushing in the configuration. + * + * Remote objects already in memory will not be affected. This assumes + * the common case of a single-url remote and will otherwise return an error. + * + * + * @param repo the repository in which to perform the change + * @param remote the remote's name + * @param url the url to set + * @return 0, or an error code + */ +GIT_EXTERN(int) git_remote_set_pushurl(git_repository *repo, const char *remote, const char *url); + +/** + * Set the url for this particular url instance. The URL in the + * configuration will be ignored, and will not be changed. + * + * @param remote the remote's name + * @param url the url to set + * @return 0 or an error value + */ +GIT_EXTERN(int) git_remote_set_instance_url(git_remote *remote, const char *url); + +/** + * Set the push url for this particular url instance. The URL in the + * configuration will be ignored, and will not be changed. + * + * @param remote the remote's name + * @param url the url to set + * @return 0 or an error value + */ +GIT_EXTERN(int) git_remote_set_instance_pushurl(git_remote *remote, const char *url); + +/** + * Add a fetch refspec to the remote's configuration + * + * Add the given refspec to the fetch list in the configuration. No + * loaded remote instances will be affected. + * + * @param repo the repository in which to change the configuration + * @param remote the name of the remote to change + * @param refspec the new fetch refspec + * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value + */ +GIT_EXTERN(int) git_remote_add_fetch(git_repository *repo, const char *remote, const char *refspec); + +/** + * Get the remote's list of fetch refspecs + * + * The memory is owned by the user and should be freed with + * `git_strarray_free`. + * + * @param array pointer to the array in which to store the strings + * @param remote the remote to query + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_remote_get_fetch_refspecs(git_strarray *array, const git_remote *remote); + +/** + * Add a push refspec to the remote's configuration + * + * Add the given refspec to the push list in the configuration. No + * loaded remote instances will be affected. + * + * @param repo the repository in which to change the configuration + * @param remote the name of the remote to change + * @param refspec the new push refspec + * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value + */ +GIT_EXTERN(int) git_remote_add_push(git_repository *repo, const char *remote, const char *refspec); + +/** + * Get the remote's list of push refspecs + * + * The memory is owned by the user and should be freed with + * `git_strarray_free`. + * + * @param array pointer to the array in which to store the strings + * @param remote the remote to query + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_remote_get_push_refspecs(git_strarray *array, const git_remote *remote); + +/** + * Get the number of refspecs for a remote + * + * @param remote the remote + * @return the amount of refspecs configured in this remote + */ +GIT_EXTERN(size_t) git_remote_refspec_count(const git_remote *remote); + +/** + * Get a refspec from the remote + * + * @param remote the remote to query + * @param n the refspec to get + * @return the nth refspec + */ +GIT_EXTERN(const git_refspec *)git_remote_get_refspec(const git_remote *remote, size_t n); + +/** + * Get the remote repository's reference advertisement list + * + * Get the list of references with which the server responds to a new + * connection. + * + * The remote (or more exactly its transport) must have connected to + * the remote repository. This list is available as soon as the + * connection to the remote is initiated and it remains available + * after disconnecting. + * + * The memory belongs to the remote. The pointer will be valid as long + * as a new connection is not initiated, but it is recommended that + * you make a copy in order to make use of the data. + * + * @param out pointer to the array + * @param size the number of remote heads + * @param remote the remote + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_remote_ls(const git_remote_head ***out, size_t *size, git_remote *remote); + +/** + * Check whether the remote is connected + * + * Check whether the remote's underlying transport is connected to the + * remote host. + * + * @param remote the remote + * @return 1 if it's connected, 0 otherwise. + */ +GIT_EXTERN(int) git_remote_connected(const git_remote *remote); + +/** + * Cancel the operation + * + * At certain points in its operation, the network code checks whether + * the operation has been cancelled and if so stops the operation. + * + * @param remote the remote + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_remote_stop(git_remote *remote); + +/** + * Disconnect from the remote + * + * Close the connection to the remote. + * + * @param remote the remote to disconnect from + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_remote_disconnect(git_remote *remote); + +/** + * Free the memory associated with a remote + * + * This also disconnects from the remote, if the connection + * has not been closed yet (using git_remote_disconnect). + * + * @param remote the remote to free + */ +GIT_EXTERN(void) git_remote_free(git_remote *remote); + +/** + * Get a list of the configured remotes for a repo + * + * The string array must be freed by the user. + * + * @param out a string array which receives the names of the remotes + * @param repo the repository to query + * @return 0 or an error code + */ +GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo); + +/** + * Argument to the completion callback which tells it which operation + * finished. + */ +typedef enum git_remote_completion_t { + GIT_REMOTE_COMPLETION_DOWNLOAD, + GIT_REMOTE_COMPLETION_INDEXING, + GIT_REMOTE_COMPLETION_ERROR +} git_remote_completion_t; + +/** Push network progress notification function */ +typedef int GIT_CALLBACK(git_push_transfer_progress_cb)( + unsigned int current, + unsigned int total, + size_t bytes, + void *payload); + +/** + * Represents an update which will be performed on the remote during push + */ +typedef struct { + /** + * The source name of the reference + */ + char *src_refname; + /** + * The name of the reference to update on the server + */ + char *dst_refname; + /** + * The current target of the reference + */ + git_oid src; + /** + * The new target for the reference + */ + git_oid dst; +} git_push_update; + +/** + * Callback used to inform of upcoming updates. + * + * @param updates an array containing the updates which will be sent + * as commands to the destination. + * @param len number of elements in `updates` + * @param payload Payload provided by the caller + */ +typedef int GIT_CALLBACK(git_push_negotiation)(const git_push_update **updates, size_t len, void *payload); + +/** + * Callback used to inform of the update status from the remote. + * + * Called for each updated reference on push. If `status` is + * not `NULL`, the update was rejected by the remote server + * and `status` contains the reason given. + * + * @param refname refname specifying to the remote ref + * @param status status message sent from the remote + * @param data data provided by the caller + * @return 0 on success, otherwise an error + */ +typedef int GIT_CALLBACK(git_push_update_reference_cb)(const char *refname, const char *status, void *data); + +#ifndef GIT_DEPRECATE_HARD +/** + * Callback to resolve URLs before connecting to remote + * + * If you return GIT_PASSTHROUGH, you don't need to write anything to + * url_resolved. + * + * @param url_resolved The buffer to write the resolved URL to + * @param url The URL to resolve + * @param direction GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH + * @param payload Payload provided by the caller + * @return 0 on success, GIT_PASSTHROUGH or an error + * @deprecated Use `git_remote_set_instance_url` + */ +typedef int GIT_CALLBACK(git_url_resolve_cb)(git_buf *url_resolved, const char *url, int direction, void *payload); +#endif + +/** + * Callback invoked immediately before we attempt to connect to the + * given url. Callers may change the URL before the connection by + * calling `git_remote_set_instance_url` in the callback. + * + * @param remote The remote to be connected + * @param direction GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH + * @param payload Payload provided by the caller + * @return 0 on success, or an error + */ +typedef int GIT_CALLBACK(git_remote_ready_cb)(git_remote *remote, int direction, void *payload); + +/** + * The callback settings structure + * + * Set the callbacks to be called by the remote when informing the user + * about the progress of the network operations. + */ +struct git_remote_callbacks { + unsigned int version; /**< The version */ + + /** + * Textual progress from the remote. Text send over the + * progress side-band will be passed to this function (this is + * the 'counting objects' output). + */ + git_transport_message_cb sideband_progress; + + /** + * Completion is called when different parts of the download + * process are done (currently unused). + */ + int GIT_CALLBACK(completion)(git_remote_completion_t type, void *data); + + /** + * This will be called if the remote host requires + * authentication in order to connect to it. + * + * Returning GIT_PASSTHROUGH will make libgit2 behave as + * though this field isn't set. + */ + git_credential_acquire_cb credentials; + + /** + * If cert verification fails, this will be called to let the + * user make the final decision of whether to allow the + * connection to proceed. Returns 0 to allow the connection + * or a negative value to indicate an error. + */ + git_transport_certificate_check_cb certificate_check; + + /** + * During the download of new data, this will be regularly + * called with the current count of progress done by the + * indexer. + */ + git_indexer_progress_cb transfer_progress; + + /** + * Each time a reference is updated locally, this function + * will be called with information about it. + */ + int GIT_CALLBACK(update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data); + + /** + * Function to call with progress information during pack + * building. Be aware that this is called inline with pack + * building operations, so performance may be affected. + */ + git_packbuilder_progress pack_progress; + + /** + * Function to call with progress information during the + * upload portion of a push. Be aware that this is called + * inline with pack building operations, so performance may be + * affected. + */ + git_push_transfer_progress_cb push_transfer_progress; + + /** + * See documentation of git_push_update_reference_cb + */ + git_push_update_reference_cb push_update_reference; + + /** + * Called once between the negotiation step and the upload. It + * provides information about what updates will be performed. + */ + git_push_negotiation push_negotiation; + + /** + * Create the transport to use for this operation. Leave NULL + * to auto-detect. + */ + git_transport_cb transport; + + /** + * Callback when the remote is ready to connect. + */ + git_remote_ready_cb remote_ready; + + /** + * This will be passed to each of the callbacks in this struct + * as the last parameter. + */ + void *payload; + +#ifdef GIT_DEPRECATE_HARD + void *reserved; +#else + /** + * Resolve URL before connecting to remote. + * The returned URL will be used to connect to the remote instead. + * + * This callback is deprecated; users should use + * git_remote_ready_cb and configure the instance URL instead. + */ + git_url_resolve_cb resolve_url; +#endif +}; + +#define GIT_REMOTE_CALLBACKS_VERSION 1 +#define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION} + +/** + * Initializes a `git_remote_callbacks` with default values. Equivalent to + * creating an instance with GIT_REMOTE_CALLBACKS_INIT. + * + * @param opts the `git_remote_callbacks` struct to initialize + * @param version Version of struct; pass `GIT_REMOTE_CALLBACKS_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_remote_init_callbacks( + git_remote_callbacks *opts, + unsigned int version); + +/** Acceptable prune settings when fetching */ +typedef enum { + /** + * Use the setting from the configuration + */ + GIT_FETCH_PRUNE_UNSPECIFIED, + /** + * Force pruning on + */ + GIT_FETCH_PRUNE, + /** + * Force pruning off + */ + GIT_FETCH_NO_PRUNE +} git_fetch_prune_t; + +/** + * Automatic tag following option + * + * Lets us select the --tags option to use. + */ +typedef enum { + /** + * Use the setting from the configuration. + */ + GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED = 0, + /** + * Ask the server for tags pointing to objects we're already + * downloading. + */ + GIT_REMOTE_DOWNLOAD_TAGS_AUTO, + /** + * Don't ask for any tags beyond the refspecs. + */ + GIT_REMOTE_DOWNLOAD_TAGS_NONE, + /** + * Ask for the all the tags. + */ + GIT_REMOTE_DOWNLOAD_TAGS_ALL +} git_remote_autotag_option_t; + +/** Constants for fetch depth (shallowness of fetch). */ +typedef enum { + /** The fetch is "full" (not shallow). This is the default. */ + GIT_FETCH_DEPTH_FULL = 0, + + /** The fetch should "unshallow" and fetch missing data. */ + GIT_FETCH_DEPTH_UNSHALLOW = 2147483647 +} git_fetch_depth_t; + +/** + * Fetch options structure. + * + * Zero out for defaults. Initialize with `GIT_FETCH_OPTIONS_INIT` macro to + * correctly set the `version` field. E.g. + * + * git_fetch_options opts = GIT_FETCH_OPTIONS_INIT; + */ +typedef struct { + int version; + + /** + * Callbacks to use for this fetch operation + */ + git_remote_callbacks callbacks; + + /** + * Whether to perform a prune after the fetch + */ + git_fetch_prune_t prune; + + /** + * How to handle reference updates; see `git_remote_update_flags`. + */ + unsigned int update_fetchhead : 1, + report_unchanged : 1; + + /** + * Determines how to behave regarding tags on the remote, such + * as auto-downloading tags for objects we're downloading or + * downloading all of them. + * + * The default is to auto-follow tags. + */ + git_remote_autotag_option_t download_tags; + + /** + * Proxy options to use, by default no proxy is used. + */ + git_proxy_options proxy_opts; + + /** + * Depth of the fetch to perform, or `GIT_FETCH_DEPTH_FULL` + * (or `0`) for full history, or `GIT_FETCH_DEPTH_UNSHALLOW` + * to "unshallow" a shallow repository. + * + * The default is full (`GIT_FETCH_DEPTH_FULL` or `0`). + */ + int depth; + + /** + * Whether to allow off-site redirects. If this is not + * specified, the `http.followRedirects` configuration setting + * will be consulted. + */ + git_remote_redirect_t follow_redirects; + + /** + * Extra headers for this fetch operation + */ + git_strarray custom_headers; +} git_fetch_options; + +#define GIT_FETCH_OPTIONS_VERSION 1 +#define GIT_FETCH_OPTIONS_INIT { \ + GIT_FETCH_OPTIONS_VERSION, \ + GIT_REMOTE_CALLBACKS_INIT, \ + GIT_FETCH_PRUNE_UNSPECIFIED, \ + 1, \ + 0, \ + GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED, \ + GIT_PROXY_OPTIONS_INIT } + +/** + * Initialize git_fetch_options structure + * + * Initializes a `git_fetch_options` with default values. Equivalent to + * creating an instance with `GIT_FETCH_OPTIONS_INIT`. + * + * @param opts The `git_fetch_options` struct to initialize. + * @param version The struct version; pass `GIT_FETCH_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_fetch_options_init( + git_fetch_options *opts, + unsigned int version); + + +/** + * Controls the behavior of a git_push object. + */ +typedef struct { + unsigned int version; + + /** + * If the transport being used to push to the remote requires the creation + * of a pack file, this controls the number of worker threads used by + * the packbuilder when creating that pack file to be sent to the remote. + * + * If set to 0, the packbuilder will auto-detect the number of threads + * to create. The default value is 1. + */ + unsigned int pb_parallelism; + + /** + * Callbacks to use for this push operation + */ + git_remote_callbacks callbacks; + + /** + * Proxy options to use, by default no proxy is used. + */ + git_proxy_options proxy_opts; + + /** + * Whether to allow off-site redirects. If this is not + * specified, the `http.followRedirects` configuration setting + * will be consulted. + */ + git_remote_redirect_t follow_redirects; + + /** + * Extra headers for this push operation + */ + git_strarray custom_headers; + + /** + * "Push options" to deliver to the remote. + */ + git_strarray remote_push_options; +} git_push_options; + +#define GIT_PUSH_OPTIONS_VERSION 1 +#define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 1, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT } + +/** + * Initialize git_push_options structure + * + * Initializes a `git_push_options` with default values. Equivalent to + * creating an instance with `GIT_PUSH_OPTIONS_INIT`. + * + * @param opts The `git_push_options` struct to initialize. + * @param version The struct version; pass `GIT_PUSH_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_push_options_init( + git_push_options *opts, + unsigned int version); + +/** + * Remote creation options structure + * + * Initialize with `GIT_REMOTE_CREATE_OPTIONS_INIT`. Alternatively, you can + * use `git_remote_create_options_init`. + * + */ +typedef struct { + unsigned int version; + + /** Callbacks to use for this connection */ + git_remote_callbacks callbacks; + + /** HTTP Proxy settings */ + git_proxy_options proxy_opts; + + /** + * Whether to allow off-site redirects. If this is not + * specified, the `http.followRedirects` configuration setting + * will be consulted. + */ + git_remote_redirect_t follow_redirects; + + /** Extra HTTP headers to use in this connection */ + git_strarray custom_headers; +} git_remote_connect_options; + +#define GIT_REMOTE_CONNECT_OPTIONS_VERSION 1 +#define GIT_REMOTE_CONNECT_OPTIONS_INIT { \ + GIT_REMOTE_CONNECT_OPTIONS_VERSION, \ + GIT_REMOTE_CALLBACKS_INIT, \ + GIT_PROXY_OPTIONS_INIT } + +/** + * Initialize git_remote_connect_options structure. + * + * Initializes a `git_remote_connect_options` with default values. + * Equivalent to creating an instance with + * `GIT_REMOTE_CONNECT_OPTIONS_INIT`. + * + * @param opts The `git_remote_connect_options` struct to initialize. + * @param version The struct version; pass `GIT_REMOTE_CONNECT_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_remote_connect_options_init( + git_remote_connect_options *opts, + unsigned int version); + +/** + * Open a connection to a remote. + * + * The transport is selected based on the URL; the direction argument + * is due to a limitation of the git protocol which starts up a + * specific binary which can only do the one or the other. + * + * @param remote the remote to connect to + * @param direction GIT_DIRECTION_FETCH if you want to fetch or + * GIT_DIRECTION_PUSH if you want to push + * @param callbacks the callbacks to use for this connection + * @param proxy_opts proxy settings + * @param custom_headers extra HTTP headers to use in this connection + * @return 0 or an error code + */ +GIT_EXTERN(int) git_remote_connect( + git_remote *remote, + git_direction direction, + const git_remote_callbacks *callbacks, + const git_proxy_options *proxy_opts, + const git_strarray *custom_headers); + +/** + * Open a connection to a remote with extended options. + * + * The transport is selected based on the URL; the direction argument + * is due to a limitation of the git protocol which starts up a + * specific binary which can only do the one or the other. + * + * The given options structure will form the defaults for connection + * options and callback setup. Callers may override these defaults + * by specifying `git_fetch_options` or `git_push_options` in + * subsequent calls. + * + * @param remote the remote to connect to + * @param direction GIT_DIRECTION_FETCH if you want to fetch or + * GIT_DIRECTION_PUSH if you want to push + * @param opts the remote connection options + * @return 0 or an error code + */ +GIT_EXTERN(int) git_remote_connect_ext( + git_remote *remote, + git_direction direction, + const git_remote_connect_options *opts); + +/** + * Download and index the packfile. + * + * Connect to the remote if it hasn't been done yet, negotiate with + * the remote git which objects are missing, download and index the + * packfile. + * + * The .idx file will be created and both it and the packfile with be + * renamed to their final name. + * + * If options are specified and this remote is already connected then + * the existing remote connection options will be discarded and the + * remote will now use the new options. + * + * @param remote the remote + * @param refspecs the refspecs to use for this negotiation and + * download. Use NULL or an empty array to use the base refspecs + * @param opts the options to use for this fetch or NULL + * @return 0 or an error code + */ + GIT_EXTERN(int) git_remote_download( + git_remote *remote, + const git_strarray *refspecs, + const git_fetch_options *opts); + +/** + * Create a packfile and send it to the server + * + * Connect to the remote if it hasn't been done yet, negotiate with + * the remote git which objects are missing, create a packfile with + * the missing objects and send it. + * + * If options are specified and this remote is already connected then + * the existing remote connection options will be discarded and the + * remote will now use the new options. + * + * @param remote the remote + * @param refspecs the refspecs to use for this negotiation and + * upload. Use NULL or an empty array to use the base refspecs + * @param opts the options to use for this push + * @return 0 or an error code + */ +GIT_EXTERN(int) git_remote_upload( + git_remote *remote, + const git_strarray *refspecs, + const git_push_options *opts); + +/** + * Update the tips to the new state. + * + * If callbacks are not specified then the callbacks specified to + * `git_remote_connect` will be used (if it was called). + * + * @param remote the remote to update + * @param reflog_message The message to insert into the reflogs. If + * NULL and fetching, the default is "fetch ", where is + * the name of the remote (or its url, for in-memory remotes). This + * parameter is ignored when pushing. + * @param callbacks pointer to the callback structure to use or NULL + * @param update_flags the git_remote_update_flags for these tips. + * @param download_tags what the behaviour for downloading tags is for this fetch. This is + * ignored for push. This must be the same value passed to `git_remote_download()`. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_remote_update_tips( + git_remote *remote, + const git_remote_callbacks *callbacks, + unsigned int update_flags, + git_remote_autotag_option_t download_tags, + const char *reflog_message); + +/** + * Download new data and update tips. + * + * Convenience function to connect to a remote, download the data, + * disconnect and update the remote-tracking branches. + * + * If options are specified and this remote is already connected then + * the existing remote connection options will be discarded and the + * remote will now use the new options. + * + * @param remote the remote to fetch from + * @param refspecs the refspecs to use for this fetch. Pass NULL or an + * empty array to use the base refspecs. + * @param opts options to use for this fetch or NULL + * @param reflog_message The message to insert into the reflogs. If NULL, the + * default is "fetch" + * @return 0 or an error code + */ +GIT_EXTERN(int) git_remote_fetch( + git_remote *remote, + const git_strarray *refspecs, + const git_fetch_options *opts, + const char *reflog_message); + +/** + * Prune tracking refs that are no longer present on remote. + * + * If callbacks are not specified then the callbacks specified to + * `git_remote_connect` will be used (if it was called). + * + * @param remote the remote to prune + * @param callbacks callbacks to use for this prune + * @return 0 or an error code + */ +GIT_EXTERN(int) git_remote_prune( + git_remote *remote, + const git_remote_callbacks *callbacks); + +/** + * Perform a push. + * + * If options are specified and this remote is already connected then + * the existing remote connection options will be discarded and the + * remote will now use the new options. + * + * @param remote the remote to push to + * @param refspecs the refspecs to use for pushing. If NULL or an empty + * array, the configured refspecs will be used + * @param opts options to use for this push + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_remote_push( + git_remote *remote, + const git_strarray *refspecs, + const git_push_options *opts); + +/** + * Get the statistics structure that is filled in by the fetch operation. + */ +GIT_EXTERN(const git_indexer_progress *) git_remote_stats(git_remote *remote); + +/** + * Retrieve the tag auto-follow setting + * + * @param remote the remote to query + * @return the auto-follow setting + */ +GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(const git_remote *remote); + +/** + * Set the remote's tag following setting. + * + * The change will be made in the configuration. No loaded remotes + * will be affected. + * + * @param repo the repository in which to make the change + * @param remote the name of the remote + * @param value the new value to take. + * @return 0, or an error code. + */ +GIT_EXTERN(int) git_remote_set_autotag(git_repository *repo, const char *remote, git_remote_autotag_option_t value); + +/** + * Retrieve the ref-prune setting + * + * @param remote the remote to query + * @return the ref-prune setting + */ +GIT_EXTERN(int) git_remote_prune_refs(const git_remote *remote); + +/** + * Give the remote a new name + * + * All remote-tracking branches and configuration settings + * for the remote are updated. + * + * The new name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * + * No loaded instances of a the remote with the old name will change + * their name or their list of refspecs. + * + * @param problems non-default refspecs cannot be renamed and will be + * stored here for further processing by the caller. Always free this + * strarray on successful return. + * @param repo the repository in which to rename + * @param name the current name of the remote + * @param new_name the new name the remote should bear + * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code + */ +GIT_EXTERN(int) git_remote_rename( + git_strarray *problems, + git_repository *repo, + const char *name, + const char *new_name); + +/** + * Ensure the remote name is well-formed. + * + * @param valid output pointer to set with validity of given remote name + * @param remote_name name to be checked. + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_remote_name_is_valid(int *valid, const char *remote_name); + +/** +* Delete an existing persisted remote. +* +* All remote-tracking branches and configuration settings +* for the remote will be removed. +* +* @param repo the repository in which to act +* @param name the name of the remote to delete +* @return 0 on success, or an error code. +*/ +GIT_EXTERN(int) git_remote_delete(git_repository *repo, const char *name); + +/** + * Retrieve the name of the remote's default branch + * + * The default branch of a repository is the branch which HEAD points + * to. If the remote does not support reporting this information + * directly, it performs the guess as git does; that is, if there are + * multiple branches which point to the same commit, the first one is + * chosen. If the master branch is a candidate, it wins. + * + * This function must only be called after connecting. + * + * @param out the buffer in which to store the reference name + * @param remote the remote + * @return 0, GIT_ENOTFOUND if the remote does not have any references + * or none of them point to HEAD's commit, or an error message. + */ +GIT_EXTERN(int) git_remote_default_branch(git_buf *out, git_remote *remote); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/repository.h b/3rdparty/libgit2/include/git2/repository.h index 0afda72..bcacd2e 100644 --- a/3rdparty/libgit2/include/git2/repository.h +++ b/3rdparty/libgit2/include/git2/repository.h @@ -1,996 +1,996 @@ -/* - * 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_repository_h__ -#define INCLUDE_git_repository_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "buffer.h" -#include "commit.h" - -/** - * @file git2/repository.h - * @brief Git repository management routines - * @defgroup git_repository Git repository management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Open a git repository. - * - * The 'path' argument must point to either a git repository - * folder, or an existing work dir. - * - * The method will automatically detect if 'path' is a normal - * or bare repository or fail is 'path' is neither. - * - * @param out pointer to the repo which will be opened - * @param path the path to the repository - * @return 0 or an error code - */ -GIT_EXTERN(int) git_repository_open(git_repository **out, const char *path); -/** - * Open working tree as a repository - * - * Open the working directory of the working tree as a normal - * repository that can then be worked on. - * - * @param out Output pointer containing opened repository - * @param wt Working tree to open - * @return 0 or an error code - */ -GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_worktree *wt); - -/** - * Create a "fake" repository to wrap an object database - * - * Create a repository object to wrap an object database to be used - * with the API when all you have is an object database. This doesn't - * have any paths associated with it, so use with care. - * - * @param out pointer to the repo - * @param odb the object database to wrap - * @param oid_type the oid type of the object database - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_repository_wrap_odb( - git_repository **out, - git_odb *odb, - git_oid_t oid_type); -#else -GIT_EXTERN(int) git_repository_wrap_odb( - git_repository **out, - git_odb *odb); -#endif - -/** - * Look for a git repository and copy its path in the given buffer. - * The lookup start from base_path and walk across parent directories - * if nothing has been found. The lookup ends when the first repository - * is found, or when reaching a directory referenced in ceiling_dirs - * or when the filesystem changes (in case across_fs is true). - * - * The method will automatically detect if the repository is bare - * (if there is a repository). - * - * @param out A pointer to a user-allocated git_buf which will contain - * the found path. - * - * @param start_path The base path where the lookup starts. - * - * @param across_fs If true, then the lookup will not stop when a - * filesystem device change is detected while exploring parent directories. - * - * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR separated list of - * absolute symbolic link free paths. The lookup will stop when any - * of this paths is reached. Note that the lookup always performs on - * start_path no matter start_path appears in ceiling_dirs ceiling_dirs - * might be NULL (which is equivalent to an empty string) - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_repository_discover( - git_buf *out, - const char *start_path, - int across_fs, - const char *ceiling_dirs); - -/** - * Option flags for `git_repository_open_ext`. - */ -typedef enum { - /** - * Only open the repository if it can be immediately found in the - * start_path. Do not walk up from the start_path looking at parent - * directories. - */ - GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0), - - /** - * Unless this flag is set, open will not continue searching across - * filesystem boundaries (i.e. when `st_dev` changes from the `stat` - * system call). For example, searching in a user's home directory at - * "/home/user/source/" will not return "/.git/" as the found repo if - * "/" is a different filesystem than "/home". - */ - GIT_REPOSITORY_OPEN_CROSS_FS = (1 << 1), - - /** - * Open repository as a bare repo regardless of core.bare config, and - * defer loading config file for faster setup. - * Unlike `git_repository_open_bare`, this can follow gitlinks. - */ - GIT_REPOSITORY_OPEN_BARE = (1 << 2), - - /** - * Do not check for a repository by appending /.git to the start_path; - * only open the repository if start_path itself points to the git - * directory. - */ - GIT_REPOSITORY_OPEN_NO_DOTGIT = (1 << 3), - - /** - * Find and open a git repository, respecting the environment variables - * used by the git command-line tools. - * If set, `git_repository_open_ext` will ignore the other flags and - * the `ceiling_dirs` argument, and will allow a NULL `path` to use - * `GIT_DIR` or search from the current directory. - * The search for a repository will respect $GIT_CEILING_DIRECTORIES and - * $GIT_DISCOVERY_ACROSS_FILESYSTEM. The opened repository will - * respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and - * $GIT_ALTERNATE_OBJECT_DIRECTORIES. - * In the future, this flag will also cause `git_repository_open_ext` - * to respect $GIT_WORK_TREE and $GIT_COMMON_DIR; currently, - * `git_repository_open_ext` with this flag will error out if either - * $GIT_WORK_TREE or $GIT_COMMON_DIR is set. - */ - GIT_REPOSITORY_OPEN_FROM_ENV = (1 << 4) -} git_repository_open_flag_t; - -/** - * Find and open a repository with extended controls. - * - * @param out Pointer to the repo which will be opened. This can - * actually be NULL if you only want to use the error code to - * see if a repo at this path could be opened. - * @param path Path to open as git repository. If the flags - * permit "searching", then this can be a path to a subdirectory - * inside the working directory of the repository. May be NULL if - * flags is GIT_REPOSITORY_OPEN_FROM_ENV. - * @param flags A combination of the GIT_REPOSITORY_OPEN flags above. - * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR delimited list of path - * prefixes at which the search for a containing repository should - * terminate. - * @return 0 on success, GIT_ENOTFOUND if no repository could be found, - * or -1 if there was a repository but open failed for some reason - * (such as repo corruption or system errors). - */ -GIT_EXTERN(int) git_repository_open_ext( - git_repository **out, - const char *path, - unsigned int flags, - const char *ceiling_dirs); - -/** - * Open a bare repository on the serverside. - * - * This is a fast open for bare repositories that will come in handy - * if you're e.g. hosting git repositories and need to access them - * efficiently - * - * @param out Pointer to the repo which will be opened. - * @param bare_path Direct path to the bare repository - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_repository_open_bare(git_repository **out, const char *bare_path); - -/** - * Free a previously allocated repository - * - * Note that after a repository is free'd, all the objects it has spawned - * will still exist until they are manually closed by the user - * with `git_object_free`, but accessing any of the attributes of - * an object without a backing repository will result in undefined - * behavior - * - * @param repo repository handle to close. If NULL nothing occurs. - */ -GIT_EXTERN(void) git_repository_free(git_repository *repo); - -/** - * Creates a new Git repository in the given folder. - * - * TODO: - * - Reinit the repository - * - * @param out pointer to the repo which will be created or reinitialized - * @param path the path to the repository - * @param is_bare if true, a Git repository without a working directory is - * created at the pointed path. If false, provided path will be - * considered as the working directory into which the .git directory - * will be created. - * - * @return 0 or an error code - */ -GIT_EXTERN(int) git_repository_init( - git_repository **out, - const char *path, - unsigned is_bare); - -/** - * Option flags for `git_repository_init_ext`. - * - * These flags configure extra behaviors to `git_repository_init_ext`. - * In every case, the default behavior is the zero value (i.e. flag is - * not set). Just OR the flag values together for the `flags` parameter - * when initializing a new repo. - */ -typedef enum { - /** - * Create a bare repository with no working directory. - */ - GIT_REPOSITORY_INIT_BARE = (1u << 0), - - /** - * Return an GIT_EEXISTS error if the repo_path appears to already be - * an git repository. - */ - GIT_REPOSITORY_INIT_NO_REINIT = (1u << 1), - - /** - * Normally a "/.git/" will be appended to the repo path for - * non-bare repos (if it is not already there), but passing this flag - * prevents that behavior. - */ - GIT_REPOSITORY_INIT_NO_DOTGIT_DIR = (1u << 2), - - /** - * Make the repo_path (and workdir_path) as needed. Init is always willing - * to create the ".git" directory even without this flag. This flag tells - * init to create the trailing component of the repo and workdir paths - * as needed. - */ - GIT_REPOSITORY_INIT_MKDIR = (1u << 3), - - /** - * Recursively make all components of the repo and workdir paths as - * necessary. - */ - GIT_REPOSITORY_INIT_MKPATH = (1u << 4), - - /** - * libgit2 normally uses internal templates to initialize a new repo. - * This flags enables external templates, looking the "template_path" from - * the options if set, or the `init.templatedir` global config if not, - * or falling back on "/usr/share/git-core/templates" if it exists. - */ - GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE = (1u << 5), - - /** - * If an alternate workdir is specified, use relative paths for the gitdir - * and core.worktree. - */ - GIT_REPOSITORY_INIT_RELATIVE_GITLINK = (1u << 6) -} git_repository_init_flag_t; - -/** - * Mode options for `git_repository_init_ext`. - * - * Set the mode field of the `git_repository_init_options` structure - * either to the custom mode that you would like, or to one of the - * defined modes. - */ -typedef enum { - /** - * Use permissions configured by umask - the default. - */ - GIT_REPOSITORY_INIT_SHARED_UMASK = 0, - - /** - * Use "--shared=group" behavior, chmod'ing the new repo to be group - * writable and "g+sx" for sticky group assignment. - */ - GIT_REPOSITORY_INIT_SHARED_GROUP = 0002775, - - /** - * Use "--shared=all" behavior, adding world readability. - */ - GIT_REPOSITORY_INIT_SHARED_ALL = 0002777 -} git_repository_init_mode_t; - -/** - * Extended options structure for `git_repository_init_ext`. - * - * This contains extra options for `git_repository_init_ext` that enable - * additional initialization features. - */ -typedef struct { - unsigned int version; - - /** - * Combination of GIT_REPOSITORY_INIT flags above. - */ - uint32_t flags; - - /** - * Set to one of the standard GIT_REPOSITORY_INIT_SHARED_... constants - * above, or to a custom value that you would like. - */ - uint32_t mode; - - /** - * The path to the working dir or NULL for default (i.e. repo_path parent - * on non-bare repos). IF THIS IS RELATIVE PATH, IT WILL BE EVALUATED - * RELATIVE TO THE REPO_PATH. If this is not the "natural" working - * directory, a .git gitlink file will be created here linking to the - * repo_path. - */ - const char *workdir_path; - - /** - * If set, this will be used to initialize the "description" file in the - * repository, instead of using the template content. - */ - const char *description; - - /** - * When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set, this contains - * the path to use for the template directory. If this is NULL, the config - * or default directory options will be used instead. - */ - const char *template_path; - - /** - * The name of the head to point HEAD at. If NULL, then this will be - * treated as "master" and the HEAD ref will be set to "refs/heads/master". - * If this begins with "refs/" it will be used verbatim; - * otherwise "refs/heads/" will be prefixed. - */ - const char *initial_head; - - /** - * If this is non-NULL, then after the rest of the repository - * initialization is completed, an "origin" remote will be added - * pointing to this URL. - */ - const char *origin_url; - -#ifdef GIT_EXPERIMENTAL_SHA256 - /** - * - * Type of object IDs to use for this repository, or 0 for - * default (currently SHA1). - */ - git_oid_t oid_type; -#endif -} git_repository_init_options; - -#define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1 -#define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION} - -/** - * Initialize git_repository_init_options structure - * - * Initializes a `git_repository_init_options` with default values. Equivalent to - * creating an instance with `GIT_REPOSITORY_INIT_OPTIONS_INIT`. - * - * @param opts The `git_repository_init_options` struct to initialize. - * @param version The struct version; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_repository_init_options_init( - git_repository_init_options *opts, - unsigned int version); - -/** - * Create a new Git repository in the given folder with extended controls. - * - * This will initialize a new git repository (creating the repo_path - * if requested by flags) and working directory as needed. It will - * auto-detect the case sensitivity of the file system and if the - * file system supports file mode bits correctly. - * - * @param out Pointer to the repo which will be created or reinitialized. - * @param repo_path The path to the repository. - * @param opts Pointer to git_repository_init_options struct. - * @return 0 or an error code on failure. - */ -GIT_EXTERN(int) git_repository_init_ext( - git_repository **out, - const char *repo_path, - git_repository_init_options *opts); - -/** - * Retrieve and resolve the reference pointed at by HEAD. - * - * The returned `git_reference` will be owned by caller and - * `git_reference_free()` must be called when done with it to release the - * allocated memory and prevent a leak. - * - * @param out pointer to the reference which will be retrieved - * @param repo a repository object - * - * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing - * branch, GIT_ENOTFOUND when HEAD is missing; an error code otherwise - */ -GIT_EXTERN(int) git_repository_head(git_reference **out, git_repository *repo); - -/** - * Retrieve the referenced HEAD for the worktree - * - * @param out pointer to the reference which will be retrieved - * @param repo a repository object - * @param name name of the worktree to retrieve HEAD for - * @return 0 when successful, error-code otherwise - */ -GIT_EXTERN(int) git_repository_head_for_worktree(git_reference **out, git_repository *repo, - const char *name); - -/** - * Check if a repository's HEAD is detached - * - * A repository's HEAD is detached when it points directly to a commit - * instead of a branch. - * - * @param repo Repo to test - * @return 1 if HEAD is detached, 0 if it's not; error code if there - * was an error. - */ -GIT_EXTERN(int) git_repository_head_detached(git_repository *repo); - -/** - * Check if a worktree's HEAD is detached - * - * A worktree's HEAD is detached when it points directly to a - * commit instead of a branch. - * - * @param repo a repository object - * @param name name of the worktree to retrieve HEAD for - * @return 1 if HEAD is detached, 0 if its not; error code if - * there was an error - */ -GIT_EXTERN(int) git_repository_head_detached_for_worktree(git_repository *repo, - const char *name); - -/** - * Check if the current branch is unborn - * - * An unborn branch is one named from HEAD but which doesn't exist in - * the refs namespace, because it doesn't have any commit to point to. - * - * @param repo Repo to test - * @return 1 if the current branch is unborn, 0 if it's not; error - * code if there was an error - */ -GIT_EXTERN(int) git_repository_head_unborn(git_repository *repo); - -/** - * Check if a repository is empty - * - * An empty repository has just been initialized and contains no references - * apart from HEAD, which must be pointing to the unborn master branch, - * or the branch specified for the repository in the `init.defaultBranch` - * configuration variable. - * - * @param repo Repo to test - * @return 1 if the repository is empty, 0 if it isn't, error code - * if the repository is corrupted - */ -GIT_EXTERN(int) git_repository_is_empty(git_repository *repo); - -/** - * List of items which belong to the git repository layout - */ -typedef enum { - GIT_REPOSITORY_ITEM_GITDIR, - GIT_REPOSITORY_ITEM_WORKDIR, - GIT_REPOSITORY_ITEM_COMMONDIR, - GIT_REPOSITORY_ITEM_INDEX, - GIT_REPOSITORY_ITEM_OBJECTS, - GIT_REPOSITORY_ITEM_REFS, - GIT_REPOSITORY_ITEM_PACKED_REFS, - GIT_REPOSITORY_ITEM_REMOTES, - GIT_REPOSITORY_ITEM_CONFIG, - GIT_REPOSITORY_ITEM_INFO, - GIT_REPOSITORY_ITEM_HOOKS, - GIT_REPOSITORY_ITEM_LOGS, - GIT_REPOSITORY_ITEM_MODULES, - GIT_REPOSITORY_ITEM_WORKTREES, - GIT_REPOSITORY_ITEM_WORKTREE_CONFIG, - GIT_REPOSITORY_ITEM__LAST -} git_repository_item_t; - -/** - * Get the location of a specific repository file or directory - * - * This function will retrieve the path of a specific repository - * item. It will thereby honor things like the repository's - * common directory, gitdir, etc. In case a file path cannot - * exist for a given item (e.g. the working directory of a bare - * repository), GIT_ENOTFOUND is returned. - * - * @param out Buffer to store the path at - * @param repo Repository to get path for - * @param item The repository item for which to retrieve the path - * @return 0, GIT_ENOTFOUND if the path cannot exist or an error code - */ -GIT_EXTERN(int) git_repository_item_path(git_buf *out, const git_repository *repo, git_repository_item_t item); - -/** - * Get the path of this repository - * - * This is the path of the `.git` folder for normal repositories, - * or of the repository itself for bare repositories. - * - * @param repo A repository object - * @return the path to the repository - */ -GIT_EXTERN(const char *) git_repository_path(const git_repository *repo); - -/** - * Get the path of the working directory for this repository - * - * If the repository is bare, this function will always return - * NULL. - * - * @param repo A repository object - * @return the path to the working dir, if it exists - */ -GIT_EXTERN(const char *) git_repository_workdir(const git_repository *repo); - -/** - * Get the path of the shared common directory for this repository. - * - * If the repository is bare, it is the root directory for the repository. - * If the repository is a worktree, it is the parent repo's gitdir. - * Otherwise, it is the gitdir. - * - * @param repo A repository object - * @return the path to the common dir - */ -GIT_EXTERN(const char *) git_repository_commondir(const git_repository *repo); - -/** - * Set the path to the working directory for this repository - * - * The working directory doesn't need to be the same one - * that contains the `.git` folder for this repository. - * - * If this repository is bare, setting its working directory - * will turn it into a normal repository, capable of performing - * all the common workdir operations (checkout, status, index - * manipulation, etc). - * - * @param repo A repository object - * @param workdir The path to a working directory - * @param update_gitlink Create/update gitlink in workdir and set config - * "core.worktree" (if workdir is not the parent of the .git directory) - * @return 0, or an error code - */ -GIT_EXTERN(int) git_repository_set_workdir( - git_repository *repo, const char *workdir, int update_gitlink); - -/** - * Check if a repository is bare - * - * @param repo Repo to test - * @return 1 if the repository is bare, 0 otherwise. - */ -GIT_EXTERN(int) git_repository_is_bare(const git_repository *repo); - -/** - * Check if a repository is a linked work tree - * - * @param repo Repo to test - * @return 1 if the repository is a linked work tree, 0 otherwise. - */ -GIT_EXTERN(int) git_repository_is_worktree(const git_repository *repo); - -/** - * Get the configuration file for this repository. - * - * If a configuration file has not been set, the default - * config set for the repository will be returned, including - * global and system configurations (if they are available). - * - * The configuration file must be freed once it's no longer - * being used by the user. - * - * @param out Pointer to store the loaded configuration - * @param repo A repository object - * @return 0, or an error code - */ -GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo); - -/** - * Get a snapshot of the repository's configuration - * - * Convenience function to take a snapshot from the repository's - * configuration. The contents of this snapshot will not change, - * even if the underlying config files are modified. - * - * The configuration file must be freed once it's no longer - * being used by the user. - * - * @param out Pointer to store the loaded configuration - * @param repo the repository - * @return 0, or an error code - */ -GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository *repo); - -/** - * Get the Object Database for this repository. - * - * If a custom ODB has not been set, the default - * database for the repository will be returned (the one - * located in `.git/objects`). - * - * The ODB must be freed once it's no longer being used by - * the user. - * - * @param out Pointer to store the loaded ODB - * @param repo A repository object - * @return 0, or an error code - */ -GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo); - -/** - * Get the Reference Database Backend for this repository. - * - * If a custom refsdb has not been set, the default database for - * the repository will be returned (the one that manipulates loose - * and packed references in the `.git` directory). - * - * The refdb must be freed once it's no longer being used by - * the user. - * - * @param out Pointer to store the loaded refdb - * @param repo A repository object - * @return 0, or an error code - */ -GIT_EXTERN(int) git_repository_refdb(git_refdb **out, git_repository *repo); - -/** - * Get the Index file for this repository. - * - * If a custom index has not been set, the default - * index for the repository will be returned (the one - * located in `.git/index`). - * - * The index must be freed once it's no longer being used by - * the user. - * - * @param out Pointer to store the loaded index - * @param repo A repository object - * @return 0, or an error code - */ -GIT_EXTERN(int) git_repository_index(git_index **out, git_repository *repo); - -/** - * Retrieve git's prepared message - * - * Operations such as git revert/cherry-pick/merge with the -n option - * stop just short of creating a commit with the changes and save - * their prepared message in .git/MERGE_MSG so the next git-commit - * execution can present it to the user for them to amend if they - * wish. - * - * Use this function to get the contents of this file. Don't forget to - * remove the file after you create the commit. - * - * @param out git_buf to write data into - * @param repo Repository to read prepared message from - * @return 0, GIT_ENOTFOUND if no message exists or an error code - */ -GIT_EXTERN(int) git_repository_message(git_buf *out, git_repository *repo); - -/** - * Remove git's prepared message. - * - * Remove the message that `git_repository_message` retrieves. - * - * @param repo Repository to remove prepared message from. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_repository_message_remove(git_repository *repo); - -/** - * Remove all the metadata associated with an ongoing command like merge, - * revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG, etc. - * - * @param repo A repository object - * @return 0 on success, or error - */ -GIT_EXTERN(int) git_repository_state_cleanup(git_repository *repo); - -/** - * Callback used to iterate over each FETCH_HEAD entry - * - * @see git_repository_fetchhead_foreach - * - * @param ref_name The reference name - * @param remote_url The remote URL - * @param oid The reference target OID - * @param is_merge Was the reference the result of a merge - * @param payload Payload passed to git_repository_fetchhead_foreach - * @return non-zero to terminate the iteration - */ -typedef int GIT_CALLBACK(git_repository_fetchhead_foreach_cb)(const char *ref_name, - const char *remote_url, - const git_oid *oid, - unsigned int is_merge, - void *payload); - -/** - * Invoke 'callback' for each entry in the given FETCH_HEAD file. - * - * Return a non-zero value from the callback to stop the loop. - * - * @param repo A repository object - * @param callback Callback function - * @param payload Pointer to callback data (optional) - * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if - * there is no FETCH_HEAD file, or other error code. - */ -GIT_EXTERN(int) git_repository_fetchhead_foreach( - git_repository *repo, - git_repository_fetchhead_foreach_cb callback, - void *payload); - -/** - * Callback used to iterate over each MERGE_HEAD entry - * - * @see git_repository_mergehead_foreach - * - * @param oid The merge OID - * @param payload Payload passed to git_repository_mergehead_foreach - * @return non-zero to terminate the iteration - */ -typedef int GIT_CALLBACK(git_repository_mergehead_foreach_cb)(const git_oid *oid, - void *payload); - -/** - * If a merge is in progress, invoke 'callback' for each commit ID in the - * MERGE_HEAD file. - * - * Return a non-zero value from the callback to stop the loop. - * - * @param repo A repository object - * @param callback Callback function - * @param payload Pointer to callback data (optional) - * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if - * there is no MERGE_HEAD file, or other error code. - */ -GIT_EXTERN(int) git_repository_mergehead_foreach( - git_repository *repo, - git_repository_mergehead_foreach_cb callback, - void *payload); - -/** - * Calculate hash of file using repository filtering rules. - * - * If you simply want to calculate the hash of a file on disk with no filters, - * you can just use the `git_odb_hashfile()` API. However, if you want to - * hash a file in the repository and you want to apply filtering rules (e.g. - * crlf filters) before generating the SHA, then use this function. - * - * Note: if the repository has `core.safecrlf` set to fail and the - * filtering triggers that failure, then this function will return an - * error and not calculate the hash of the file. - * - * @param out Output value of calculated SHA - * @param repo Repository pointer - * @param path Path to file on disk whose contents should be hashed. This - * may be an absolute path or a relative path, in which case it - * will be treated as a path within the working directory. - * @param type The object type to hash as (e.g. GIT_OBJECT_BLOB) - * @param as_path The path to use to look up filtering rules. If this is - * an empty string then no filters will be applied when - * calculating the hash. If this is `NULL` and the `path` - * parameter is a file within the repository's working - * directory, then the `path` will be used. - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_repository_hashfile( - git_oid *out, - git_repository *repo, - const char *path, - git_object_t type, - const char *as_path); - -/** - * Make the repository HEAD point to the specified reference. - * - * If the provided reference points to a Tree or a Blob, the HEAD is - * unaltered and -1 is returned. - * - * If the provided reference points to a branch, the HEAD will point - * to that branch, staying attached, or become attached if it isn't yet. - * If the branch doesn't exist yet, no error will be return. The HEAD - * will then be attached to an unborn branch. - * - * Otherwise, the HEAD will be detached and will directly point to - * the Commit. - * - * @param repo Repository pointer - * @param refname Canonical name of the reference the HEAD should point at - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_repository_set_head( - git_repository *repo, - const char *refname); - -/** - * Make the repository HEAD directly point to the Commit. - * - * If the provided committish cannot be found in the repository, the HEAD - * is unaltered and GIT_ENOTFOUND is returned. - * - * If the provided committish cannot be peeled into a commit, the HEAD - * is unaltered and -1 is returned. - * - * Otherwise, the HEAD will eventually be detached and will directly point to - * the peeled Commit. - * - * @param repo Repository pointer - * @param committish Object id of the Commit the HEAD should point to - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_repository_set_head_detached( - git_repository *repo, - const git_oid *committish); - -/** - * Make the repository HEAD directly point to the Commit. - * - * This behaves like `git_repository_set_head_detached()` but takes an - * annotated commit, which lets you specify which extended sha syntax - * string was specified by a user, allowing for more exact reflog - * messages. - * - * See the documentation for `git_repository_set_head_detached()`. - * - * @see git_repository_set_head_detached - */ -GIT_EXTERN(int) git_repository_set_head_detached_from_annotated( - git_repository *repo, - const git_annotated_commit *committish); - -/** - * Detach the HEAD. - * - * If the HEAD is already detached and points to a Commit, 0 is returned. - * - * If the HEAD is already detached and points to a Tag, the HEAD is - * updated into making it point to the peeled Commit, and 0 is returned. - * - * If the HEAD is already detached and points to a non committish, the HEAD is - * unaltered, and -1 is returned. - * - * Otherwise, the HEAD will be detached and point to the peeled Commit. - * - * @param repo Repository pointer - * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing - * branch or an error code - */ -GIT_EXTERN(int) git_repository_detach_head( - git_repository *repo); - -/** - * Repository state - * - * These values represent possible states for the repository to be in, - * based on the current operation which is ongoing. - */ -typedef enum { - GIT_REPOSITORY_STATE_NONE, - GIT_REPOSITORY_STATE_MERGE, - GIT_REPOSITORY_STATE_REVERT, - GIT_REPOSITORY_STATE_REVERT_SEQUENCE, - GIT_REPOSITORY_STATE_CHERRYPICK, - GIT_REPOSITORY_STATE_CHERRYPICK_SEQUENCE, - GIT_REPOSITORY_STATE_BISECT, - GIT_REPOSITORY_STATE_REBASE, - GIT_REPOSITORY_STATE_REBASE_INTERACTIVE, - GIT_REPOSITORY_STATE_REBASE_MERGE, - GIT_REPOSITORY_STATE_APPLY_MAILBOX, - GIT_REPOSITORY_STATE_APPLY_MAILBOX_OR_REBASE -} git_repository_state_t; - -/** - * Determines the status of a git repository - ie, whether an operation - * (merge, cherry-pick, etc) is in progress. - * - * @param repo Repository pointer - * @return The state of the repository - */ -GIT_EXTERN(int) git_repository_state(git_repository *repo); - -/** - * Sets the active namespace for this Git Repository - * - * This namespace affects all reference operations for the repo. - * See `man gitnamespaces` - * - * @param repo The repo - * @param nmspace The namespace. This should not include the refs - * folder, e.g. to namespace all references under `refs/namespaces/foo/`, - * use `foo` as the namespace. - * @return 0 on success, -1 on error - */ -GIT_EXTERN(int) git_repository_set_namespace(git_repository *repo, const char *nmspace); - -/** - * Get the currently active namespace for this repository - * - * @param repo The repo - * @return the active namespace, or NULL if there isn't one - */ -GIT_EXTERN(const char *) git_repository_get_namespace(git_repository *repo); - - -/** - * Determine if the repository was a shallow clone - * - * @param repo The repository - * @return 1 if shallow, zero if not - */ -GIT_EXTERN(int) git_repository_is_shallow(git_repository *repo); - -/** - * Retrieve the configured identity to use for reflogs - * - * The memory is owned by the repository and must not be freed by the - * user. - * - * @param name where to store the pointer to the name - * @param email where to store the pointer to the email - * @param repo the repository - * @return 0 or an error code - */ -GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, const git_repository *repo); - -/** - * Set the identity to be used for writing reflogs - * - * If both are set, this name and email will be used to write to the - * reflog. Pass NULL to unset. When unset, the identity will be taken - * from the repository's configuration. - * - * @param repo the repository to configure - * @param name the name to use for the reflog entries - * @param email the email to use for the reflog entries - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name, const char *email); - -/** - * Gets the object type used by this repository. - * - * @param repo the repository - * @return the object id type - */ -GIT_EXTERN(git_oid_t) git_repository_oid_type(git_repository *repo); - -/** - * Gets the parents of the next commit, given the current repository state. - * Generally, this is the HEAD commit, except when performing a merge, in - * which case it is two or more commits. - * - * @param commits a `git_commitarray` that will contain the commit parents - * @param repo the repository - * @return 0 or an error code - */ -GIT_EXTERN(int) git_repository_commit_parents(git_commitarray *commits, git_repository *repo); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_repository_h__ +#define INCLUDE_git_repository_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "buffer.h" +#include "commit.h" + +/** + * @file git2/repository.h + * @brief Git repository management routines + * @defgroup git_repository Git repository management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Open a git repository. + * + * The 'path' argument must point to either a git repository + * folder, or an existing work dir. + * + * The method will automatically detect if 'path' is a normal + * or bare repository or fail is 'path' is neither. + * + * @param out pointer to the repo which will be opened + * @param path the path to the repository + * @return 0 or an error code + */ +GIT_EXTERN(int) git_repository_open(git_repository **out, const char *path); +/** + * Open working tree as a repository + * + * Open the working directory of the working tree as a normal + * repository that can then be worked on. + * + * @param out Output pointer containing opened repository + * @param wt Working tree to open + * @return 0 or an error code + */ +GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_worktree *wt); + +/** + * Create a "fake" repository to wrap an object database + * + * Create a repository object to wrap an object database to be used + * with the API when all you have is an object database. This doesn't + * have any paths associated with it, so use with care. + * + * @param out pointer to the repo + * @param odb the object database to wrap + * @param oid_type the oid type of the object database + * @return 0 or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_repository_wrap_odb( + git_repository **out, + git_odb *odb, + git_oid_t oid_type); +#else +GIT_EXTERN(int) git_repository_wrap_odb( + git_repository **out, + git_odb *odb); +#endif + +/** + * Look for a git repository and copy its path in the given buffer. + * The lookup start from base_path and walk across parent directories + * if nothing has been found. The lookup ends when the first repository + * is found, or when reaching a directory referenced in ceiling_dirs + * or when the filesystem changes (in case across_fs is true). + * + * The method will automatically detect if the repository is bare + * (if there is a repository). + * + * @param out A pointer to a user-allocated git_buf which will contain + * the found path. + * + * @param start_path The base path where the lookup starts. + * + * @param across_fs If true, then the lookup will not stop when a + * filesystem device change is detected while exploring parent directories. + * + * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR separated list of + * absolute symbolic link free paths. The lookup will stop when any + * of this paths is reached. Note that the lookup always performs on + * start_path no matter start_path appears in ceiling_dirs ceiling_dirs + * might be NULL (which is equivalent to an empty string) + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_repository_discover( + git_buf *out, + const char *start_path, + int across_fs, + const char *ceiling_dirs); + +/** + * Option flags for `git_repository_open_ext`. + */ +typedef enum { + /** + * Only open the repository if it can be immediately found in the + * start_path. Do not walk up from the start_path looking at parent + * directories. + */ + GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0), + + /** + * Unless this flag is set, open will not continue searching across + * filesystem boundaries (i.e. when `st_dev` changes from the `stat` + * system call). For example, searching in a user's home directory at + * "/home/user/source/" will not return "/.git/" as the found repo if + * "/" is a different filesystem than "/home". + */ + GIT_REPOSITORY_OPEN_CROSS_FS = (1 << 1), + + /** + * Open repository as a bare repo regardless of core.bare config, and + * defer loading config file for faster setup. + * Unlike `git_repository_open_bare`, this can follow gitlinks. + */ + GIT_REPOSITORY_OPEN_BARE = (1 << 2), + + /** + * Do not check for a repository by appending /.git to the start_path; + * only open the repository if start_path itself points to the git + * directory. + */ + GIT_REPOSITORY_OPEN_NO_DOTGIT = (1 << 3), + + /** + * Find and open a git repository, respecting the environment variables + * used by the git command-line tools. + * If set, `git_repository_open_ext` will ignore the other flags and + * the `ceiling_dirs` argument, and will allow a NULL `path` to use + * `GIT_DIR` or search from the current directory. + * The search for a repository will respect $GIT_CEILING_DIRECTORIES and + * $GIT_DISCOVERY_ACROSS_FILESYSTEM. The opened repository will + * respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and + * $GIT_ALTERNATE_OBJECT_DIRECTORIES. + * In the future, this flag will also cause `git_repository_open_ext` + * to respect $GIT_WORK_TREE and $GIT_COMMON_DIR; currently, + * `git_repository_open_ext` with this flag will error out if either + * $GIT_WORK_TREE or $GIT_COMMON_DIR is set. + */ + GIT_REPOSITORY_OPEN_FROM_ENV = (1 << 4) +} git_repository_open_flag_t; + +/** + * Find and open a repository with extended controls. + * + * @param out Pointer to the repo which will be opened. This can + * actually be NULL if you only want to use the error code to + * see if a repo at this path could be opened. + * @param path Path to open as git repository. If the flags + * permit "searching", then this can be a path to a subdirectory + * inside the working directory of the repository. May be NULL if + * flags is GIT_REPOSITORY_OPEN_FROM_ENV. + * @param flags A combination of the GIT_REPOSITORY_OPEN flags above. + * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR delimited list of path + * prefixes at which the search for a containing repository should + * terminate. + * @return 0 on success, GIT_ENOTFOUND if no repository could be found, + * or -1 if there was a repository but open failed for some reason + * (such as repo corruption or system errors). + */ +GIT_EXTERN(int) git_repository_open_ext( + git_repository **out, + const char *path, + unsigned int flags, + const char *ceiling_dirs); + +/** + * Open a bare repository on the serverside. + * + * This is a fast open for bare repositories that will come in handy + * if you're e.g. hosting git repositories and need to access them + * efficiently + * + * @param out Pointer to the repo which will be opened. + * @param bare_path Direct path to the bare repository + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_open_bare(git_repository **out, const char *bare_path); + +/** + * Free a previously allocated repository + * + * Note that after a repository is free'd, all the objects it has spawned + * will still exist until they are manually closed by the user + * with `git_object_free`, but accessing any of the attributes of + * an object without a backing repository will result in undefined + * behavior + * + * @param repo repository handle to close. If NULL nothing occurs. + */ +GIT_EXTERN(void) git_repository_free(git_repository *repo); + +/** + * Creates a new Git repository in the given folder. + * + * TODO: + * - Reinit the repository + * + * @param out pointer to the repo which will be created or reinitialized + * @param path the path to the repository + * @param is_bare if true, a Git repository without a working directory is + * created at the pointed path. If false, provided path will be + * considered as the working directory into which the .git directory + * will be created. + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_repository_init( + git_repository **out, + const char *path, + unsigned is_bare); + +/** + * Option flags for `git_repository_init_ext`. + * + * These flags configure extra behaviors to `git_repository_init_ext`. + * In every case, the default behavior is the zero value (i.e. flag is + * not set). Just OR the flag values together for the `flags` parameter + * when initializing a new repo. + */ +typedef enum { + /** + * Create a bare repository with no working directory. + */ + GIT_REPOSITORY_INIT_BARE = (1u << 0), + + /** + * Return an GIT_EEXISTS error if the repo_path appears to already be + * an git repository. + */ + GIT_REPOSITORY_INIT_NO_REINIT = (1u << 1), + + /** + * Normally a "/.git/" will be appended to the repo path for + * non-bare repos (if it is not already there), but passing this flag + * prevents that behavior. + */ + GIT_REPOSITORY_INIT_NO_DOTGIT_DIR = (1u << 2), + + /** + * Make the repo_path (and workdir_path) as needed. Init is always willing + * to create the ".git" directory even without this flag. This flag tells + * init to create the trailing component of the repo and workdir paths + * as needed. + */ + GIT_REPOSITORY_INIT_MKDIR = (1u << 3), + + /** + * Recursively make all components of the repo and workdir paths as + * necessary. + */ + GIT_REPOSITORY_INIT_MKPATH = (1u << 4), + + /** + * libgit2 normally uses internal templates to initialize a new repo. + * This flags enables external templates, looking the "template_path" from + * the options if set, or the `init.templatedir` global config if not, + * or falling back on "/usr/share/git-core/templates" if it exists. + */ + GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE = (1u << 5), + + /** + * If an alternate workdir is specified, use relative paths for the gitdir + * and core.worktree. + */ + GIT_REPOSITORY_INIT_RELATIVE_GITLINK = (1u << 6) +} git_repository_init_flag_t; + +/** + * Mode options for `git_repository_init_ext`. + * + * Set the mode field of the `git_repository_init_options` structure + * either to the custom mode that you would like, or to one of the + * defined modes. + */ +typedef enum { + /** + * Use permissions configured by umask - the default. + */ + GIT_REPOSITORY_INIT_SHARED_UMASK = 0, + + /** + * Use "--shared=group" behavior, chmod'ing the new repo to be group + * writable and "g+sx" for sticky group assignment. + */ + GIT_REPOSITORY_INIT_SHARED_GROUP = 0002775, + + /** + * Use "--shared=all" behavior, adding world readability. + */ + GIT_REPOSITORY_INIT_SHARED_ALL = 0002777 +} git_repository_init_mode_t; + +/** + * Extended options structure for `git_repository_init_ext`. + * + * This contains extra options for `git_repository_init_ext` that enable + * additional initialization features. + */ +typedef struct { + unsigned int version; + + /** + * Combination of GIT_REPOSITORY_INIT flags above. + */ + uint32_t flags; + + /** + * Set to one of the standard GIT_REPOSITORY_INIT_SHARED_... constants + * above, or to a custom value that you would like. + */ + uint32_t mode; + + /** + * The path to the working dir or NULL for default (i.e. repo_path parent + * on non-bare repos). IF THIS IS RELATIVE PATH, IT WILL BE EVALUATED + * RELATIVE TO THE REPO_PATH. If this is not the "natural" working + * directory, a .git gitlink file will be created here linking to the + * repo_path. + */ + const char *workdir_path; + + /** + * If set, this will be used to initialize the "description" file in the + * repository, instead of using the template content. + */ + const char *description; + + /** + * When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set, this contains + * the path to use for the template directory. If this is NULL, the config + * or default directory options will be used instead. + */ + const char *template_path; + + /** + * The name of the head to point HEAD at. If NULL, then this will be + * treated as "master" and the HEAD ref will be set to "refs/heads/master". + * If this begins with "refs/" it will be used verbatim; + * otherwise "refs/heads/" will be prefixed. + */ + const char *initial_head; + + /** + * If this is non-NULL, then after the rest of the repository + * initialization is completed, an "origin" remote will be added + * pointing to this URL. + */ + const char *origin_url; + +#ifdef GIT_EXPERIMENTAL_SHA256 + /** + * + * Type of object IDs to use for this repository, or 0 for + * default (currently SHA1). + */ + git_oid_t oid_type; +#endif +} git_repository_init_options; + +#define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1 +#define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION} + +/** + * Initialize git_repository_init_options structure + * + * Initializes a `git_repository_init_options` with default values. Equivalent to + * creating an instance with `GIT_REPOSITORY_INIT_OPTIONS_INIT`. + * + * @param opts The `git_repository_init_options` struct to initialize. + * @param version The struct version; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_repository_init_options_init( + git_repository_init_options *opts, + unsigned int version); + +/** + * Create a new Git repository in the given folder with extended controls. + * + * This will initialize a new git repository (creating the repo_path + * if requested by flags) and working directory as needed. It will + * auto-detect the case sensitivity of the file system and if the + * file system supports file mode bits correctly. + * + * @param out Pointer to the repo which will be created or reinitialized. + * @param repo_path The path to the repository. + * @param opts Pointer to git_repository_init_options struct. + * @return 0 or an error code on failure. + */ +GIT_EXTERN(int) git_repository_init_ext( + git_repository **out, + const char *repo_path, + git_repository_init_options *opts); + +/** + * Retrieve and resolve the reference pointed at by HEAD. + * + * The returned `git_reference` will be owned by caller and + * `git_reference_free()` must be called when done with it to release the + * allocated memory and prevent a leak. + * + * @param out pointer to the reference which will be retrieved + * @param repo a repository object + * + * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing + * branch, GIT_ENOTFOUND when HEAD is missing; an error code otherwise + */ +GIT_EXTERN(int) git_repository_head(git_reference **out, git_repository *repo); + +/** + * Retrieve the referenced HEAD for the worktree + * + * @param out pointer to the reference which will be retrieved + * @param repo a repository object + * @param name name of the worktree to retrieve HEAD for + * @return 0 when successful, error-code otherwise + */ +GIT_EXTERN(int) git_repository_head_for_worktree(git_reference **out, git_repository *repo, + const char *name); + +/** + * Check if a repository's HEAD is detached + * + * A repository's HEAD is detached when it points directly to a commit + * instead of a branch. + * + * @param repo Repo to test + * @return 1 if HEAD is detached, 0 if it's not; error code if there + * was an error. + */ +GIT_EXTERN(int) git_repository_head_detached(git_repository *repo); + +/** + * Check if a worktree's HEAD is detached + * + * A worktree's HEAD is detached when it points directly to a + * commit instead of a branch. + * + * @param repo a repository object + * @param name name of the worktree to retrieve HEAD for + * @return 1 if HEAD is detached, 0 if its not; error code if + * there was an error + */ +GIT_EXTERN(int) git_repository_head_detached_for_worktree(git_repository *repo, + const char *name); + +/** + * Check if the current branch is unborn + * + * An unborn branch is one named from HEAD but which doesn't exist in + * the refs namespace, because it doesn't have any commit to point to. + * + * @param repo Repo to test + * @return 1 if the current branch is unborn, 0 if it's not; error + * code if there was an error + */ +GIT_EXTERN(int) git_repository_head_unborn(git_repository *repo); + +/** + * Check if a repository is empty + * + * An empty repository has just been initialized and contains no references + * apart from HEAD, which must be pointing to the unborn master branch, + * or the branch specified for the repository in the `init.defaultBranch` + * configuration variable. + * + * @param repo Repo to test + * @return 1 if the repository is empty, 0 if it isn't, error code + * if the repository is corrupted + */ +GIT_EXTERN(int) git_repository_is_empty(git_repository *repo); + +/** + * List of items which belong to the git repository layout + */ +typedef enum { + GIT_REPOSITORY_ITEM_GITDIR, + GIT_REPOSITORY_ITEM_WORKDIR, + GIT_REPOSITORY_ITEM_COMMONDIR, + GIT_REPOSITORY_ITEM_INDEX, + GIT_REPOSITORY_ITEM_OBJECTS, + GIT_REPOSITORY_ITEM_REFS, + GIT_REPOSITORY_ITEM_PACKED_REFS, + GIT_REPOSITORY_ITEM_REMOTES, + GIT_REPOSITORY_ITEM_CONFIG, + GIT_REPOSITORY_ITEM_INFO, + GIT_REPOSITORY_ITEM_HOOKS, + GIT_REPOSITORY_ITEM_LOGS, + GIT_REPOSITORY_ITEM_MODULES, + GIT_REPOSITORY_ITEM_WORKTREES, + GIT_REPOSITORY_ITEM_WORKTREE_CONFIG, + GIT_REPOSITORY_ITEM__LAST +} git_repository_item_t; + +/** + * Get the location of a specific repository file or directory + * + * This function will retrieve the path of a specific repository + * item. It will thereby honor things like the repository's + * common directory, gitdir, etc. In case a file path cannot + * exist for a given item (e.g. the working directory of a bare + * repository), GIT_ENOTFOUND is returned. + * + * @param out Buffer to store the path at + * @param repo Repository to get path for + * @param item The repository item for which to retrieve the path + * @return 0, GIT_ENOTFOUND if the path cannot exist or an error code + */ +GIT_EXTERN(int) git_repository_item_path(git_buf *out, const git_repository *repo, git_repository_item_t item); + +/** + * Get the path of this repository + * + * This is the path of the `.git` folder for normal repositories, + * or of the repository itself for bare repositories. + * + * @param repo A repository object + * @return the path to the repository + */ +GIT_EXTERN(const char *) git_repository_path(const git_repository *repo); + +/** + * Get the path of the working directory for this repository + * + * If the repository is bare, this function will always return + * NULL. + * + * @param repo A repository object + * @return the path to the working dir, if it exists + */ +GIT_EXTERN(const char *) git_repository_workdir(const git_repository *repo); + +/** + * Get the path of the shared common directory for this repository. + * + * If the repository is bare, it is the root directory for the repository. + * If the repository is a worktree, it is the parent repo's gitdir. + * Otherwise, it is the gitdir. + * + * @param repo A repository object + * @return the path to the common dir + */ +GIT_EXTERN(const char *) git_repository_commondir(const git_repository *repo); + +/** + * Set the path to the working directory for this repository + * + * The working directory doesn't need to be the same one + * that contains the `.git` folder for this repository. + * + * If this repository is bare, setting its working directory + * will turn it into a normal repository, capable of performing + * all the common workdir operations (checkout, status, index + * manipulation, etc). + * + * @param repo A repository object + * @param workdir The path to a working directory + * @param update_gitlink Create/update gitlink in workdir and set config + * "core.worktree" (if workdir is not the parent of the .git directory) + * @return 0, or an error code + */ +GIT_EXTERN(int) git_repository_set_workdir( + git_repository *repo, const char *workdir, int update_gitlink); + +/** + * Check if a repository is bare + * + * @param repo Repo to test + * @return 1 if the repository is bare, 0 otherwise. + */ +GIT_EXTERN(int) git_repository_is_bare(const git_repository *repo); + +/** + * Check if a repository is a linked work tree + * + * @param repo Repo to test + * @return 1 if the repository is a linked work tree, 0 otherwise. + */ +GIT_EXTERN(int) git_repository_is_worktree(const git_repository *repo); + +/** + * Get the configuration file for this repository. + * + * If a configuration file has not been set, the default + * config set for the repository will be returned, including + * global and system configurations (if they are available). + * + * The configuration file must be freed once it's no longer + * being used by the user. + * + * @param out Pointer to store the loaded configuration + * @param repo A repository object + * @return 0, or an error code + */ +GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo); + +/** + * Get a snapshot of the repository's configuration + * + * Convenience function to take a snapshot from the repository's + * configuration. The contents of this snapshot will not change, + * even if the underlying config files are modified. + * + * The configuration file must be freed once it's no longer + * being used by the user. + * + * @param out Pointer to store the loaded configuration + * @param repo the repository + * @return 0, or an error code + */ +GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository *repo); + +/** + * Get the Object Database for this repository. + * + * If a custom ODB has not been set, the default + * database for the repository will be returned (the one + * located in `.git/objects`). + * + * The ODB must be freed once it's no longer being used by + * the user. + * + * @param out Pointer to store the loaded ODB + * @param repo A repository object + * @return 0, or an error code + */ +GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo); + +/** + * Get the Reference Database Backend for this repository. + * + * If a custom refsdb has not been set, the default database for + * the repository will be returned (the one that manipulates loose + * and packed references in the `.git` directory). + * + * The refdb must be freed once it's no longer being used by + * the user. + * + * @param out Pointer to store the loaded refdb + * @param repo A repository object + * @return 0, or an error code + */ +GIT_EXTERN(int) git_repository_refdb(git_refdb **out, git_repository *repo); + +/** + * Get the Index file for this repository. + * + * If a custom index has not been set, the default + * index for the repository will be returned (the one + * located in `.git/index`). + * + * The index must be freed once it's no longer being used by + * the user. + * + * @param out Pointer to store the loaded index + * @param repo A repository object + * @return 0, or an error code + */ +GIT_EXTERN(int) git_repository_index(git_index **out, git_repository *repo); + +/** + * Retrieve git's prepared message + * + * Operations such as git revert/cherry-pick/merge with the -n option + * stop just short of creating a commit with the changes and save + * their prepared message in .git/MERGE_MSG so the next git-commit + * execution can present it to the user for them to amend if they + * wish. + * + * Use this function to get the contents of this file. Don't forget to + * remove the file after you create the commit. + * + * @param out git_buf to write data into + * @param repo Repository to read prepared message from + * @return 0, GIT_ENOTFOUND if no message exists or an error code + */ +GIT_EXTERN(int) git_repository_message(git_buf *out, git_repository *repo); + +/** + * Remove git's prepared message. + * + * Remove the message that `git_repository_message` retrieves. + * + * @param repo Repository to remove prepared message from. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_repository_message_remove(git_repository *repo); + +/** + * Remove all the metadata associated with an ongoing command like merge, + * revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG, etc. + * + * @param repo A repository object + * @return 0 on success, or error + */ +GIT_EXTERN(int) git_repository_state_cleanup(git_repository *repo); + +/** + * Callback used to iterate over each FETCH_HEAD entry + * + * @see git_repository_fetchhead_foreach + * + * @param ref_name The reference name + * @param remote_url The remote URL + * @param oid The reference target OID + * @param is_merge Was the reference the result of a merge + * @param payload Payload passed to git_repository_fetchhead_foreach + * @return non-zero to terminate the iteration + */ +typedef int GIT_CALLBACK(git_repository_fetchhead_foreach_cb)(const char *ref_name, + const char *remote_url, + const git_oid *oid, + unsigned int is_merge, + void *payload); + +/** + * Invoke 'callback' for each entry in the given FETCH_HEAD file. + * + * Return a non-zero value from the callback to stop the loop. + * + * @param repo A repository object + * @param callback Callback function + * @param payload Pointer to callback data (optional) + * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if + * there is no FETCH_HEAD file, or other error code. + */ +GIT_EXTERN(int) git_repository_fetchhead_foreach( + git_repository *repo, + git_repository_fetchhead_foreach_cb callback, + void *payload); + +/** + * Callback used to iterate over each MERGE_HEAD entry + * + * @see git_repository_mergehead_foreach + * + * @param oid The merge OID + * @param payload Payload passed to git_repository_mergehead_foreach + * @return non-zero to terminate the iteration + */ +typedef int GIT_CALLBACK(git_repository_mergehead_foreach_cb)(const git_oid *oid, + void *payload); + +/** + * If a merge is in progress, invoke 'callback' for each commit ID in the + * MERGE_HEAD file. + * + * Return a non-zero value from the callback to stop the loop. + * + * @param repo A repository object + * @param callback Callback function + * @param payload Pointer to callback data (optional) + * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if + * there is no MERGE_HEAD file, or other error code. + */ +GIT_EXTERN(int) git_repository_mergehead_foreach( + git_repository *repo, + git_repository_mergehead_foreach_cb callback, + void *payload); + +/** + * Calculate hash of file using repository filtering rules. + * + * If you simply want to calculate the hash of a file on disk with no filters, + * you can just use the `git_odb_hashfile()` API. However, if you want to + * hash a file in the repository and you want to apply filtering rules (e.g. + * crlf filters) before generating the SHA, then use this function. + * + * Note: if the repository has `core.safecrlf` set to fail and the + * filtering triggers that failure, then this function will return an + * error and not calculate the hash of the file. + * + * @param out Output value of calculated SHA + * @param repo Repository pointer + * @param path Path to file on disk whose contents should be hashed. This + * may be an absolute path or a relative path, in which case it + * will be treated as a path within the working directory. + * @param type The object type to hash as (e.g. GIT_OBJECT_BLOB) + * @param as_path The path to use to look up filtering rules. If this is + * an empty string then no filters will be applied when + * calculating the hash. If this is `NULL` and the `path` + * parameter is a file within the repository's working + * directory, then the `path` will be used. + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_hashfile( + git_oid *out, + git_repository *repo, + const char *path, + git_object_t type, + const char *as_path); + +/** + * Make the repository HEAD point to the specified reference. + * + * If the provided reference points to a Tree or a Blob, the HEAD is + * unaltered and -1 is returned. + * + * If the provided reference points to a branch, the HEAD will point + * to that branch, staying attached, or become attached if it isn't yet. + * If the branch doesn't exist yet, no error will be return. The HEAD + * will then be attached to an unborn branch. + * + * Otherwise, the HEAD will be detached and will directly point to + * the Commit. + * + * @param repo Repository pointer + * @param refname Canonical name of the reference the HEAD should point at + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_set_head( + git_repository *repo, + const char *refname); + +/** + * Make the repository HEAD directly point to the Commit. + * + * If the provided committish cannot be found in the repository, the HEAD + * is unaltered and GIT_ENOTFOUND is returned. + * + * If the provided committish cannot be peeled into a commit, the HEAD + * is unaltered and -1 is returned. + * + * Otherwise, the HEAD will eventually be detached and will directly point to + * the peeled Commit. + * + * @param repo Repository pointer + * @param committish Object id of the Commit the HEAD should point to + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_set_head_detached( + git_repository *repo, + const git_oid *committish); + +/** + * Make the repository HEAD directly point to the Commit. + * + * This behaves like `git_repository_set_head_detached()` but takes an + * annotated commit, which lets you specify which extended sha syntax + * string was specified by a user, allowing for more exact reflog + * messages. + * + * See the documentation for `git_repository_set_head_detached()`. + * + * @see git_repository_set_head_detached + */ +GIT_EXTERN(int) git_repository_set_head_detached_from_annotated( + git_repository *repo, + const git_annotated_commit *committish); + +/** + * Detach the HEAD. + * + * If the HEAD is already detached and points to a Commit, 0 is returned. + * + * If the HEAD is already detached and points to a Tag, the HEAD is + * updated into making it point to the peeled Commit, and 0 is returned. + * + * If the HEAD is already detached and points to a non committish, the HEAD is + * unaltered, and -1 is returned. + * + * Otherwise, the HEAD will be detached and point to the peeled Commit. + * + * @param repo Repository pointer + * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing + * branch or an error code + */ +GIT_EXTERN(int) git_repository_detach_head( + git_repository *repo); + +/** + * Repository state + * + * These values represent possible states for the repository to be in, + * based on the current operation which is ongoing. + */ +typedef enum { + GIT_REPOSITORY_STATE_NONE, + GIT_REPOSITORY_STATE_MERGE, + GIT_REPOSITORY_STATE_REVERT, + GIT_REPOSITORY_STATE_REVERT_SEQUENCE, + GIT_REPOSITORY_STATE_CHERRYPICK, + GIT_REPOSITORY_STATE_CHERRYPICK_SEQUENCE, + GIT_REPOSITORY_STATE_BISECT, + GIT_REPOSITORY_STATE_REBASE, + GIT_REPOSITORY_STATE_REBASE_INTERACTIVE, + GIT_REPOSITORY_STATE_REBASE_MERGE, + GIT_REPOSITORY_STATE_APPLY_MAILBOX, + GIT_REPOSITORY_STATE_APPLY_MAILBOX_OR_REBASE +} git_repository_state_t; + +/** + * Determines the status of a git repository - ie, whether an operation + * (merge, cherry-pick, etc) is in progress. + * + * @param repo Repository pointer + * @return The state of the repository + */ +GIT_EXTERN(int) git_repository_state(git_repository *repo); + +/** + * Sets the active namespace for this Git Repository + * + * This namespace affects all reference operations for the repo. + * See `man gitnamespaces` + * + * @param repo The repo + * @param nmspace The namespace. This should not include the refs + * folder, e.g. to namespace all references under `refs/namespaces/foo/`, + * use `foo` as the namespace. + * @return 0 on success, -1 on error + */ +GIT_EXTERN(int) git_repository_set_namespace(git_repository *repo, const char *nmspace); + +/** + * Get the currently active namespace for this repository + * + * @param repo The repo + * @return the active namespace, or NULL if there isn't one + */ +GIT_EXTERN(const char *) git_repository_get_namespace(git_repository *repo); + + +/** + * Determine if the repository was a shallow clone + * + * @param repo The repository + * @return 1 if shallow, zero if not + */ +GIT_EXTERN(int) git_repository_is_shallow(git_repository *repo); + +/** + * Retrieve the configured identity to use for reflogs + * + * The memory is owned by the repository and must not be freed by the + * user. + * + * @param name where to store the pointer to the name + * @param email where to store the pointer to the email + * @param repo the repository + * @return 0 or an error code + */ +GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, const git_repository *repo); + +/** + * Set the identity to be used for writing reflogs + * + * If both are set, this name and email will be used to write to the + * reflog. Pass NULL to unset. When unset, the identity will be taken + * from the repository's configuration. + * + * @param repo the repository to configure + * @param name the name to use for the reflog entries + * @param email the email to use for the reflog entries + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name, const char *email); + +/** + * Gets the object type used by this repository. + * + * @param repo the repository + * @return the object id type + */ +GIT_EXTERN(git_oid_t) git_repository_oid_type(git_repository *repo); + +/** + * Gets the parents of the next commit, given the current repository state. + * Generally, this is the HEAD commit, except when performing a merge, in + * which case it is two or more commits. + * + * @param commits a `git_commitarray` that will contain the commit parents + * @param repo the repository + * @return 0 or an error code + */ +GIT_EXTERN(int) git_repository_commit_parents(git_commitarray *commits, git_repository *repo); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/reset.h b/3rdparty/libgit2/include/git2/reset.h index b2ee2ba..2c4c05a 100644 --- a/3rdparty/libgit2/include/git2/reset.h +++ b/3rdparty/libgit2/include/git2/reset.h @@ -1,111 +1,111 @@ -/* - * 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_reset_h__ -#define INCLUDE_git_reset_h__ - -#include "common.h" -#include "types.h" -#include "strarray.h" -#include "checkout.h" - -/** - * @file git2/reset.h - * @brief Git reset management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Kinds of reset operation - */ -typedef enum { - GIT_RESET_SOFT = 1, /**< Move the head to the given commit */ - GIT_RESET_MIXED = 2, /**< SOFT plus reset index to the commit */ - GIT_RESET_HARD = 3 /**< MIXED plus changes in working tree discarded */ -} git_reset_t; - -/** - * Sets the current head to the specified commit oid and optionally - * resets the index and working tree to match. - * - * SOFT reset means the Head will be moved to the commit. - * - * MIXED reset will trigger a SOFT reset, plus the index will be replaced - * with the content of the commit tree. - * - * HARD reset will trigger a MIXED reset and the working directory will be - * replaced with the content of the index. (Untracked and ignored files - * will be left alone, however.) - * - * TODO: Implement remaining kinds of resets. - * - * @param repo Repository where to perform the reset operation. - * - * @param target Committish to which the Head should be moved to. This object - * must belong to the given `repo` and can either be a git_commit or a - * git_tag. When a git_tag is being passed, it should be dereferenceable - * to a git_commit which oid will be used as the target of the branch. - * - * @param reset_type Kind of reset operation to perform. - * - * @param checkout_opts Optional checkout options to be used for a HARD reset. - * The checkout_strategy field will be overridden (based on reset_type). - * This parameter can be used to propagate notify and progress callbacks. - * - * @return 0 on success or an error code - */ -GIT_EXTERN(int) git_reset( - git_repository *repo, - const git_object *target, - git_reset_t reset_type, - const git_checkout_options *checkout_opts); - -/** - * Sets the current head to the specified commit oid and optionally - * resets the index and working tree to match. - * - * This behaves like `git_reset()` but takes an annotated commit, - * which lets you specify which extended sha syntax string was - * specified by a user, allowing for more exact reflog messages. - * - * See the documentation for `git_reset()`. - * - * @see git_reset - */ -GIT_EXTERN(int) git_reset_from_annotated( - git_repository *repo, - const git_annotated_commit *commit, - git_reset_t reset_type, - const git_checkout_options *checkout_opts); - -/** - * Updates some entries in the index from the target commit tree. - * - * The scope of the updated entries is determined by the paths - * being passed in the `pathspec` parameters. - * - * Passing a NULL `target` will result in removing - * entries in the index matching the provided pathspecs. - * - * @param repo Repository where to perform the reset operation. - * - * @param target The committish which content will be used to reset the content - * of the index. - * - * @param pathspecs List of pathspecs to operate on. - * - * @return 0 on success or an error code < 0 - */ -GIT_EXTERN(int) git_reset_default( - git_repository *repo, - const git_object *target, - const git_strarray* pathspecs); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_reset_h__ +#define INCLUDE_git_reset_h__ + +#include "common.h" +#include "types.h" +#include "strarray.h" +#include "checkout.h" + +/** + * @file git2/reset.h + * @brief Git reset management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Kinds of reset operation + */ +typedef enum { + GIT_RESET_SOFT = 1, /**< Move the head to the given commit */ + GIT_RESET_MIXED = 2, /**< SOFT plus reset index to the commit */ + GIT_RESET_HARD = 3 /**< MIXED plus changes in working tree discarded */ +} git_reset_t; + +/** + * Sets the current head to the specified commit oid and optionally + * resets the index and working tree to match. + * + * SOFT reset means the Head will be moved to the commit. + * + * MIXED reset will trigger a SOFT reset, plus the index will be replaced + * with the content of the commit tree. + * + * HARD reset will trigger a MIXED reset and the working directory will be + * replaced with the content of the index. (Untracked and ignored files + * will be left alone, however.) + * + * TODO: Implement remaining kinds of resets. + * + * @param repo Repository where to perform the reset operation. + * + * @param target Committish to which the Head should be moved to. This object + * must belong to the given `repo` and can either be a git_commit or a + * git_tag. When a git_tag is being passed, it should be dereferenceable + * to a git_commit which oid will be used as the target of the branch. + * + * @param reset_type Kind of reset operation to perform. + * + * @param checkout_opts Optional checkout options to be used for a HARD reset. + * The checkout_strategy field will be overridden (based on reset_type). + * This parameter can be used to propagate notify and progress callbacks. + * + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_reset( + git_repository *repo, + const git_object *target, + git_reset_t reset_type, + const git_checkout_options *checkout_opts); + +/** + * Sets the current head to the specified commit oid and optionally + * resets the index and working tree to match. + * + * This behaves like `git_reset()` but takes an annotated commit, + * which lets you specify which extended sha syntax string was + * specified by a user, allowing for more exact reflog messages. + * + * See the documentation for `git_reset()`. + * + * @see git_reset + */ +GIT_EXTERN(int) git_reset_from_annotated( + git_repository *repo, + const git_annotated_commit *commit, + git_reset_t reset_type, + const git_checkout_options *checkout_opts); + +/** + * Updates some entries in the index from the target commit tree. + * + * The scope of the updated entries is determined by the paths + * being passed in the `pathspec` parameters. + * + * Passing a NULL `target` will result in removing + * entries in the index matching the provided pathspecs. + * + * @param repo Repository where to perform the reset operation. + * + * @param target The committish which content will be used to reset the content + * of the index. + * + * @param pathspecs List of pathspecs to operate on. + * + * @return 0 on success or an error code < 0 + */ +GIT_EXTERN(int) git_reset_default( + git_repository *repo, + const git_object *target, + const git_strarray* pathspecs); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/revert.h b/3rdparty/libgit2/include/git2/revert.h index 331e90d..bd28e6e 100644 --- a/3rdparty/libgit2/include/git2/revert.h +++ b/3rdparty/libgit2/include/git2/revert.h @@ -1,91 +1,91 @@ -/* - * 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_revert_h__ -#define INCLUDE_git_revert_h__ - -#include "common.h" -#include "types.h" -#include "merge.h" - -/** - * @file git2/revert.h - * @brief Git revert routines - * @defgroup git_revert Git revert routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Options for revert - */ -typedef struct { - unsigned int version; - - /** For merge commits, the "mainline" is treated as the parent. */ - unsigned int mainline; - - git_merge_options merge_opts; /**< Options for the merging */ - git_checkout_options checkout_opts; /**< Options for the checkout */ -} git_revert_options; - -#define GIT_REVERT_OPTIONS_VERSION 1 -#define GIT_REVERT_OPTIONS_INIT {GIT_REVERT_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT} - -/** - * Initialize git_revert_options structure - * - * Initializes a `git_revert_options` with default values. Equivalent to - * creating an instance with `GIT_REVERT_OPTIONS_INIT`. - * - * @param opts The `git_revert_options` struct to initialize. - * @param version The struct version; pass `GIT_REVERT_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_revert_options_init( - git_revert_options *opts, - unsigned int version); - -/** - * Reverts the given commit against the given "our" commit, producing an - * index that reflects the result of the revert. - * - * The returned index must be freed explicitly with `git_index_free`. - * - * @param out pointer to store the index result in - * @param repo the repository that contains the given commits - * @param revert_commit the commit to revert - * @param our_commit the commit to revert against (eg, HEAD) - * @param mainline the parent of the revert commit, if it is a merge - * @param merge_options the merge options (or null for defaults) - * @return zero on success, -1 on failure. - */ -GIT_EXTERN(int) git_revert_commit( - git_index **out, - git_repository *repo, - git_commit *revert_commit, - git_commit *our_commit, - unsigned int mainline, - const git_merge_options *merge_options); - -/** - * Reverts the given commit, producing changes in the index and working directory. - * - * @param repo the repository to revert - * @param commit the commit to revert - * @param given_opts the revert options (or null for defaults) - * @return zero on success, -1 on failure. - */ -GIT_EXTERN(int) git_revert( - git_repository *repo, - git_commit *commit, - const git_revert_options *given_opts); - -/** @} */ -GIT_END_DECL -#endif - +/* + * 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_revert_h__ +#define INCLUDE_git_revert_h__ + +#include "common.h" +#include "types.h" +#include "merge.h" + +/** + * @file git2/revert.h + * @brief Git revert routines + * @defgroup git_revert Git revert routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Options for revert + */ +typedef struct { + unsigned int version; + + /** For merge commits, the "mainline" is treated as the parent. */ + unsigned int mainline; + + git_merge_options merge_opts; /**< Options for the merging */ + git_checkout_options checkout_opts; /**< Options for the checkout */ +} git_revert_options; + +#define GIT_REVERT_OPTIONS_VERSION 1 +#define GIT_REVERT_OPTIONS_INIT {GIT_REVERT_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT} + +/** + * Initialize git_revert_options structure + * + * Initializes a `git_revert_options` with default values. Equivalent to + * creating an instance with `GIT_REVERT_OPTIONS_INIT`. + * + * @param opts The `git_revert_options` struct to initialize. + * @param version The struct version; pass `GIT_REVERT_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_revert_options_init( + git_revert_options *opts, + unsigned int version); + +/** + * Reverts the given commit against the given "our" commit, producing an + * index that reflects the result of the revert. + * + * The returned index must be freed explicitly with `git_index_free`. + * + * @param out pointer to store the index result in + * @param repo the repository that contains the given commits + * @param revert_commit the commit to revert + * @param our_commit the commit to revert against (eg, HEAD) + * @param mainline the parent of the revert commit, if it is a merge + * @param merge_options the merge options (or null for defaults) + * @return zero on success, -1 on failure. + */ +GIT_EXTERN(int) git_revert_commit( + git_index **out, + git_repository *repo, + git_commit *revert_commit, + git_commit *our_commit, + unsigned int mainline, + const git_merge_options *merge_options); + +/** + * Reverts the given commit, producing changes in the index and working directory. + * + * @param repo the repository to revert + * @param commit the commit to revert + * @param given_opts the revert options (or null for defaults) + * @return zero on success, -1 on failure. + */ +GIT_EXTERN(int) git_revert( + git_repository *repo, + git_commit *commit, + const git_revert_options *given_opts); + +/** @} */ +GIT_END_DECL +#endif + diff --git a/3rdparty/libgit2/include/git2/revparse.h b/3rdparty/libgit2/include/git2/revparse.h index 51ea2dc..727e04e 100644 --- a/3rdparty/libgit2/include/git2/revparse.h +++ b/3rdparty/libgit2/include/git2/revparse.h @@ -1,113 +1,113 @@ -/* - * 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_revparse_h__ -#define INCLUDE_git_revparse_h__ - -#include "common.h" -#include "types.h" - -/** - * @file git2/revparse.h - * @brief Git revision parsing routines - * @defgroup git_revparse Git revision parsing routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Find a single object, as specified by a revision string. - * - * See `man gitrevisions`, or - * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for - * information on the syntax accepted. - * - * The returned object should be released with `git_object_free` when no - * longer needed. - * - * @param out pointer to output object - * @param repo the repository to search in - * @param spec the textual specification for an object - * @return 0 on success, GIT_ENOTFOUND, GIT_EAMBIGUOUS, GIT_EINVALIDSPEC or an error code - */ -GIT_EXTERN(int) git_revparse_single( - git_object **out, git_repository *repo, const char *spec); - -/** - * Find a single object and intermediate reference by a revision string. - * - * See `man gitrevisions`, or - * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for - * information on the syntax accepted. - * - * In some cases (`@{<-n>}` or `@{upstream}`), the expression may - * point to an intermediate reference. When such expressions are being passed - * in, `reference_out` will be valued as well. - * - * The returned object should be released with `git_object_free` and the - * returned reference with `git_reference_free` when no longer needed. - * - * @param object_out pointer to output object - * @param reference_out pointer to output reference or NULL - * @param repo the repository to search in - * @param spec the textual specification for an object - * @return 0 on success, GIT_ENOTFOUND, GIT_EAMBIGUOUS, GIT_EINVALIDSPEC - * or an error code - */ -GIT_EXTERN(int) git_revparse_ext( - git_object **object_out, - git_reference **reference_out, - git_repository *repo, - const char *spec); - -/** - * Revparse flags. These indicate the intended behavior of the spec passed to - * git_revparse. - */ -typedef enum { - /** The spec targeted a single object. */ - GIT_REVSPEC_SINGLE = 1 << 0, - /** The spec targeted a range of commits. */ - GIT_REVSPEC_RANGE = 1 << 1, - /** The spec used the '...' operator, which invokes special semantics. */ - GIT_REVSPEC_MERGE_BASE = 1 << 2 -} git_revspec_t; - -/** - * Git Revision Spec: output of a `git_revparse` operation - */ -typedef struct { - /** The left element of the revspec; must be freed by the user */ - git_object *from; - /** The right element of the revspec; must be freed by the user */ - git_object *to; - /** The intent of the revspec (i.e. `git_revspec_mode_t` flags) */ - unsigned int flags; -} git_revspec; - -/** - * Parse a revision string for `from`, `to`, and intent. - * - * See `man gitrevisions` or - * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for - * information on the syntax accepted. - * - * @param revspec Pointer to an user-allocated git_revspec struct where - * the result of the rev-parse will be stored - * @param repo the repository to search in - * @param spec the rev-parse spec to parse - * @return 0 on success, GIT_INVALIDSPEC, GIT_ENOTFOUND, GIT_EAMBIGUOUS or an error code - */ -GIT_EXTERN(int) git_revparse( - git_revspec *revspec, - git_repository *repo, - const char *spec); - - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_revparse_h__ +#define INCLUDE_git_revparse_h__ + +#include "common.h" +#include "types.h" + +/** + * @file git2/revparse.h + * @brief Git revision parsing routines + * @defgroup git_revparse Git revision parsing routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Find a single object, as specified by a revision string. + * + * See `man gitrevisions`, or + * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for + * information on the syntax accepted. + * + * The returned object should be released with `git_object_free` when no + * longer needed. + * + * @param out pointer to output object + * @param repo the repository to search in + * @param spec the textual specification for an object + * @return 0 on success, GIT_ENOTFOUND, GIT_EAMBIGUOUS, GIT_EINVALIDSPEC or an error code + */ +GIT_EXTERN(int) git_revparse_single( + git_object **out, git_repository *repo, const char *spec); + +/** + * Find a single object and intermediate reference by a revision string. + * + * See `man gitrevisions`, or + * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for + * information on the syntax accepted. + * + * In some cases (`@{<-n>}` or `@{upstream}`), the expression may + * point to an intermediate reference. When such expressions are being passed + * in, `reference_out` will be valued as well. + * + * The returned object should be released with `git_object_free` and the + * returned reference with `git_reference_free` when no longer needed. + * + * @param object_out pointer to output object + * @param reference_out pointer to output reference or NULL + * @param repo the repository to search in + * @param spec the textual specification for an object + * @return 0 on success, GIT_ENOTFOUND, GIT_EAMBIGUOUS, GIT_EINVALIDSPEC + * or an error code + */ +GIT_EXTERN(int) git_revparse_ext( + git_object **object_out, + git_reference **reference_out, + git_repository *repo, + const char *spec); + +/** + * Revparse flags. These indicate the intended behavior of the spec passed to + * git_revparse. + */ +typedef enum { + /** The spec targeted a single object. */ + GIT_REVSPEC_SINGLE = 1 << 0, + /** The spec targeted a range of commits. */ + GIT_REVSPEC_RANGE = 1 << 1, + /** The spec used the '...' operator, which invokes special semantics. */ + GIT_REVSPEC_MERGE_BASE = 1 << 2 +} git_revspec_t; + +/** + * Git Revision Spec: output of a `git_revparse` operation + */ +typedef struct { + /** The left element of the revspec; must be freed by the user */ + git_object *from; + /** The right element of the revspec; must be freed by the user */ + git_object *to; + /** The intent of the revspec (i.e. `git_revspec_mode_t` flags) */ + unsigned int flags; +} git_revspec; + +/** + * Parse a revision string for `from`, `to`, and intent. + * + * See `man gitrevisions` or + * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for + * information on the syntax accepted. + * + * @param revspec Pointer to an user-allocated git_revspec struct where + * the result of the rev-parse will be stored + * @param repo the repository to search in + * @param spec the rev-parse spec to parse + * @return 0 on success, GIT_INVALIDSPEC, GIT_ENOTFOUND, GIT_EAMBIGUOUS or an error code + */ +GIT_EXTERN(int) git_revparse( + git_revspec *revspec, + git_repository *repo, + const char *spec); + + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/revwalk.h b/3rdparty/libgit2/include/git2/revwalk.h index 4aa9f5b..05da79a 100644 --- a/3rdparty/libgit2/include/git2/revwalk.h +++ b/3rdparty/libgit2/include/git2/revwalk.h @@ -1,302 +1,302 @@ -/* - * 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_revwalk_h__ -#define INCLUDE_git_revwalk_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" - -/** - * @file git2/revwalk.h - * @brief Git revision traversal routines - * @defgroup git_revwalk Git revision traversal routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Flags to specify the sorting which a revwalk should perform. - */ -typedef enum { - /** - * Sort the output with the same default method from `git`: reverse - * chronological order. This is the default sorting for new walkers. - */ - GIT_SORT_NONE = 0, - - /** - * Sort the repository contents in topological order (no parents before - * all of its children are shown); this sorting mode can be combined - * with time sorting to produce `git`'s `--date-order``. - */ - GIT_SORT_TOPOLOGICAL = 1 << 0, - - /** - * Sort the repository contents by commit time; - * this sorting mode can be combined with - * topological sorting. - */ - GIT_SORT_TIME = 1 << 1, - - /** - * Iterate through the repository contents in reverse - * order; this sorting mode can be combined with - * any of the above. - */ - GIT_SORT_REVERSE = 1 << 2 -} git_sort_t; - -/** - * Allocate a new revision walker to iterate through a repo. - * - * This revision walker uses a custom memory pool and an internal - * commit cache, so it is relatively expensive to allocate. - * - * For maximum performance, this revision walker should be - * reused for different walks. - * - * This revision walker is *not* thread safe: it may only be - * used to walk a repository on a single thread; however, - * it is possible to have several revision walkers in - * several different threads walking the same repository. - * - * @param out pointer to the new revision walker - * @param repo the repo to walk through - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_new(git_revwalk **out, git_repository *repo); - -/** - * Reset the revision walker for reuse. - * - * This will clear all the pushed and hidden commits, and - * leave the walker in a blank state (just like at - * creation) ready to receive new commit pushes and - * start a new walk. - * - * The revision walk is automatically reset when a walk - * is over. - * - * @param walker handle to reset. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_reset(git_revwalk *walker); - -/** - * Add a new root for the traversal - * - * The pushed commit will be marked as one of the roots from which to - * start the walk. This commit may not be walked if it or a child is - * hidden. - * - * At least one commit must be pushed onto the walker before a walk - * can be started. - * - * The given id must belong to a committish on the walked - * repository. - * - * @param walk the walker being used for the traversal. - * @param id the oid of the commit to start from. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_push(git_revwalk *walk, const git_oid *id); - -/** - * Push matching references - * - * The OIDs pointed to by the references that match the given glob - * pattern will be pushed to the revision walker. - * - * A leading 'refs/' is implied if not present as well as a trailing - * '/\*' if the glob lacks '?', '\*' or '['. - * - * Any references matching this glob which do not point to a - * committish will be ignored. - * - * @param walk the walker being used for the traversal - * @param glob the glob pattern references should match - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_push_glob(git_revwalk *walk, const char *glob); - -/** - * Push the repository's HEAD - * - * @param walk the walker being used for the traversal - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_push_head(git_revwalk *walk); - -/** - * Mark a commit (and its ancestors) uninteresting for the output. - * - * The given id must belong to a committish on the walked - * repository. - * - * The resolved commit and all its parents will be hidden from the - * output on the revision walk. - * - * @param walk the walker being used for the traversal. - * @param commit_id the oid of commit that will be ignored during the traversal - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_hide(git_revwalk *walk, const git_oid *commit_id); - -/** - * Hide matching references. - * - * The OIDs pointed to by the references that match the given glob - * pattern and their ancestors will be hidden from the output on the - * revision walk. - * - * A leading 'refs/' is implied if not present as well as a trailing - * '/\*' if the glob lacks '?', '\*' or '['. - * - * Any references matching this glob which do not point to a - * committish will be ignored. - * - * @param walk the walker being used for the traversal - * @param glob the glob pattern references should match - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_hide_glob(git_revwalk *walk, const char *glob); - -/** - * Hide the repository's HEAD - * - * @param walk the walker being used for the traversal - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_hide_head(git_revwalk *walk); - -/** - * Push the OID pointed to by a reference - * - * The reference must point to a committish. - * - * @param walk the walker being used for the traversal - * @param refname the reference to push - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_push_ref(git_revwalk *walk, const char *refname); - -/** - * Hide the OID pointed to by a reference - * - * The reference must point to a committish. - * - * @param walk the walker being used for the traversal - * @param refname the reference to hide - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_hide_ref(git_revwalk *walk, const char *refname); - -/** - * Get the next commit from the revision walk. - * - * The initial call to this method is *not* blocking when - * iterating through a repo with a time-sorting mode. - * - * Iterating with Topological or inverted modes makes the initial - * call blocking to preprocess the commit list, but this block should be - * mostly unnoticeable on most repositories (topological preprocessing - * times at 0.3s on the git.git repo). - * - * The revision walker is reset when the walk is over. - * - * @param out Pointer where to store the oid of the next commit - * @param walk the walker to pop the commit from. - * @return 0 if the next commit was found; - * GIT_ITEROVER if there are no commits left to iterate - */ -GIT_EXTERN(int) git_revwalk_next(git_oid *out, git_revwalk *walk); - -/** - * Change the sorting mode when iterating through the - * repository's contents. - * - * Changing the sorting mode resets the walker. - * - * @param walk the walker being used for the traversal. - * @param sort_mode combination of GIT_SORT_XXX flags - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_sorting(git_revwalk *walk, unsigned int sort_mode); - -/** - * Push and hide the respective endpoints of the given range. - * - * The range should be of the form - * .. - * where each is in the form accepted by 'git_revparse_single'. - * The left-hand commit will be hidden and the right-hand commit pushed. - * - * @param walk the walker being used for the traversal - * @param range the range - * @return 0 or an error code - * - */ -GIT_EXTERN(int) git_revwalk_push_range(git_revwalk *walk, const char *range); - -/** - * Simplify the history by first-parent - * - * No parents other than the first for each commit will be enqueued. - * - * @param walk The revision walker. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_revwalk_simplify_first_parent(git_revwalk *walk); - - -/** - * Free a revision walker previously allocated. - * - * @param walk traversal handle to close. If NULL nothing occurs. - */ -GIT_EXTERN(void) git_revwalk_free(git_revwalk *walk); - -/** - * Return the repository on which this walker - * is operating. - * - * @param walk the revision walker - * @return the repository being walked - */ -GIT_EXTERN(git_repository *) git_revwalk_repository(git_revwalk *walk); - -/** - * This is a callback function that user can provide to hide a - * commit and its parents. If the callback function returns non-zero value, - * then this commit and its parents will be hidden. - * - * @param commit_id oid of Commit - * @param payload User-specified pointer to data to be passed as data payload - * @return non-zero to hide the commmit and it parent. - */ -typedef int GIT_CALLBACK(git_revwalk_hide_cb)( - const git_oid *commit_id, - void *payload); - -/** - * Adds, changes or removes a callback function to hide a commit and its parents - * - * @param walk the revision walker - * @param hide_cb callback function to hide a commit and its parents - * @param payload data payload to be passed to callback function - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_revwalk_add_hide_cb( - git_revwalk *walk, - git_revwalk_hide_cb hide_cb, - void *payload); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_revwalk_h__ +#define INCLUDE_git_revwalk_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" + +/** + * @file git2/revwalk.h + * @brief Git revision traversal routines + * @defgroup git_revwalk Git revision traversal routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Flags to specify the sorting which a revwalk should perform. + */ +typedef enum { + /** + * Sort the output with the same default method from `git`: reverse + * chronological order. This is the default sorting for new walkers. + */ + GIT_SORT_NONE = 0, + + /** + * Sort the repository contents in topological order (no parents before + * all of its children are shown); this sorting mode can be combined + * with time sorting to produce `git`'s `--date-order``. + */ + GIT_SORT_TOPOLOGICAL = 1 << 0, + + /** + * Sort the repository contents by commit time; + * this sorting mode can be combined with + * topological sorting. + */ + GIT_SORT_TIME = 1 << 1, + + /** + * Iterate through the repository contents in reverse + * order; this sorting mode can be combined with + * any of the above. + */ + GIT_SORT_REVERSE = 1 << 2 +} git_sort_t; + +/** + * Allocate a new revision walker to iterate through a repo. + * + * This revision walker uses a custom memory pool and an internal + * commit cache, so it is relatively expensive to allocate. + * + * For maximum performance, this revision walker should be + * reused for different walks. + * + * This revision walker is *not* thread safe: it may only be + * used to walk a repository on a single thread; however, + * it is possible to have several revision walkers in + * several different threads walking the same repository. + * + * @param out pointer to the new revision walker + * @param repo the repo to walk through + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_new(git_revwalk **out, git_repository *repo); + +/** + * Reset the revision walker for reuse. + * + * This will clear all the pushed and hidden commits, and + * leave the walker in a blank state (just like at + * creation) ready to receive new commit pushes and + * start a new walk. + * + * The revision walk is automatically reset when a walk + * is over. + * + * @param walker handle to reset. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_reset(git_revwalk *walker); + +/** + * Add a new root for the traversal + * + * The pushed commit will be marked as one of the roots from which to + * start the walk. This commit may not be walked if it or a child is + * hidden. + * + * At least one commit must be pushed onto the walker before a walk + * can be started. + * + * The given id must belong to a committish on the walked + * repository. + * + * @param walk the walker being used for the traversal. + * @param id the oid of the commit to start from. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_push(git_revwalk *walk, const git_oid *id); + +/** + * Push matching references + * + * The OIDs pointed to by the references that match the given glob + * pattern will be pushed to the revision walker. + * + * A leading 'refs/' is implied if not present as well as a trailing + * '/\*' if the glob lacks '?', '\*' or '['. + * + * Any references matching this glob which do not point to a + * committish will be ignored. + * + * @param walk the walker being used for the traversal + * @param glob the glob pattern references should match + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_push_glob(git_revwalk *walk, const char *glob); + +/** + * Push the repository's HEAD + * + * @param walk the walker being used for the traversal + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_push_head(git_revwalk *walk); + +/** + * Mark a commit (and its ancestors) uninteresting for the output. + * + * The given id must belong to a committish on the walked + * repository. + * + * The resolved commit and all its parents will be hidden from the + * output on the revision walk. + * + * @param walk the walker being used for the traversal. + * @param commit_id the oid of commit that will be ignored during the traversal + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_hide(git_revwalk *walk, const git_oid *commit_id); + +/** + * Hide matching references. + * + * The OIDs pointed to by the references that match the given glob + * pattern and their ancestors will be hidden from the output on the + * revision walk. + * + * A leading 'refs/' is implied if not present as well as a trailing + * '/\*' if the glob lacks '?', '\*' or '['. + * + * Any references matching this glob which do not point to a + * committish will be ignored. + * + * @param walk the walker being used for the traversal + * @param glob the glob pattern references should match + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_hide_glob(git_revwalk *walk, const char *glob); + +/** + * Hide the repository's HEAD + * + * @param walk the walker being used for the traversal + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_hide_head(git_revwalk *walk); + +/** + * Push the OID pointed to by a reference + * + * The reference must point to a committish. + * + * @param walk the walker being used for the traversal + * @param refname the reference to push + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_push_ref(git_revwalk *walk, const char *refname); + +/** + * Hide the OID pointed to by a reference + * + * The reference must point to a committish. + * + * @param walk the walker being used for the traversal + * @param refname the reference to hide + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_hide_ref(git_revwalk *walk, const char *refname); + +/** + * Get the next commit from the revision walk. + * + * The initial call to this method is *not* blocking when + * iterating through a repo with a time-sorting mode. + * + * Iterating with Topological or inverted modes makes the initial + * call blocking to preprocess the commit list, but this block should be + * mostly unnoticeable on most repositories (topological preprocessing + * times at 0.3s on the git.git repo). + * + * The revision walker is reset when the walk is over. + * + * @param out Pointer where to store the oid of the next commit + * @param walk the walker to pop the commit from. + * @return 0 if the next commit was found; + * GIT_ITEROVER if there are no commits left to iterate + */ +GIT_EXTERN(int) git_revwalk_next(git_oid *out, git_revwalk *walk); + +/** + * Change the sorting mode when iterating through the + * repository's contents. + * + * Changing the sorting mode resets the walker. + * + * @param walk the walker being used for the traversal. + * @param sort_mode combination of GIT_SORT_XXX flags + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_sorting(git_revwalk *walk, unsigned int sort_mode); + +/** + * Push and hide the respective endpoints of the given range. + * + * The range should be of the form + * .. + * where each is in the form accepted by 'git_revparse_single'. + * The left-hand commit will be hidden and the right-hand commit pushed. + * + * @param walk the walker being used for the traversal + * @param range the range + * @return 0 or an error code + * + */ +GIT_EXTERN(int) git_revwalk_push_range(git_revwalk *walk, const char *range); + +/** + * Simplify the history by first-parent + * + * No parents other than the first for each commit will be enqueued. + * + * @param walk The revision walker. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_revwalk_simplify_first_parent(git_revwalk *walk); + + +/** + * Free a revision walker previously allocated. + * + * @param walk traversal handle to close. If NULL nothing occurs. + */ +GIT_EXTERN(void) git_revwalk_free(git_revwalk *walk); + +/** + * Return the repository on which this walker + * is operating. + * + * @param walk the revision walker + * @return the repository being walked + */ +GIT_EXTERN(git_repository *) git_revwalk_repository(git_revwalk *walk); + +/** + * This is a callback function that user can provide to hide a + * commit and its parents. If the callback function returns non-zero value, + * then this commit and its parents will be hidden. + * + * @param commit_id oid of Commit + * @param payload User-specified pointer to data to be passed as data payload + * @return non-zero to hide the commmit and it parent. + */ +typedef int GIT_CALLBACK(git_revwalk_hide_cb)( + const git_oid *commit_id, + void *payload); + +/** + * Adds, changes or removes a callback function to hide a commit and its parents + * + * @param walk the revision walker + * @param hide_cb callback function to hide a commit and its parents + * @param payload data payload to be passed to callback function + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_revwalk_add_hide_cb( + git_revwalk *walk, + git_revwalk_hide_cb hide_cb, + void *payload); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/signature.h b/3rdparty/libgit2/include/git2/signature.h index 849998e..29e4225 100644 --- a/3rdparty/libgit2/include/git2/signature.h +++ b/3rdparty/libgit2/include/git2/signature.h @@ -1,103 +1,103 @@ -/* - * 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_signature_h__ -#define INCLUDE_git_signature_h__ - -#include "common.h" -#include "types.h" - -/** - * @file git2/signature.h - * @brief Git signature creation - * @defgroup git_signature Git signature creation - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Create a new action signature. - * - * Call `git_signature_free()` to free the data. - * - * Note: angle brackets ('<' and '>') characters are not allowed - * to be used in either the `name` or the `email` parameter. - * - * @param out new signature, in case of error NULL - * @param name name of the person - * @param email email of the person - * @param time time (in seconds from epoch) when the action happened - * @param offset timezone offset (in minutes) for the time - * @return 0 or an error code - */ -GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const char *email, git_time_t time, int offset); - -/** - * Create a new action signature with a timestamp of 'now'. - * - * Call `git_signature_free()` to free the data. - * - * @param out new signature, in case of error NULL - * @param name name of the person - * @param email email of the person - * @return 0 or an error code - */ -GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const char *email); - -/** - * Create a new action signature with default user and now timestamp. - * - * This looks up the user.name and user.email from the configuration and - * uses the current time as the timestamp, and creates a new signature - * based on that information. It will return GIT_ENOTFOUND if either the - * user.name or user.email are not set. - * - * @param out new signature - * @param repo repository pointer - * @return 0 on success, GIT_ENOTFOUND if config is missing, or error code - */ -GIT_EXTERN(int) git_signature_default(git_signature **out, git_repository *repo); - -/** - * Create a new signature by parsing the given buffer, which is - * expected to be in the format "Real Name timestamp tzoffset", - * where `timestamp` is the number of seconds since the Unix epoch and - * `tzoffset` is the timezone offset in `hhmm` format (note the lack - * of a colon separator). - * - * @param out new signature - * @param buf signature string - * @return 0 on success, GIT_EINVALID if the signature is not parseable, or an error code - */ -GIT_EXTERN(int) git_signature_from_buffer(git_signature **out, const char *buf); - -/** - * Create a copy of an existing signature. All internal strings are also - * duplicated. - * - * Call `git_signature_free()` to free the data. - * - * @param dest pointer where to store the copy - * @param sig signature to duplicate - * @return 0 or an error code - */ -GIT_EXTERN(int) git_signature_dup(git_signature **dest, const git_signature *sig); - -/** - * Free an existing signature. - * - * Because the signature is not an opaque structure, it is legal to free it - * manually, but be sure to free the "name" and "email" strings in addition - * to the structure itself. - * - * @param sig signature to free - */ -GIT_EXTERN(void) git_signature_free(git_signature *sig); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_signature_h__ +#define INCLUDE_git_signature_h__ + +#include "common.h" +#include "types.h" + +/** + * @file git2/signature.h + * @brief Git signature creation + * @defgroup git_signature Git signature creation + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a new action signature. + * + * Call `git_signature_free()` to free the data. + * + * Note: angle brackets ('<' and '>') characters are not allowed + * to be used in either the `name` or the `email` parameter. + * + * @param out new signature, in case of error NULL + * @param name name of the person + * @param email email of the person + * @param time time (in seconds from epoch) when the action happened + * @param offset timezone offset (in minutes) for the time + * @return 0 or an error code + */ +GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const char *email, git_time_t time, int offset); + +/** + * Create a new action signature with a timestamp of 'now'. + * + * Call `git_signature_free()` to free the data. + * + * @param out new signature, in case of error NULL + * @param name name of the person + * @param email email of the person + * @return 0 or an error code + */ +GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const char *email); + +/** + * Create a new action signature with default user and now timestamp. + * + * This looks up the user.name and user.email from the configuration and + * uses the current time as the timestamp, and creates a new signature + * based on that information. It will return GIT_ENOTFOUND if either the + * user.name or user.email are not set. + * + * @param out new signature + * @param repo repository pointer + * @return 0 on success, GIT_ENOTFOUND if config is missing, or error code + */ +GIT_EXTERN(int) git_signature_default(git_signature **out, git_repository *repo); + +/** + * Create a new signature by parsing the given buffer, which is + * expected to be in the format "Real Name timestamp tzoffset", + * where `timestamp` is the number of seconds since the Unix epoch and + * `tzoffset` is the timezone offset in `hhmm` format (note the lack + * of a colon separator). + * + * @param out new signature + * @param buf signature string + * @return 0 on success, GIT_EINVALID if the signature is not parseable, or an error code + */ +GIT_EXTERN(int) git_signature_from_buffer(git_signature **out, const char *buf); + +/** + * Create a copy of an existing signature. All internal strings are also + * duplicated. + * + * Call `git_signature_free()` to free the data. + * + * @param dest pointer where to store the copy + * @param sig signature to duplicate + * @return 0 or an error code + */ +GIT_EXTERN(int) git_signature_dup(git_signature **dest, const git_signature *sig); + +/** + * Free an existing signature. + * + * Because the signature is not an opaque structure, it is legal to free it + * manually, but be sure to free the "name" and "email" strings in addition + * to the structure itself. + * + * @param sig signature to free + */ +GIT_EXTERN(void) git_signature_free(git_signature *sig); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/stash.h b/3rdparty/libgit2/include/git2/stash.h index dcfc013..a785f2b 100644 --- a/3rdparty/libgit2/include/git2/stash.h +++ b/3rdparty/libgit2/include/git2/stash.h @@ -1,314 +1,314 @@ -/* - * 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_stash_h__ -#define INCLUDE_git_stash_h__ - -#include "common.h" -#include "types.h" -#include "checkout.h" - -/** - * @file git2/stash.h - * @brief Git stash management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Stash flags - */ -typedef enum { - /** - * No option, default - */ - GIT_STASH_DEFAULT = 0, - - /** - * All changes already added to the index are left intact in - * the working directory - */ - GIT_STASH_KEEP_INDEX = (1 << 0), - - /** - * All untracked files are also stashed and then cleaned up - * from the working directory - */ - GIT_STASH_INCLUDE_UNTRACKED = (1 << 1), - - /** - * All ignored files are also stashed and then cleaned up from - * the working directory - */ - GIT_STASH_INCLUDE_IGNORED = (1 << 2), - - /** - * All changes in the index and working directory are left intact - */ - GIT_STASH_KEEP_ALL = (1 << 3) -} git_stash_flags; - -/** - * Save the local modifications to a new stash. - * - * @param out Object id of the commit containing the stashed state. - * This commit is also the target of the direct reference refs/stash. - * @param repo The owning repository. - * @param stasher The identity of the person performing the stashing. - * @param message Optional description along with the stashed state. - * @param flags Flags to control the stashing process. (see GIT_STASH_* above) - * @return 0 on success, GIT_ENOTFOUND where there's nothing to stash, - * or error code. - */ -GIT_EXTERN(int) git_stash_save( - git_oid *out, - git_repository *repo, - const git_signature *stasher, - const char *message, - uint32_t flags); - -/** - * Stash save options structure - * - * Initialize with `GIT_STASH_SAVE_OPTIONS_INIT`. Alternatively, you can - * use `git_stash_save_options_init`. - * - */ -typedef struct git_stash_save_options { - unsigned int version; - - /** Flags to control the stashing process. (see GIT_STASH_* above) */ - uint32_t flags; - - /** The identity of the person performing the stashing. */ - const git_signature *stasher; - - /** Optional description along with the stashed state. */ - const char *message; - - /** Optional paths that control which files are stashed. */ - git_strarray paths; -} git_stash_save_options; - -#define GIT_STASH_SAVE_OPTIONS_VERSION 1 -#define GIT_STASH_SAVE_OPTIONS_INIT { GIT_STASH_SAVE_OPTIONS_VERSION } - -/** - * Initialize git_stash_save_options structure - * - * Initializes a `git_stash_save_options` with default values. Equivalent to - * creating an instance with `GIT_STASH_SAVE_OPTIONS_INIT`. - * - * @param opts The `git_stash_save_options` struct to initialize. - * @param version The struct version; pass `GIT_STASH_SAVE_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_stash_save_options_init( - git_stash_save_options *opts, unsigned int version); - -/** - * Save the local modifications to a new stash, with options. - * - * @param out Object id of the commit containing the stashed state. - * This commit is also the target of the direct reference refs/stash. - * @param repo The owning repository. - * @param opts The stash options. - * @return 0 on success, GIT_ENOTFOUND where there's nothing to stash, - * or error code. - */ -GIT_EXTERN(int) git_stash_save_with_opts( - git_oid *out, - git_repository *repo, - const git_stash_save_options *opts); - -/** Stash application flags. */ -typedef enum { - GIT_STASH_APPLY_DEFAULT = 0, - - /* Try to reinstate not only the working tree's changes, - * but also the index's changes. - */ - GIT_STASH_APPLY_REINSTATE_INDEX = (1 << 0) -} git_stash_apply_flags; - -/** Stash apply progression states */ -typedef enum { - GIT_STASH_APPLY_PROGRESS_NONE = 0, - - /** Loading the stashed data from the object database. */ - GIT_STASH_APPLY_PROGRESS_LOADING_STASH, - - /** The stored index is being analyzed. */ - GIT_STASH_APPLY_PROGRESS_ANALYZE_INDEX, - - /** The modified files are being analyzed. */ - GIT_STASH_APPLY_PROGRESS_ANALYZE_MODIFIED, - - /** The untracked and ignored files are being analyzed. */ - GIT_STASH_APPLY_PROGRESS_ANALYZE_UNTRACKED, - - /** The untracked files are being written to disk. */ - GIT_STASH_APPLY_PROGRESS_CHECKOUT_UNTRACKED, - - /** The modified files are being written to disk. */ - GIT_STASH_APPLY_PROGRESS_CHECKOUT_MODIFIED, - - /** The stash was applied successfully. */ - GIT_STASH_APPLY_PROGRESS_DONE -} git_stash_apply_progress_t; - -/** - * Stash application progress notification function. - * Return 0 to continue processing, or a negative value to - * abort the stash application. - */ -typedef int GIT_CALLBACK(git_stash_apply_progress_cb)( - git_stash_apply_progress_t progress, - void *payload); - -/** - * Stash application options structure - * - * Initialize with `GIT_STASH_APPLY_OPTIONS_INIT`. Alternatively, you can - * use `git_stash_apply_options_init`. - * - */ -typedef struct git_stash_apply_options { - unsigned int version; - - /** See `git_stash_apply_flags`, above. */ - uint32_t flags; - - /** Options to use when writing files to the working directory. */ - git_checkout_options checkout_options; - - /** Optional callback to notify the consumer of application progress. */ - git_stash_apply_progress_cb progress_cb; - void *progress_payload; -} git_stash_apply_options; - -#define GIT_STASH_APPLY_OPTIONS_VERSION 1 -#define GIT_STASH_APPLY_OPTIONS_INIT { \ - GIT_STASH_APPLY_OPTIONS_VERSION, \ - GIT_STASH_APPLY_DEFAULT, \ - GIT_CHECKOUT_OPTIONS_INIT } - -/** - * Initialize git_stash_apply_options structure - * - * Initializes a `git_stash_apply_options` with default values. Equivalent to - * creating an instance with `GIT_STASH_APPLY_OPTIONS_INIT`. - * - * @param opts The `git_stash_apply_options` struct to initialize. - * @param version The struct version; pass `GIT_STASH_APPLY_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_stash_apply_options_init( - git_stash_apply_options *opts, unsigned int version); - -/** - * Apply a single stashed state from the stash list. - * - * If local changes in the working directory conflict with changes in the - * stash then GIT_EMERGECONFLICT will be returned. In this case, the index - * will always remain unmodified and all files in the working directory will - * remain unmodified. However, if you are restoring untracked files or - * ignored files and there is a conflict when applying the modified files, - * then those files will remain in the working directory. - * - * If passing the GIT_STASH_APPLY_REINSTATE_INDEX flag and there would be - * conflicts when reinstating the index, the function will return - * GIT_EMERGECONFLICT and both the working directory and index will be left - * unmodified. - * - * Note that a minimum checkout strategy of `GIT_CHECKOUT_SAFE` is implied. - * - * @param repo The owning repository. - * @param index The position within the stash list. 0 points to the - * most recent stashed state. - * @param options Optional options to control how stashes are applied. - * - * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the - * given index, GIT_EMERGECONFLICT if changes exist in the working - * directory, or an error code - */ -GIT_EXTERN(int) git_stash_apply( - git_repository *repo, - size_t index, - const git_stash_apply_options *options); - -/** - * This is a callback function you can provide to iterate over all the - * stashed states that will be invoked per entry. - * - * @param index The position within the stash list. 0 points to the - * most recent stashed state. - * @param message The stash message. - * @param stash_id The commit oid of the stashed state. - * @param payload Extra parameter to callback function. - * @return 0 to continue iterating or non-zero to stop. - */ -typedef int GIT_CALLBACK(git_stash_cb)( - size_t index, - const char *message, - const git_oid *stash_id, - void *payload); - -/** - * Loop over all the stashed states and issue a callback for each one. - * - * If the callback returns a non-zero value, this will stop looping. - * - * @param repo Repository where to find the stash. - * - * @param callback Callback to invoke per found stashed state. The most - * recent stash state will be enumerated first. - * - * @param payload Extra parameter to callback function. - * - * @return 0 on success, non-zero callback return value, or error code. - */ -GIT_EXTERN(int) git_stash_foreach( - git_repository *repo, - git_stash_cb callback, - void *payload); - -/** - * Remove a single stashed state from the stash list. - * - * @param repo The owning repository. - * - * @param index The position within the stash list. 0 points to the - * most recent stashed state. - * - * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the given - * index, or error code. - */ -GIT_EXTERN(int) git_stash_drop( - git_repository *repo, - size_t index); - -/** - * Apply a single stashed state from the stash list and remove it from the list - * if successful. - * - * @param repo The owning repository. - * @param index The position within the stash list. 0 points to the - * most recent stashed state. - * @param options Optional options to control how stashes are applied. - * - * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the given - * index, or error code. (see git_stash_apply() above for details) -*/ -GIT_EXTERN(int) git_stash_pop( - git_repository *repo, - size_t index, - const git_stash_apply_options *options); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_stash_h__ +#define INCLUDE_git_stash_h__ + +#include "common.h" +#include "types.h" +#include "checkout.h" + +/** + * @file git2/stash.h + * @brief Git stash management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Stash flags + */ +typedef enum { + /** + * No option, default + */ + GIT_STASH_DEFAULT = 0, + + /** + * All changes already added to the index are left intact in + * the working directory + */ + GIT_STASH_KEEP_INDEX = (1 << 0), + + /** + * All untracked files are also stashed and then cleaned up + * from the working directory + */ + GIT_STASH_INCLUDE_UNTRACKED = (1 << 1), + + /** + * All ignored files are also stashed and then cleaned up from + * the working directory + */ + GIT_STASH_INCLUDE_IGNORED = (1 << 2), + + /** + * All changes in the index and working directory are left intact + */ + GIT_STASH_KEEP_ALL = (1 << 3) +} git_stash_flags; + +/** + * Save the local modifications to a new stash. + * + * @param out Object id of the commit containing the stashed state. + * This commit is also the target of the direct reference refs/stash. + * @param repo The owning repository. + * @param stasher The identity of the person performing the stashing. + * @param message Optional description along with the stashed state. + * @param flags Flags to control the stashing process. (see GIT_STASH_* above) + * @return 0 on success, GIT_ENOTFOUND where there's nothing to stash, + * or error code. + */ +GIT_EXTERN(int) git_stash_save( + git_oid *out, + git_repository *repo, + const git_signature *stasher, + const char *message, + uint32_t flags); + +/** + * Stash save options structure + * + * Initialize with `GIT_STASH_SAVE_OPTIONS_INIT`. Alternatively, you can + * use `git_stash_save_options_init`. + * + */ +typedef struct git_stash_save_options { + unsigned int version; + + /** Flags to control the stashing process. (see GIT_STASH_* above) */ + uint32_t flags; + + /** The identity of the person performing the stashing. */ + const git_signature *stasher; + + /** Optional description along with the stashed state. */ + const char *message; + + /** Optional paths that control which files are stashed. */ + git_strarray paths; +} git_stash_save_options; + +#define GIT_STASH_SAVE_OPTIONS_VERSION 1 +#define GIT_STASH_SAVE_OPTIONS_INIT { GIT_STASH_SAVE_OPTIONS_VERSION } + +/** + * Initialize git_stash_save_options structure + * + * Initializes a `git_stash_save_options` with default values. Equivalent to + * creating an instance with `GIT_STASH_SAVE_OPTIONS_INIT`. + * + * @param opts The `git_stash_save_options` struct to initialize. + * @param version The struct version; pass `GIT_STASH_SAVE_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_stash_save_options_init( + git_stash_save_options *opts, unsigned int version); + +/** + * Save the local modifications to a new stash, with options. + * + * @param out Object id of the commit containing the stashed state. + * This commit is also the target of the direct reference refs/stash. + * @param repo The owning repository. + * @param opts The stash options. + * @return 0 on success, GIT_ENOTFOUND where there's nothing to stash, + * or error code. + */ +GIT_EXTERN(int) git_stash_save_with_opts( + git_oid *out, + git_repository *repo, + const git_stash_save_options *opts); + +/** Stash application flags. */ +typedef enum { + GIT_STASH_APPLY_DEFAULT = 0, + + /* Try to reinstate not only the working tree's changes, + * but also the index's changes. + */ + GIT_STASH_APPLY_REINSTATE_INDEX = (1 << 0) +} git_stash_apply_flags; + +/** Stash apply progression states */ +typedef enum { + GIT_STASH_APPLY_PROGRESS_NONE = 0, + + /** Loading the stashed data from the object database. */ + GIT_STASH_APPLY_PROGRESS_LOADING_STASH, + + /** The stored index is being analyzed. */ + GIT_STASH_APPLY_PROGRESS_ANALYZE_INDEX, + + /** The modified files are being analyzed. */ + GIT_STASH_APPLY_PROGRESS_ANALYZE_MODIFIED, + + /** The untracked and ignored files are being analyzed. */ + GIT_STASH_APPLY_PROGRESS_ANALYZE_UNTRACKED, + + /** The untracked files are being written to disk. */ + GIT_STASH_APPLY_PROGRESS_CHECKOUT_UNTRACKED, + + /** The modified files are being written to disk. */ + GIT_STASH_APPLY_PROGRESS_CHECKOUT_MODIFIED, + + /** The stash was applied successfully. */ + GIT_STASH_APPLY_PROGRESS_DONE +} git_stash_apply_progress_t; + +/** + * Stash application progress notification function. + * Return 0 to continue processing, or a negative value to + * abort the stash application. + */ +typedef int GIT_CALLBACK(git_stash_apply_progress_cb)( + git_stash_apply_progress_t progress, + void *payload); + +/** + * Stash application options structure + * + * Initialize with `GIT_STASH_APPLY_OPTIONS_INIT`. Alternatively, you can + * use `git_stash_apply_options_init`. + * + */ +typedef struct git_stash_apply_options { + unsigned int version; + + /** See `git_stash_apply_flags`, above. */ + uint32_t flags; + + /** Options to use when writing files to the working directory. */ + git_checkout_options checkout_options; + + /** Optional callback to notify the consumer of application progress. */ + git_stash_apply_progress_cb progress_cb; + void *progress_payload; +} git_stash_apply_options; + +#define GIT_STASH_APPLY_OPTIONS_VERSION 1 +#define GIT_STASH_APPLY_OPTIONS_INIT { \ + GIT_STASH_APPLY_OPTIONS_VERSION, \ + GIT_STASH_APPLY_DEFAULT, \ + GIT_CHECKOUT_OPTIONS_INIT } + +/** + * Initialize git_stash_apply_options structure + * + * Initializes a `git_stash_apply_options` with default values. Equivalent to + * creating an instance with `GIT_STASH_APPLY_OPTIONS_INIT`. + * + * @param opts The `git_stash_apply_options` struct to initialize. + * @param version The struct version; pass `GIT_STASH_APPLY_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_stash_apply_options_init( + git_stash_apply_options *opts, unsigned int version); + +/** + * Apply a single stashed state from the stash list. + * + * If local changes in the working directory conflict with changes in the + * stash then GIT_EMERGECONFLICT will be returned. In this case, the index + * will always remain unmodified and all files in the working directory will + * remain unmodified. However, if you are restoring untracked files or + * ignored files and there is a conflict when applying the modified files, + * then those files will remain in the working directory. + * + * If passing the GIT_STASH_APPLY_REINSTATE_INDEX flag and there would be + * conflicts when reinstating the index, the function will return + * GIT_EMERGECONFLICT and both the working directory and index will be left + * unmodified. + * + * Note that a minimum checkout strategy of `GIT_CHECKOUT_SAFE` is implied. + * + * @param repo The owning repository. + * @param index The position within the stash list. 0 points to the + * most recent stashed state. + * @param options Optional options to control how stashes are applied. + * + * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the + * given index, GIT_EMERGECONFLICT if changes exist in the working + * directory, or an error code + */ +GIT_EXTERN(int) git_stash_apply( + git_repository *repo, + size_t index, + const git_stash_apply_options *options); + +/** + * This is a callback function you can provide to iterate over all the + * stashed states that will be invoked per entry. + * + * @param index The position within the stash list. 0 points to the + * most recent stashed state. + * @param message The stash message. + * @param stash_id The commit oid of the stashed state. + * @param payload Extra parameter to callback function. + * @return 0 to continue iterating or non-zero to stop. + */ +typedef int GIT_CALLBACK(git_stash_cb)( + size_t index, + const char *message, + const git_oid *stash_id, + void *payload); + +/** + * Loop over all the stashed states and issue a callback for each one. + * + * If the callback returns a non-zero value, this will stop looping. + * + * @param repo Repository where to find the stash. + * + * @param callback Callback to invoke per found stashed state. The most + * recent stash state will be enumerated first. + * + * @param payload Extra parameter to callback function. + * + * @return 0 on success, non-zero callback return value, or error code. + */ +GIT_EXTERN(int) git_stash_foreach( + git_repository *repo, + git_stash_cb callback, + void *payload); + +/** + * Remove a single stashed state from the stash list. + * + * @param repo The owning repository. + * + * @param index The position within the stash list. 0 points to the + * most recent stashed state. + * + * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the given + * index, or error code. + */ +GIT_EXTERN(int) git_stash_drop( + git_repository *repo, + size_t index); + +/** + * Apply a single stashed state from the stash list and remove it from the list + * if successful. + * + * @param repo The owning repository. + * @param index The position within the stash list. 0 points to the + * most recent stashed state. + * @param options Optional options to control how stashes are applied. + * + * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the given + * index, or error code. (see git_stash_apply() above for details) +*/ +GIT_EXTERN(int) git_stash_pop( + git_repository *repo, + size_t index, + const git_stash_apply_options *options); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/status.h b/3rdparty/libgit2/include/git2/status.h index bb28e87..cfe4ec7 100644 --- a/3rdparty/libgit2/include/git2/status.h +++ b/3rdparty/libgit2/include/git2/status.h @@ -1,452 +1,452 @@ -/* - * 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_status_h__ -#define INCLUDE_git_status_h__ - -#include "common.h" -#include "types.h" -#include "strarray.h" -#include "diff.h" - -/** - * @file git2/status.h - * @brief Git file status routines - * @defgroup git_status Git file status routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Status flags for a single file. - * - * A combination of these values will be returned to indicate the status of - * a file. Status compares the working directory, the index, and the - * current HEAD of the repository. The `GIT_STATUS_INDEX` set of flags - * represents the status of file in the index relative to the HEAD, and the - * `GIT_STATUS_WT` set of flags represent the status of the file in the - * working directory relative to the index. - */ -typedef enum { - GIT_STATUS_CURRENT = 0, - - GIT_STATUS_INDEX_NEW = (1u << 0), - GIT_STATUS_INDEX_MODIFIED = (1u << 1), - GIT_STATUS_INDEX_DELETED = (1u << 2), - GIT_STATUS_INDEX_RENAMED = (1u << 3), - GIT_STATUS_INDEX_TYPECHANGE = (1u << 4), - - GIT_STATUS_WT_NEW = (1u << 7), - GIT_STATUS_WT_MODIFIED = (1u << 8), - GIT_STATUS_WT_DELETED = (1u << 9), - GIT_STATUS_WT_TYPECHANGE = (1u << 10), - GIT_STATUS_WT_RENAMED = (1u << 11), - GIT_STATUS_WT_UNREADABLE = (1u << 12), - - GIT_STATUS_IGNORED = (1u << 14), - GIT_STATUS_CONFLICTED = (1u << 15) -} git_status_t; - -/** - * Function pointer to receive status on individual files - * - * `path` is the relative path to the file from the root of the repository. - * - * `status_flags` is a combination of `git_status_t` values that apply. - * - * `payload` is the value you passed to the foreach function as payload. - */ -typedef int GIT_CALLBACK(git_status_cb)( - const char *path, unsigned int status_flags, void *payload); - -/** - * Select the files on which to report status. - * - * With `git_status_foreach_ext`, this will control which changes get - * callbacks. With `git_status_list_new`, these will control which - * changes are included in the list. - */ -typedef enum { - /** - * The default. This roughly matches `git status --porcelain` regarding - * which files are included and in what order. - */ - GIT_STATUS_SHOW_INDEX_AND_WORKDIR = 0, - - /** - * Only gives status based on HEAD to index comparison, not looking at - * working directory changes. - */ - GIT_STATUS_SHOW_INDEX_ONLY = 1, - - /** - * Only gives status based on index to working directory comparison, - * not comparing the index to the HEAD. - */ - GIT_STATUS_SHOW_WORKDIR_ONLY = 2 -} git_status_show_t; - -/** - * Flags to control status callbacks - * - * Calling `git_status_foreach()` is like calling the extended version - * with: GIT_STATUS_OPT_INCLUDE_IGNORED, GIT_STATUS_OPT_INCLUDE_UNTRACKED, - * and GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS. Those options are bundled - * together as `GIT_STATUS_OPT_DEFAULTS` if you want them as a baseline. - */ -typedef enum { - /** - * Says that callbacks should be made on untracked files. - * These will only be made if the workdir files are included in the status - * "show" option. - */ - GIT_STATUS_OPT_INCLUDE_UNTRACKED = (1u << 0), - - /** - * Says that ignored files get callbacks. - * Again, these callbacks will only be made if the workdir files are - * included in the status "show" option. - */ - GIT_STATUS_OPT_INCLUDE_IGNORED = (1u << 1), - - /** - * Indicates that callback should be made even on unmodified files. - */ - GIT_STATUS_OPT_INCLUDE_UNMODIFIED = (1u << 2), - - /** - * Indicates that submodules should be skipped. - * This only applies if there are no pending typechanges to the submodule - * (either from or to another type). - */ - GIT_STATUS_OPT_EXCLUDE_SUBMODULES = (1u << 3), - - /** - * Indicates that all files in untracked directories should be included. - * Normally if an entire directory is new, then just the top-level - * directory is included (with a trailing slash on the entry name). - * This flag says to include all of the individual files in the directory - * instead. - */ - GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS = (1u << 4), - - /** - * Indicates that the given path should be treated as a literal path, - * and not as a pathspec pattern. - */ - GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH = (1u << 5), - - /** - * Indicates that the contents of ignored directories should be included - * in the status. This is like doing `git ls-files -o -i --exclude-standard` - * with core git. - */ - GIT_STATUS_OPT_RECURSE_IGNORED_DIRS = (1u << 6), - - /** - * Indicates that rename detection should be processed between the head and - * the index and enables the GIT_STATUS_INDEX_RENAMED as a possible status - * flag. - */ - GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX = (1u << 7), - - /** - * Indicates that rename detection should be run between the index and the - * working directory and enabled GIT_STATUS_WT_RENAMED as a possible status - * flag. - */ - GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR = (1u << 8), - - /** - * Overrides the native case sensitivity for the file system and forces - * the output to be in case-sensitive order. - */ - GIT_STATUS_OPT_SORT_CASE_SENSITIVELY = (1u << 9), - - /** - * Overrides the native case sensitivity for the file system and forces - * the output to be in case-insensitive order. - */ - GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY = (1u << 10), - - /** - * Iindicates that rename detection should include rewritten files. - */ - GIT_STATUS_OPT_RENAMES_FROM_REWRITES = (1u << 11), - - /** - * Bypasses the default status behavior of doing a "soft" index reload - * (i.e. reloading the index data if the file on disk has been modified - * outside libgit2). - */ - GIT_STATUS_OPT_NO_REFRESH = (1u << 12), - - /** - * Tells libgit2 to refresh the stat cache in the index for files that are - * unchanged but have out of date stat einformation in the index. - * It will result in less work being done on subsequent calls to get status. - * This is mutually exclusive with the NO_REFRESH option. - */ - GIT_STATUS_OPT_UPDATE_INDEX = (1u << 13), - - /** - * Normally files that cannot be opened or read are ignored as - * these are often transient files; this option will return - * unreadable files as `GIT_STATUS_WT_UNREADABLE`. - */ - GIT_STATUS_OPT_INCLUDE_UNREADABLE = (1u << 14), - - /** - * Unreadable files will be detected and given the status - * untracked instead of unreadable. - */ - GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 15) -} git_status_opt_t; - -#define GIT_STATUS_OPT_DEFAULTS \ - (GIT_STATUS_OPT_INCLUDE_IGNORED | \ - GIT_STATUS_OPT_INCLUDE_UNTRACKED | \ - GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS) - -/** - * Options to control how `git_status_foreach_ext()` will issue callbacks. - * - * Initialize with `GIT_STATUS_OPTIONS_INIT`. Alternatively, you can - * use `git_status_options_init`. - * - */ -typedef struct { - /** - * The struct version; pass `GIT_STATUS_OPTIONS_VERSION`. - */ - unsigned int version; - - /** - * The `show` value is one of the `git_status_show_t` constants that - * control which files to scan and in what order. The default is - * `GIT_STATUS_SHOW_INDEX_AND_WORKDIR`. - */ - git_status_show_t show; - - /** - * The `flags` value is an OR'ed combination of the - * `git_status_opt_t` values above. The default is - * `GIT_STATUS_OPT_DEFAULTS`, which matches git's default - * behavior. - */ - unsigned int flags; - - /** - * The `pathspec` is an array of path patterns to match (using - * fnmatch-style matching), or just an array of paths to match - * exactly if `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified - * in the flags. - */ - git_strarray pathspec; - - /** - * The `baseline` is the tree to be used for comparison to the - * working directory and index; defaults to HEAD. - */ - git_tree *baseline; - - /** - * Threshold above which similar files will be considered renames. - * This is equivalent to the -M option. Defaults to 50. - */ - uint16_t rename_threshold; -} git_status_options; - -#define GIT_STATUS_OPTIONS_VERSION 1 -#define GIT_STATUS_OPTIONS_INIT {GIT_STATUS_OPTIONS_VERSION} - -/** - * Initialize git_status_options structure - * - * Initializes a `git_status_options` with default values. Equivalent to - * creating an instance with `GIT_STATUS_OPTIONS_INIT`. - * - * @param opts The `git_status_options` struct to initialize. - * @param version The struct version; pass `GIT_STATUS_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_status_options_init( - git_status_options *opts, - unsigned int version); - -/** - * A status entry, providing the differences between the file as it exists - * in HEAD and the index, and providing the differences between the index - * and the working directory. - * - * The `status` value provides the status flags for this file. - * - * The `head_to_index` value provides detailed information about the - * differences between the file in HEAD and the file in the index. - * - * The `index_to_workdir` value provides detailed information about the - * differences between the file in the index and the file in the - * working directory. - */ -typedef struct { - git_status_t status; - git_diff_delta *head_to_index; - git_diff_delta *index_to_workdir; -} git_status_entry; - - -/** - * Gather file statuses and run a callback for each one. - * - * The callback is passed the path of the file, the status (a combination of - * the `git_status_t` values above) and the `payload` data pointer passed - * into this function. - * - * If the callback returns a non-zero value, this function will stop looping - * and return that value to caller. - * - * @param repo A repository object - * @param callback The function to call on each file - * @param payload Pointer to pass through to callback function - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_status_foreach( - git_repository *repo, - git_status_cb callback, - void *payload); - -/** - * Gather file status information and run callbacks as requested. - * - * This is an extended version of the `git_status_foreach()` API that - * allows for more granular control over which paths will be processed and - * in what order. See the `git_status_options` structure for details - * about the additional controls that this makes available. - * - * Note that if a `pathspec` is given in the `git_status_options` to filter - * the status, then the results from rename detection (if you enable it) may - * not be accurate. To do rename detection properly, this must be called - * with no `pathspec` so that all files can be considered. - * - * @param repo Repository object - * @param opts Status options structure - * @param callback The function to call on each file - * @param payload Pointer to pass through to callback function - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_status_foreach_ext( - git_repository *repo, - const git_status_options *opts, - git_status_cb callback, - void *payload); - -/** - * Get file status for a single file. - * - * This tries to get status for the filename that you give. If no files - * match that name (in either the HEAD, index, or working directory), this - * returns GIT_ENOTFOUND. - * - * If the name matches multiple files (for example, if the `path` names a - * directory or if running on a case- insensitive filesystem and yet the - * HEAD has two entries that both match the path), then this returns - * GIT_EAMBIGUOUS because it cannot give correct results. - * - * This does not do any sort of rename detection. Renames require a set of - * targets and because of the path filtering, there is not enough - * information to check renames correctly. To check file status with rename - * detection, there is no choice but to do a full `git_status_list_new` and - * scan through looking for the path that you are interested in. - * - * @param status_flags Output combination of git_status_t values for file - * @param repo A repository object - * @param path The exact path to retrieve status for relative to the - * repository working directory - * @return 0 on success, GIT_ENOTFOUND if the file is not found in the HEAD, - * index, and work tree, GIT_EAMBIGUOUS if `path` matches multiple files - * or if it refers to a folder, and -1 on other errors. - */ -GIT_EXTERN(int) git_status_file( - unsigned int *status_flags, - git_repository *repo, - const char *path); - -/** - * Gather file status information and populate the `git_status_list`. - * - * Note that if a `pathspec` is given in the `git_status_options` to filter - * the status, then the results from rename detection (if you enable it) may - * not be accurate. To do rename detection properly, this must be called - * with no `pathspec` so that all files can be considered. - * - * @param out Pointer to store the status results in - * @param repo Repository object - * @param opts Status options structure - * @return 0 on success or error code - */ -GIT_EXTERN(int) git_status_list_new( - git_status_list **out, - git_repository *repo, - const git_status_options *opts); - -/** - * Gets the count of status entries in this list. - * - * If there are no changes in status (at least according the options given - * when the status list was created), this can return 0. - * - * @param statuslist Existing status list object - * @return the number of status entries - */ -GIT_EXTERN(size_t) git_status_list_entrycount( - git_status_list *statuslist); - -/** - * Get a pointer to one of the entries in the status list. - * - * The entry is not modifiable and should not be freed. - * - * @param statuslist Existing status list object - * @param idx Position of the entry - * @return Pointer to the entry; NULL if out of bounds - */ -GIT_EXTERN(const git_status_entry *) git_status_byindex( - git_status_list *statuslist, - size_t idx); - -/** - * Free an existing status list - * - * @param statuslist Existing status list object - */ -GIT_EXTERN(void) git_status_list_free( - git_status_list *statuslist); - -/** - * Test if the ignore rules apply to a given file. - * - * This function checks the ignore rules to see if they would apply to the - * given file. This indicates if the file would be ignored regardless of - * whether the file is already in the index or committed to the repository. - * - * One way to think of this is if you were to do "git add ." on the - * directory containing the file, would it be added or not? - * - * @param ignored Boolean returning 0 if the file is not ignored, 1 if it is - * @param repo A repository object - * @param path The file to check ignores for, rooted at the repo's workdir. - * @return 0 if ignore rules could be processed for the file (regardless - * of whether it exists or not), or an error < 0 if they could not. - */ -GIT_EXTERN(int) git_status_should_ignore( - int *ignored, - git_repository *repo, - const char *path); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_status_h__ +#define INCLUDE_git_status_h__ + +#include "common.h" +#include "types.h" +#include "strarray.h" +#include "diff.h" + +/** + * @file git2/status.h + * @brief Git file status routines + * @defgroup git_status Git file status routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Status flags for a single file. + * + * A combination of these values will be returned to indicate the status of + * a file. Status compares the working directory, the index, and the + * current HEAD of the repository. The `GIT_STATUS_INDEX` set of flags + * represents the status of file in the index relative to the HEAD, and the + * `GIT_STATUS_WT` set of flags represent the status of the file in the + * working directory relative to the index. + */ +typedef enum { + GIT_STATUS_CURRENT = 0, + + GIT_STATUS_INDEX_NEW = (1u << 0), + GIT_STATUS_INDEX_MODIFIED = (1u << 1), + GIT_STATUS_INDEX_DELETED = (1u << 2), + GIT_STATUS_INDEX_RENAMED = (1u << 3), + GIT_STATUS_INDEX_TYPECHANGE = (1u << 4), + + GIT_STATUS_WT_NEW = (1u << 7), + GIT_STATUS_WT_MODIFIED = (1u << 8), + GIT_STATUS_WT_DELETED = (1u << 9), + GIT_STATUS_WT_TYPECHANGE = (1u << 10), + GIT_STATUS_WT_RENAMED = (1u << 11), + GIT_STATUS_WT_UNREADABLE = (1u << 12), + + GIT_STATUS_IGNORED = (1u << 14), + GIT_STATUS_CONFLICTED = (1u << 15) +} git_status_t; + +/** + * Function pointer to receive status on individual files + * + * `path` is the relative path to the file from the root of the repository. + * + * `status_flags` is a combination of `git_status_t` values that apply. + * + * `payload` is the value you passed to the foreach function as payload. + */ +typedef int GIT_CALLBACK(git_status_cb)( + const char *path, unsigned int status_flags, void *payload); + +/** + * Select the files on which to report status. + * + * With `git_status_foreach_ext`, this will control which changes get + * callbacks. With `git_status_list_new`, these will control which + * changes are included in the list. + */ +typedef enum { + /** + * The default. This roughly matches `git status --porcelain` regarding + * which files are included and in what order. + */ + GIT_STATUS_SHOW_INDEX_AND_WORKDIR = 0, + + /** + * Only gives status based on HEAD to index comparison, not looking at + * working directory changes. + */ + GIT_STATUS_SHOW_INDEX_ONLY = 1, + + /** + * Only gives status based on index to working directory comparison, + * not comparing the index to the HEAD. + */ + GIT_STATUS_SHOW_WORKDIR_ONLY = 2 +} git_status_show_t; + +/** + * Flags to control status callbacks + * + * Calling `git_status_foreach()` is like calling the extended version + * with: GIT_STATUS_OPT_INCLUDE_IGNORED, GIT_STATUS_OPT_INCLUDE_UNTRACKED, + * and GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS. Those options are bundled + * together as `GIT_STATUS_OPT_DEFAULTS` if you want them as a baseline. + */ +typedef enum { + /** + * Says that callbacks should be made on untracked files. + * These will only be made if the workdir files are included in the status + * "show" option. + */ + GIT_STATUS_OPT_INCLUDE_UNTRACKED = (1u << 0), + + /** + * Says that ignored files get callbacks. + * Again, these callbacks will only be made if the workdir files are + * included in the status "show" option. + */ + GIT_STATUS_OPT_INCLUDE_IGNORED = (1u << 1), + + /** + * Indicates that callback should be made even on unmodified files. + */ + GIT_STATUS_OPT_INCLUDE_UNMODIFIED = (1u << 2), + + /** + * Indicates that submodules should be skipped. + * This only applies if there are no pending typechanges to the submodule + * (either from or to another type). + */ + GIT_STATUS_OPT_EXCLUDE_SUBMODULES = (1u << 3), + + /** + * Indicates that all files in untracked directories should be included. + * Normally if an entire directory is new, then just the top-level + * directory is included (with a trailing slash on the entry name). + * This flag says to include all of the individual files in the directory + * instead. + */ + GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS = (1u << 4), + + /** + * Indicates that the given path should be treated as a literal path, + * and not as a pathspec pattern. + */ + GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH = (1u << 5), + + /** + * Indicates that the contents of ignored directories should be included + * in the status. This is like doing `git ls-files -o -i --exclude-standard` + * with core git. + */ + GIT_STATUS_OPT_RECURSE_IGNORED_DIRS = (1u << 6), + + /** + * Indicates that rename detection should be processed between the head and + * the index and enables the GIT_STATUS_INDEX_RENAMED as a possible status + * flag. + */ + GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX = (1u << 7), + + /** + * Indicates that rename detection should be run between the index and the + * working directory and enabled GIT_STATUS_WT_RENAMED as a possible status + * flag. + */ + GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR = (1u << 8), + + /** + * Overrides the native case sensitivity for the file system and forces + * the output to be in case-sensitive order. + */ + GIT_STATUS_OPT_SORT_CASE_SENSITIVELY = (1u << 9), + + /** + * Overrides the native case sensitivity for the file system and forces + * the output to be in case-insensitive order. + */ + GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY = (1u << 10), + + /** + * Iindicates that rename detection should include rewritten files. + */ + GIT_STATUS_OPT_RENAMES_FROM_REWRITES = (1u << 11), + + /** + * Bypasses the default status behavior of doing a "soft" index reload + * (i.e. reloading the index data if the file on disk has been modified + * outside libgit2). + */ + GIT_STATUS_OPT_NO_REFRESH = (1u << 12), + + /** + * Tells libgit2 to refresh the stat cache in the index for files that are + * unchanged but have out of date stat einformation in the index. + * It will result in less work being done on subsequent calls to get status. + * This is mutually exclusive with the NO_REFRESH option. + */ + GIT_STATUS_OPT_UPDATE_INDEX = (1u << 13), + + /** + * Normally files that cannot be opened or read are ignored as + * these are often transient files; this option will return + * unreadable files as `GIT_STATUS_WT_UNREADABLE`. + */ + GIT_STATUS_OPT_INCLUDE_UNREADABLE = (1u << 14), + + /** + * Unreadable files will be detected and given the status + * untracked instead of unreadable. + */ + GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 15) +} git_status_opt_t; + +#define GIT_STATUS_OPT_DEFAULTS \ + (GIT_STATUS_OPT_INCLUDE_IGNORED | \ + GIT_STATUS_OPT_INCLUDE_UNTRACKED | \ + GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS) + +/** + * Options to control how `git_status_foreach_ext()` will issue callbacks. + * + * Initialize with `GIT_STATUS_OPTIONS_INIT`. Alternatively, you can + * use `git_status_options_init`. + * + */ +typedef struct { + /** + * The struct version; pass `GIT_STATUS_OPTIONS_VERSION`. + */ + unsigned int version; + + /** + * The `show` value is one of the `git_status_show_t` constants that + * control which files to scan and in what order. The default is + * `GIT_STATUS_SHOW_INDEX_AND_WORKDIR`. + */ + git_status_show_t show; + + /** + * The `flags` value is an OR'ed combination of the + * `git_status_opt_t` values above. The default is + * `GIT_STATUS_OPT_DEFAULTS`, which matches git's default + * behavior. + */ + unsigned int flags; + + /** + * The `pathspec` is an array of path patterns to match (using + * fnmatch-style matching), or just an array of paths to match + * exactly if `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified + * in the flags. + */ + git_strarray pathspec; + + /** + * The `baseline` is the tree to be used for comparison to the + * working directory and index; defaults to HEAD. + */ + git_tree *baseline; + + /** + * Threshold above which similar files will be considered renames. + * This is equivalent to the -M option. Defaults to 50. + */ + uint16_t rename_threshold; +} git_status_options; + +#define GIT_STATUS_OPTIONS_VERSION 1 +#define GIT_STATUS_OPTIONS_INIT {GIT_STATUS_OPTIONS_VERSION} + +/** + * Initialize git_status_options structure + * + * Initializes a `git_status_options` with default values. Equivalent to + * creating an instance with `GIT_STATUS_OPTIONS_INIT`. + * + * @param opts The `git_status_options` struct to initialize. + * @param version The struct version; pass `GIT_STATUS_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_status_options_init( + git_status_options *opts, + unsigned int version); + +/** + * A status entry, providing the differences between the file as it exists + * in HEAD and the index, and providing the differences between the index + * and the working directory. + * + * The `status` value provides the status flags for this file. + * + * The `head_to_index` value provides detailed information about the + * differences between the file in HEAD and the file in the index. + * + * The `index_to_workdir` value provides detailed information about the + * differences between the file in the index and the file in the + * working directory. + */ +typedef struct { + git_status_t status; + git_diff_delta *head_to_index; + git_diff_delta *index_to_workdir; +} git_status_entry; + + +/** + * Gather file statuses and run a callback for each one. + * + * The callback is passed the path of the file, the status (a combination of + * the `git_status_t` values above) and the `payload` data pointer passed + * into this function. + * + * If the callback returns a non-zero value, this function will stop looping + * and return that value to caller. + * + * @param repo A repository object + * @param callback The function to call on each file + * @param payload Pointer to pass through to callback function + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_status_foreach( + git_repository *repo, + git_status_cb callback, + void *payload); + +/** + * Gather file status information and run callbacks as requested. + * + * This is an extended version of the `git_status_foreach()` API that + * allows for more granular control over which paths will be processed and + * in what order. See the `git_status_options` structure for details + * about the additional controls that this makes available. + * + * Note that if a `pathspec` is given in the `git_status_options` to filter + * the status, then the results from rename detection (if you enable it) may + * not be accurate. To do rename detection properly, this must be called + * with no `pathspec` so that all files can be considered. + * + * @param repo Repository object + * @param opts Status options structure + * @param callback The function to call on each file + * @param payload Pointer to pass through to callback function + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_status_foreach_ext( + git_repository *repo, + const git_status_options *opts, + git_status_cb callback, + void *payload); + +/** + * Get file status for a single file. + * + * This tries to get status for the filename that you give. If no files + * match that name (in either the HEAD, index, or working directory), this + * returns GIT_ENOTFOUND. + * + * If the name matches multiple files (for example, if the `path` names a + * directory or if running on a case- insensitive filesystem and yet the + * HEAD has two entries that both match the path), then this returns + * GIT_EAMBIGUOUS because it cannot give correct results. + * + * This does not do any sort of rename detection. Renames require a set of + * targets and because of the path filtering, there is not enough + * information to check renames correctly. To check file status with rename + * detection, there is no choice but to do a full `git_status_list_new` and + * scan through looking for the path that you are interested in. + * + * @param status_flags Output combination of git_status_t values for file + * @param repo A repository object + * @param path The exact path to retrieve status for relative to the + * repository working directory + * @return 0 on success, GIT_ENOTFOUND if the file is not found in the HEAD, + * index, and work tree, GIT_EAMBIGUOUS if `path` matches multiple files + * or if it refers to a folder, and -1 on other errors. + */ +GIT_EXTERN(int) git_status_file( + unsigned int *status_flags, + git_repository *repo, + const char *path); + +/** + * Gather file status information and populate the `git_status_list`. + * + * Note that if a `pathspec` is given in the `git_status_options` to filter + * the status, then the results from rename detection (if you enable it) may + * not be accurate. To do rename detection properly, this must be called + * with no `pathspec` so that all files can be considered. + * + * @param out Pointer to store the status results in + * @param repo Repository object + * @param opts Status options structure + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_status_list_new( + git_status_list **out, + git_repository *repo, + const git_status_options *opts); + +/** + * Gets the count of status entries in this list. + * + * If there are no changes in status (at least according the options given + * when the status list was created), this can return 0. + * + * @param statuslist Existing status list object + * @return the number of status entries + */ +GIT_EXTERN(size_t) git_status_list_entrycount( + git_status_list *statuslist); + +/** + * Get a pointer to one of the entries in the status list. + * + * The entry is not modifiable and should not be freed. + * + * @param statuslist Existing status list object + * @param idx Position of the entry + * @return Pointer to the entry; NULL if out of bounds + */ +GIT_EXTERN(const git_status_entry *) git_status_byindex( + git_status_list *statuslist, + size_t idx); + +/** + * Free an existing status list + * + * @param statuslist Existing status list object + */ +GIT_EXTERN(void) git_status_list_free( + git_status_list *statuslist); + +/** + * Test if the ignore rules apply to a given file. + * + * This function checks the ignore rules to see if they would apply to the + * given file. This indicates if the file would be ignored regardless of + * whether the file is already in the index or committed to the repository. + * + * One way to think of this is if you were to do "git add ." on the + * directory containing the file, would it be added or not? + * + * @param ignored Boolean returning 0 if the file is not ignored, 1 if it is + * @param repo A repository object + * @param path The file to check ignores for, rooted at the repo's workdir. + * @return 0 if ignore rules could be processed for the file (regardless + * of whether it exists or not), or an error < 0 if they could not. + */ +GIT_EXTERN(int) git_status_should_ignore( + int *ignored, + git_repository *repo, + const char *path); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/stdint.h b/3rdparty/libgit2/include/git2/stdint.h index 6950427..d855d7c 100644 --- a/3rdparty/libgit2/include/git2/stdint.h +++ b/3rdparty/libgit2/include/git2/stdint.h @@ -1,247 +1,247 @@ -// ISO C9x compliant stdint.h for Microsoft Visual Studio -// Based on ISO/IEC 9899:TC2 Committee draft (May 6, 2005) WG14/N1124 -// -// Copyright (c) 2006-2008 Alexander Chemeris -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions are met: -// -// 1. Redistributions of source code must retain the above copyright notice, -// this list of conditions and the following disclaimer. -// -// 2. Redistributions in binary form must reproduce the above copyright -// notice, this list of conditions and the following disclaimer in the -// documentation and/or other materials provided with the distribution. -// -// 3. The name of the author may be used to endorse or promote products -// derived from this software without specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED -// WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO -// EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; -// OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, -// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR -// OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF -// ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// -/////////////////////////////////////////////////////////////////////////////// - -#ifdef _MSC_VER // [ - -#ifndef _MSC_STDINT_H_ // [ -#define _MSC_STDINT_H_ - -#if _MSC_VER > 1000 -#pragma once -#endif - -#include - -// For Visual Studio 6 in C++ mode and for many Visual Studio versions when -// compiling for ARM we should wrap include with 'extern "C++" {}' -// or compiler give many errors like this: -// error C2733: second C linkage of overloaded function 'wmemchr' not allowed -#ifdef __cplusplus -extern "C" { -#endif -# include -#ifdef __cplusplus -} -#endif - -// Define _W64 macros to mark types changing their size, like intptr_t. -#ifndef _W64 -# if !defined(__midl) && (defined(_X86_) || defined(_M_IX86)) && _MSC_VER >= 1300 -# define _W64 __w64 -# else -# define _W64 -# endif -#endif - - -// 7.18.1 Integer types - -// 7.18.1.1 Exact-width integer types - -// Visual Studio 6 and Embedded Visual C++ 4 doesn't -// realize that, e.g. char has the same size as __int8 -// so we give up on __intX for them. -#if (_MSC_VER < 1300) - typedef signed char int8_t; - typedef signed short int16_t; - typedef signed int int32_t; - typedef unsigned char uint8_t; - typedef unsigned short uint16_t; - typedef unsigned int uint32_t; -#else - typedef signed __int8 int8_t; - typedef signed __int16 int16_t; - typedef signed __int32 int32_t; - typedef unsigned __int8 uint8_t; - typedef unsigned __int16 uint16_t; - typedef unsigned __int32 uint32_t; -#endif -typedef signed __int64 int64_t; -typedef unsigned __int64 uint64_t; - - -// 7.18.1.2 Minimum-width integer types -typedef int8_t int_least8_t; -typedef int16_t int_least16_t; -typedef int32_t int_least32_t; -typedef int64_t int_least64_t; -typedef uint8_t uint_least8_t; -typedef uint16_t uint_least16_t; -typedef uint32_t uint_least32_t; -typedef uint64_t uint_least64_t; - -// 7.18.1.3 Fastest minimum-width integer types -typedef int8_t int_fast8_t; -typedef int16_t int_fast16_t; -typedef int32_t int_fast32_t; -typedef int64_t int_fast64_t; -typedef uint8_t uint_fast8_t; -typedef uint16_t uint_fast16_t; -typedef uint32_t uint_fast32_t; -typedef uint64_t uint_fast64_t; - -// 7.18.1.4 Integer types capable of holding object pointers -#ifdef _WIN64 // [ - typedef signed __int64 intptr_t; - typedef unsigned __int64 uintptr_t; -#else // _WIN64 ][ - typedef _W64 signed int intptr_t; - typedef _W64 unsigned int uintptr_t; -#endif // _WIN64 ] - -// 7.18.1.5 Greatest-width integer types -typedef int64_t intmax_t; -typedef uint64_t uintmax_t; - - -// 7.18.2 Limits of specified-width integer types - -#if !defined(__cplusplus) || defined(__STDC_LIMIT_MACROS) // [ See footnote 220 at page 257 and footnote 221 at page 259 - -// 7.18.2.1 Limits of exact-width integer types -#define INT8_MIN ((int8_t)_I8_MIN) -#define INT8_MAX _I8_MAX -#define INT16_MIN ((int16_t)_I16_MIN) -#define INT16_MAX _I16_MAX -#define INT32_MIN ((int32_t)_I32_MIN) -#define INT32_MAX _I32_MAX -#define INT64_MIN ((int64_t)_I64_MIN) -#define INT64_MAX _I64_MAX -#define UINT8_MAX _UI8_MAX -#define UINT16_MAX _UI16_MAX -#define UINT32_MAX _UI32_MAX -#define UINT64_MAX _UI64_MAX - -// 7.18.2.2 Limits of minimum-width integer types -#define INT_LEAST8_MIN INT8_MIN -#define INT_LEAST8_MAX INT8_MAX -#define INT_LEAST16_MIN INT16_MIN -#define INT_LEAST16_MAX INT16_MAX -#define INT_LEAST32_MIN INT32_MIN -#define INT_LEAST32_MAX INT32_MAX -#define INT_LEAST64_MIN INT64_MIN -#define INT_LEAST64_MAX INT64_MAX -#define UINT_LEAST8_MAX UINT8_MAX -#define UINT_LEAST16_MAX UINT16_MAX -#define UINT_LEAST32_MAX UINT32_MAX -#define UINT_LEAST64_MAX UINT64_MAX - -// 7.18.2.3 Limits of fastest minimum-width integer types -#define INT_FAST8_MIN INT8_MIN -#define INT_FAST8_MAX INT8_MAX -#define INT_FAST16_MIN INT16_MIN -#define INT_FAST16_MAX INT16_MAX -#define INT_FAST32_MIN INT32_MIN -#define INT_FAST32_MAX INT32_MAX -#define INT_FAST64_MIN INT64_MIN -#define INT_FAST64_MAX INT64_MAX -#define UINT_FAST8_MAX UINT8_MAX -#define UINT_FAST16_MAX UINT16_MAX -#define UINT_FAST32_MAX UINT32_MAX -#define UINT_FAST64_MAX UINT64_MAX - -// 7.18.2.4 Limits of integer types capable of holding object pointers -#ifdef _WIN64 // [ -# define INTPTR_MIN INT64_MIN -# define INTPTR_MAX INT64_MAX -# define UINTPTR_MAX UINT64_MAX -#else // _WIN64 ][ -# define INTPTR_MIN INT32_MIN -# define INTPTR_MAX INT32_MAX -# define UINTPTR_MAX UINT32_MAX -#endif // _WIN64 ] - -// 7.18.2.5 Limits of greatest-width integer types -#define INTMAX_MIN INT64_MIN -#define INTMAX_MAX INT64_MAX -#define UINTMAX_MAX UINT64_MAX - -// 7.18.3 Limits of other integer types - -#ifdef _WIN64 // [ -# define PTRDIFF_MIN _I64_MIN -# define PTRDIFF_MAX _I64_MAX -#else // _WIN64 ][ -# define PTRDIFF_MIN _I32_MIN -# define PTRDIFF_MAX _I32_MAX -#endif // _WIN64 ] - -#define SIG_ATOMIC_MIN INT_MIN -#define SIG_ATOMIC_MAX INT_MAX - -#ifndef SIZE_MAX // [ -# ifdef _WIN64 // [ -# define SIZE_MAX _UI64_MAX -# else // _WIN64 ][ -# define SIZE_MAX _UI32_MAX -# endif // _WIN64 ] -#endif // SIZE_MAX ] - -// WCHAR_MIN and WCHAR_MAX are also defined in -#ifndef WCHAR_MIN // [ -# define WCHAR_MIN 0 -#endif // WCHAR_MIN ] -#ifndef WCHAR_MAX // [ -# define WCHAR_MAX _UI16_MAX -#endif // WCHAR_MAX ] - -#define WINT_MIN 0 -#define WINT_MAX _UI16_MAX - -#endif // __STDC_LIMIT_MACROS ] - - -// 7.18.4 Limits of other integer types - -#if !defined(__cplusplus) || defined(__STDC_CONSTANT_MACROS) // [ See footnote 224 at page 260 - -// 7.18.4.1 Macros for minimum-width integer constants - -#define INT8_C(val) val##i8 -#define INT16_C(val) val##i16 -#define INT32_C(val) val##i32 -#define INT64_C(val) val##i64 - -#define UINT8_C(val) val##ui8 -#define UINT16_C(val) val##ui16 -#define UINT32_C(val) val##ui32 -#define UINT64_C(val) val##ui64 - -// 7.18.4.2 Macros for greatest-width integer constants -#define INTMAX_C INT64_C -#define UINTMAX_C UINT64_C - -#endif // __STDC_CONSTANT_MACROS ] - - -#endif // _MSC_STDINT_H_ ] - +// ISO C9x compliant stdint.h for Microsoft Visual Studio +// Based on ISO/IEC 9899:TC2 Committee draft (May 6, 2005) WG14/N1124 +// +// Copyright (c) 2006-2008 Alexander Chemeris +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// 1. Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// +// 2. Redistributions in binary form must reproduce the above copyright +// notice, this list of conditions and the following disclaimer in the +// documentation and/or other materials provided with the distribution. +// +// 3. The name of the author may be used to endorse or promote products +// derived from this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED +// WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO +// EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; +// OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +// OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF +// ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +/////////////////////////////////////////////////////////////////////////////// + +#ifdef _MSC_VER // [ + +#ifndef _MSC_STDINT_H_ // [ +#define _MSC_STDINT_H_ + +#if _MSC_VER > 1000 +#pragma once +#endif + +#include + +// For Visual Studio 6 in C++ mode and for many Visual Studio versions when +// compiling for ARM we should wrap include with 'extern "C++" {}' +// or compiler give many errors like this: +// error C2733: second C linkage of overloaded function 'wmemchr' not allowed +#ifdef __cplusplus +extern "C" { +#endif +# include +#ifdef __cplusplus +} +#endif + +// Define _W64 macros to mark types changing their size, like intptr_t. +#ifndef _W64 +# if !defined(__midl) && (defined(_X86_) || defined(_M_IX86)) && _MSC_VER >= 1300 +# define _W64 __w64 +# else +# define _W64 +# endif +#endif + + +// 7.18.1 Integer types + +// 7.18.1.1 Exact-width integer types + +// Visual Studio 6 and Embedded Visual C++ 4 doesn't +// realize that, e.g. char has the same size as __int8 +// so we give up on __intX for them. +#if (_MSC_VER < 1300) + typedef signed char int8_t; + typedef signed short int16_t; + typedef signed int int32_t; + typedef unsigned char uint8_t; + typedef unsigned short uint16_t; + typedef unsigned int uint32_t; +#else + typedef signed __int8 int8_t; + typedef signed __int16 int16_t; + typedef signed __int32 int32_t; + typedef unsigned __int8 uint8_t; + typedef unsigned __int16 uint16_t; + typedef unsigned __int32 uint32_t; +#endif +typedef signed __int64 int64_t; +typedef unsigned __int64 uint64_t; + + +// 7.18.1.2 Minimum-width integer types +typedef int8_t int_least8_t; +typedef int16_t int_least16_t; +typedef int32_t int_least32_t; +typedef int64_t int_least64_t; +typedef uint8_t uint_least8_t; +typedef uint16_t uint_least16_t; +typedef uint32_t uint_least32_t; +typedef uint64_t uint_least64_t; + +// 7.18.1.3 Fastest minimum-width integer types +typedef int8_t int_fast8_t; +typedef int16_t int_fast16_t; +typedef int32_t int_fast32_t; +typedef int64_t int_fast64_t; +typedef uint8_t uint_fast8_t; +typedef uint16_t uint_fast16_t; +typedef uint32_t uint_fast32_t; +typedef uint64_t uint_fast64_t; + +// 7.18.1.4 Integer types capable of holding object pointers +#ifdef _WIN64 // [ + typedef signed __int64 intptr_t; + typedef unsigned __int64 uintptr_t; +#else // _WIN64 ][ + typedef _W64 signed int intptr_t; + typedef _W64 unsigned int uintptr_t; +#endif // _WIN64 ] + +// 7.18.1.5 Greatest-width integer types +typedef int64_t intmax_t; +typedef uint64_t uintmax_t; + + +// 7.18.2 Limits of specified-width integer types + +#if !defined(__cplusplus) || defined(__STDC_LIMIT_MACROS) // [ See footnote 220 at page 257 and footnote 221 at page 259 + +// 7.18.2.1 Limits of exact-width integer types +#define INT8_MIN ((int8_t)_I8_MIN) +#define INT8_MAX _I8_MAX +#define INT16_MIN ((int16_t)_I16_MIN) +#define INT16_MAX _I16_MAX +#define INT32_MIN ((int32_t)_I32_MIN) +#define INT32_MAX _I32_MAX +#define INT64_MIN ((int64_t)_I64_MIN) +#define INT64_MAX _I64_MAX +#define UINT8_MAX _UI8_MAX +#define UINT16_MAX _UI16_MAX +#define UINT32_MAX _UI32_MAX +#define UINT64_MAX _UI64_MAX + +// 7.18.2.2 Limits of minimum-width integer types +#define INT_LEAST8_MIN INT8_MIN +#define INT_LEAST8_MAX INT8_MAX +#define INT_LEAST16_MIN INT16_MIN +#define INT_LEAST16_MAX INT16_MAX +#define INT_LEAST32_MIN INT32_MIN +#define INT_LEAST32_MAX INT32_MAX +#define INT_LEAST64_MIN INT64_MIN +#define INT_LEAST64_MAX INT64_MAX +#define UINT_LEAST8_MAX UINT8_MAX +#define UINT_LEAST16_MAX UINT16_MAX +#define UINT_LEAST32_MAX UINT32_MAX +#define UINT_LEAST64_MAX UINT64_MAX + +// 7.18.2.3 Limits of fastest minimum-width integer types +#define INT_FAST8_MIN INT8_MIN +#define INT_FAST8_MAX INT8_MAX +#define INT_FAST16_MIN INT16_MIN +#define INT_FAST16_MAX INT16_MAX +#define INT_FAST32_MIN INT32_MIN +#define INT_FAST32_MAX INT32_MAX +#define INT_FAST64_MIN INT64_MIN +#define INT_FAST64_MAX INT64_MAX +#define UINT_FAST8_MAX UINT8_MAX +#define UINT_FAST16_MAX UINT16_MAX +#define UINT_FAST32_MAX UINT32_MAX +#define UINT_FAST64_MAX UINT64_MAX + +// 7.18.2.4 Limits of integer types capable of holding object pointers +#ifdef _WIN64 // [ +# define INTPTR_MIN INT64_MIN +# define INTPTR_MAX INT64_MAX +# define UINTPTR_MAX UINT64_MAX +#else // _WIN64 ][ +# define INTPTR_MIN INT32_MIN +# define INTPTR_MAX INT32_MAX +# define UINTPTR_MAX UINT32_MAX +#endif // _WIN64 ] + +// 7.18.2.5 Limits of greatest-width integer types +#define INTMAX_MIN INT64_MIN +#define INTMAX_MAX INT64_MAX +#define UINTMAX_MAX UINT64_MAX + +// 7.18.3 Limits of other integer types + +#ifdef _WIN64 // [ +# define PTRDIFF_MIN _I64_MIN +# define PTRDIFF_MAX _I64_MAX +#else // _WIN64 ][ +# define PTRDIFF_MIN _I32_MIN +# define PTRDIFF_MAX _I32_MAX +#endif // _WIN64 ] + +#define SIG_ATOMIC_MIN INT_MIN +#define SIG_ATOMIC_MAX INT_MAX + +#ifndef SIZE_MAX // [ +# ifdef _WIN64 // [ +# define SIZE_MAX _UI64_MAX +# else // _WIN64 ][ +# define SIZE_MAX _UI32_MAX +# endif // _WIN64 ] +#endif // SIZE_MAX ] + +// WCHAR_MIN and WCHAR_MAX are also defined in +#ifndef WCHAR_MIN // [ +# define WCHAR_MIN 0 +#endif // WCHAR_MIN ] +#ifndef WCHAR_MAX // [ +# define WCHAR_MAX _UI16_MAX +#endif // WCHAR_MAX ] + +#define WINT_MIN 0 +#define WINT_MAX _UI16_MAX + +#endif // __STDC_LIMIT_MACROS ] + + +// 7.18.4 Limits of other integer types + +#if !defined(__cplusplus) || defined(__STDC_CONSTANT_MACROS) // [ See footnote 224 at page 260 + +// 7.18.4.1 Macros for minimum-width integer constants + +#define INT8_C(val) val##i8 +#define INT16_C(val) val##i16 +#define INT32_C(val) val##i32 +#define INT64_C(val) val##i64 + +#define UINT8_C(val) val##ui8 +#define UINT16_C(val) val##ui16 +#define UINT32_C(val) val##ui32 +#define UINT64_C(val) val##ui64 + +// 7.18.4.2 Macros for greatest-width integer constants +#define INTMAX_C INT64_C +#define UINTMAX_C UINT64_C + +#endif // __STDC_CONSTANT_MACROS ] + + +#endif // _MSC_STDINT_H_ ] + #endif // _MSC_VER ] \ No newline at end of file diff --git a/3rdparty/libgit2/include/git2/strarray.h b/3rdparty/libgit2/include/git2/strarray.h index 03d93f8..6e30de3 100644 --- a/3rdparty/libgit2/include/git2/strarray.h +++ b/3rdparty/libgit2/include/git2/strarray.h @@ -1,43 +1,43 @@ -/* - * 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_strarray_h__ -#define INCLUDE_git_strarray_h__ - -#include "common.h" - -/** - * @file git2/strarray.h - * @brief Git string array routines - * @defgroup git_strarray Git string array routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** Array of strings */ -typedef struct git_strarray { - char **strings; - size_t count; -} git_strarray; - -/** - * Free the strings contained in a string array. This method should - * be called on `git_strarray` objects that were provided by the - * library. Not doing so, will result in a memory leak. - * - * This does not free the `git_strarray` itself, since the library will - * never allocate that object directly itself. - * - * @param array The git_strarray that contains strings to free - */ -GIT_EXTERN(void) git_strarray_dispose(git_strarray *array); - -/** @} */ -GIT_END_DECL - -#endif - +/* + * 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_strarray_h__ +#define INCLUDE_git_strarray_h__ + +#include "common.h" + +/** + * @file git2/strarray.h + * @brief Git string array routines + * @defgroup git_strarray Git string array routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** Array of strings */ +typedef struct git_strarray { + char **strings; + size_t count; +} git_strarray; + +/** + * Free the strings contained in a string array. This method should + * be called on `git_strarray` objects that were provided by the + * library. Not doing so, will result in a memory leak. + * + * This does not free the `git_strarray` itself, since the library will + * never allocate that object directly itself. + * + * @param array The git_strarray that contains strings to free + */ +GIT_EXTERN(void) git_strarray_dispose(git_strarray *array); + +/** @} */ +GIT_END_DECL + +#endif + diff --git a/3rdparty/libgit2/include/git2/submodule.h b/3rdparty/libgit2/include/git2/submodule.h index 2082966..beabfe7 100644 --- a/3rdparty/libgit2/include/git2/submodule.h +++ b/3rdparty/libgit2/include/git2/submodule.h @@ -1,668 +1,668 @@ -/* - * 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_submodule_h__ -#define INCLUDE_git_submodule_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "remote.h" -#include "checkout.h" - -/** - * @file git2/submodule.h - * @brief Git submodule management utilities - * - * Submodule support in libgit2 builds a list of known submodules and keeps - * it in the repository. The list is built from the .gitmodules file, the - * .git/config file, the index, and the HEAD tree. Items in the working - * directory that look like submodules (i.e. a git repo) but are not - * mentioned in those places won't be tracked. - * - * @defgroup git_submodule Git submodule management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Return codes for submodule status. - * - * A combination of these flags will be returned to describe the status of a - * submodule. Depending on the "ignore" property of the submodule, some of - * the flags may never be returned because they indicate changes that are - * supposed to be ignored. - * - * Submodule info is contained in 4 places: the HEAD tree, the index, config - * files (both .git/config and .gitmodules), and the working directory. Any - * or all of those places might be missing information about the submodule - * depending on what state the repo is in. We consider all four places to - * build the combination of status flags. - * - * There are four values that are not really status, but give basic info - * about what sources of submodule data are available. These will be - * returned even if ignore is set to "ALL". - * - * * IN_HEAD - superproject head contains submodule - * * IN_INDEX - superproject index contains submodule - * * IN_CONFIG - superproject gitmodules has submodule - * * IN_WD - superproject workdir has submodule - * - * The following values will be returned so long as ignore is not "ALL". - * - * * INDEX_ADDED - in index, not in head - * * INDEX_DELETED - in head, not in index - * * INDEX_MODIFIED - index and head don't match - * * WD_UNINITIALIZED - workdir contains empty directory - * * WD_ADDED - in workdir, not index - * * WD_DELETED - in index, not workdir - * * WD_MODIFIED - index and workdir head don't match - * - * The following can only be returned if ignore is "NONE" or "UNTRACKED". - * - * * WD_INDEX_MODIFIED - submodule workdir index is dirty - * * WD_WD_MODIFIED - submodule workdir has modified files - * - * Lastly, the following will only be returned for ignore "NONE". - * - * * WD_UNTRACKED - wd contains untracked files - */ -typedef enum { - GIT_SUBMODULE_STATUS_IN_HEAD = (1u << 0), - GIT_SUBMODULE_STATUS_IN_INDEX = (1u << 1), - GIT_SUBMODULE_STATUS_IN_CONFIG = (1u << 2), - GIT_SUBMODULE_STATUS_IN_WD = (1u << 3), - GIT_SUBMODULE_STATUS_INDEX_ADDED = (1u << 4), - GIT_SUBMODULE_STATUS_INDEX_DELETED = (1u << 5), - GIT_SUBMODULE_STATUS_INDEX_MODIFIED = (1u << 6), - GIT_SUBMODULE_STATUS_WD_UNINITIALIZED = (1u << 7), - GIT_SUBMODULE_STATUS_WD_ADDED = (1u << 8), - GIT_SUBMODULE_STATUS_WD_DELETED = (1u << 9), - GIT_SUBMODULE_STATUS_WD_MODIFIED = (1u << 10), - GIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED = (1u << 11), - GIT_SUBMODULE_STATUS_WD_WD_MODIFIED = (1u << 12), - GIT_SUBMODULE_STATUS_WD_UNTRACKED = (1u << 13) -} git_submodule_status_t; - -#define GIT_SUBMODULE_STATUS__IN_FLAGS 0x000Fu -#define GIT_SUBMODULE_STATUS__INDEX_FLAGS 0x0070u -#define GIT_SUBMODULE_STATUS__WD_FLAGS 0x3F80u - -#define GIT_SUBMODULE_STATUS_IS_UNMODIFIED(S) \ - (((S) & ~GIT_SUBMODULE_STATUS__IN_FLAGS) == 0) - -#define GIT_SUBMODULE_STATUS_IS_INDEX_UNMODIFIED(S) \ - (((S) & GIT_SUBMODULE_STATUS__INDEX_FLAGS) == 0) - -#define GIT_SUBMODULE_STATUS_IS_WD_UNMODIFIED(S) \ - (((S) & (GIT_SUBMODULE_STATUS__WD_FLAGS & \ - ~GIT_SUBMODULE_STATUS_WD_UNINITIALIZED)) == 0) - -#define GIT_SUBMODULE_STATUS_IS_WD_DIRTY(S) \ - (((S) & (GIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED | \ - GIT_SUBMODULE_STATUS_WD_WD_MODIFIED | \ - GIT_SUBMODULE_STATUS_WD_UNTRACKED)) != 0) - -/** - * Function pointer to receive each submodule - * - * @param sm git_submodule currently being visited - * @param name name of the submodule - * @param payload value you passed to the foreach function as payload - * @return 0 on success or error code - */ -typedef int GIT_CALLBACK(git_submodule_cb)( - git_submodule *sm, const char *name, void *payload); - -/** - * Submodule update options structure - * - * Initialize with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. Alternatively, you can - * use `git_submodule_update_options_init`. - * - */ -typedef struct git_submodule_update_options { - unsigned int version; - - /** - * These options are passed to the checkout step. To disable - * checkout, set the `checkout_strategy` to - * `GIT_CHECKOUT_NONE`. Generally you will want the use - * GIT_CHECKOUT_SAFE to update files in the working - * directory. - */ - git_checkout_options checkout_opts; - - /** - * Options which control the fetch, including callbacks. - * - * The callbacks to use for reporting fetch progress, and for acquiring - * credentials in the event they are needed. - */ - git_fetch_options fetch_opts; - - /** - * Allow fetching from the submodule's default remote if the target - * commit isn't found. Enabled by default. - */ - int allow_fetch; -} git_submodule_update_options; - -#define GIT_SUBMODULE_UPDATE_OPTIONS_VERSION 1 -#define GIT_SUBMODULE_UPDATE_OPTIONS_INIT \ - { GIT_SUBMODULE_UPDATE_OPTIONS_VERSION, \ - { GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE }, \ - GIT_FETCH_OPTIONS_INIT, 1 } - -/** - * Initialize git_submodule_update_options structure - * - * Initializes a `git_submodule_update_options` with default values. Equivalent to - * creating an instance with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. - * - * @param opts The `git_submodule_update_options` struct to initialize. - * @param version The struct version; pass `GIT_SUBMODULE_UPDATE_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_submodule_update_options_init( - git_submodule_update_options *opts, unsigned int version); - -/** - * Update a submodule. This will clone a missing submodule and - * checkout the subrepository to the commit specified in the index of - * the containing repository. If the submodule repository doesn't contain - * the target commit (e.g. because fetchRecurseSubmodules isn't set), then - * the submodule is fetched using the fetch options supplied in options. - * - * @param submodule Submodule object - * @param init If the submodule is not initialized, setting this flag to true - * will initialize the submodule before updating. Otherwise, this will - * return an error if attempting to update an uninitialized repository. - * but setting this to true forces them to be updated. - * @param options configuration options for the update. If NULL, the - * function works as though GIT_SUBMODULE_UPDATE_OPTIONS_INIT was passed. - * @return 0 on success, any non-zero return value from a callback - * function, or a negative value to indicate an error (use - * `git_error_last` for a detailed error message). - */ -GIT_EXTERN(int) git_submodule_update(git_submodule *submodule, int init, git_submodule_update_options *options); - -/** - * Lookup submodule information by name or path. - * - * Given either the submodule name or path (they are usually the same), this - * returns a structure describing the submodule. - * - * There are two expected error scenarios: - * - * - The submodule is not mentioned in the HEAD, the index, and the config, - * but does "exist" in the working directory (i.e. there is a subdirectory - * that appears to be a Git repository). In this case, this function - * returns GIT_EEXISTS to indicate a sub-repository exists but not in a - * state where a git_submodule can be instantiated. - * - The submodule is not mentioned in the HEAD, index, or config and the - * working directory doesn't contain a value git repo at that path. - * There may or may not be anything else at that path, but nothing that - * looks like a submodule. In this case, this returns GIT_ENOTFOUND. - * - * You must call `git_submodule_free` when done with the submodule. - * - * @param out Output ptr to submodule; pass NULL to just get return code - * @param repo The parent repository - * @param name The name of or path to the submodule; trailing slashes okay - * @return 0 on success, GIT_ENOTFOUND if submodule does not exist, - * GIT_EEXISTS if a repository is found in working directory only, - * -1 on other errors. - */ -GIT_EXTERN(int) git_submodule_lookup( - git_submodule **out, - git_repository *repo, - const char *name); - -/** - * Create an in-memory copy of a submodule. The copy must be explicitly - * free'd or it will leak. - * - * @param out Pointer to store the copy of the submodule. - * @param source Original submodule to copy. - * @return 0 - */ -GIT_EXTERN(int) git_submodule_dup(git_submodule **out, git_submodule *source); - -/** - * Release a submodule - * - * @param submodule Submodule object - */ -GIT_EXTERN(void) git_submodule_free(git_submodule *submodule); - -/** - * Iterate over all tracked submodules of a repository. - * - * See the note on `git_submodule` above. This iterates over the tracked - * submodules as described therein. - * - * If you are concerned about items in the working directory that look like - * submodules but are not tracked, the diff API will generate a diff record - * for workdir items that look like submodules but are not tracked, showing - * them as added in the workdir. Also, the status API will treat the entire - * subdirectory of a contained git repo as a single GIT_STATUS_WT_NEW item. - * - * @param repo The repository - * @param callback Function to be called with the name of each submodule. - * Return a non-zero value to terminate the iteration. - * @param payload Extra data to pass to callback - * @return 0 on success, -1 on error, or non-zero return value of callback - */ -GIT_EXTERN(int) git_submodule_foreach( - git_repository *repo, - git_submodule_cb callback, - void *payload); - -/** - * Set up a new git submodule for checkout. - * - * This does "git submodule add" up to the fetch and checkout of the - * submodule contents. It preps a new submodule, creates an entry in - * .gitmodules and creates an empty initialized repository either at the - * given path in the working directory or in .git/modules with a gitlink - * from the working directory to the new repo. - * - * To fully emulate "git submodule add" call this function, then open the - * submodule repo and perform the clone step as needed (if you don't need - * anything custom see `git_submodule_add_clone()`). Lastly, call - * `git_submodule_add_finalize()` to wrap up adding the new submodule and - * .gitmodules to the index to be ready to commit. - * - * You must call `git_submodule_free` on the submodule object when done. - * - * @param out The newly created submodule ready to open for clone - * @param repo The repository in which you want to create the submodule - * @param url URL for the submodule's remote - * @param path Path at which the submodule should be created - * @param use_gitlink Should workdir contain a gitlink to the repo in - * .git/modules vs. repo directly in workdir. - * @return 0 on success, GIT_EEXISTS if submodule already exists, - * -1 on other errors. - */ -GIT_EXTERN(int) git_submodule_add_setup( - git_submodule **out, - git_repository *repo, - const char *url, - const char *path, - int use_gitlink); - -/** - * Perform the clone step for a newly created submodule. - * - * This performs the necessary `git_clone` to setup a newly-created submodule. - * - * @param out The newly created repository object. Optional. - * @param submodule The submodule currently waiting for its clone. - * @param opts The options to use. - * - * @return 0 on success, -1 on other errors (see git_clone). - */ -GIT_EXTERN(int) git_submodule_clone( - git_repository **out, - git_submodule *submodule, - const git_submodule_update_options *opts); - -/** - * Resolve the setup of a new git submodule. - * - * This should be called on a submodule once you have called add setup - * and done the clone of the submodule. This adds the .gitmodules file - * and the newly cloned submodule to the index to be ready to be committed - * (but doesn't actually do the commit). - * - * @param submodule The submodule to finish adding. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_submodule_add_finalize(git_submodule *submodule); - -/** - * Add current submodule HEAD commit to index of superproject. - * - * @param submodule The submodule to add to the index - * @param write_index Boolean if this should immediately write the index - * file. If you pass this as false, you will have to get the - * git_index and explicitly call `git_index_write()` on it to - * save the change. - * @return 0 on success, <0 on failure - */ -GIT_EXTERN(int) git_submodule_add_to_index( - git_submodule *submodule, - int write_index); - -/** - * Get the containing repository for a submodule. - * - * This returns a pointer to the repository that contains the submodule. - * This is a just a reference to the repository that was passed to the - * original `git_submodule_lookup()` call, so if that repository has been - * freed, then this may be a dangling reference. - * - * @param submodule Pointer to submodule object - * @return Pointer to `git_repository` - */ -GIT_EXTERN(git_repository *) git_submodule_owner(git_submodule *submodule); - -/** - * Get the name of submodule. - * - * @param submodule Pointer to submodule object - * @return Pointer to the submodule name - */ -GIT_EXTERN(const char *) git_submodule_name(git_submodule *submodule); - -/** - * Get the path to the submodule. - * - * The path is almost always the same as the submodule name, but the - * two are actually not required to match. - * - * @param submodule Pointer to submodule object - * @return Pointer to the submodule path - */ -GIT_EXTERN(const char *) git_submodule_path(git_submodule *submodule); - -/** - * Get the URL for the submodule. - * - * @param submodule Pointer to submodule object - * @return Pointer to the submodule url - */ -GIT_EXTERN(const char *) git_submodule_url(git_submodule *submodule); - -/** - * Resolve a submodule url relative to the given repository. - * - * @param out buffer to store the absolute submodule url in - * @param repo Pointer to repository object - * @param url Relative url - * @return 0 or an error code - */ -GIT_EXTERN(int) git_submodule_resolve_url(git_buf *out, git_repository *repo, const char *url); - -/** -* Get the branch for the submodule. -* -* @param submodule Pointer to submodule object -* @return Pointer to the submodule branch -*/ -GIT_EXTERN(const char *) git_submodule_branch(git_submodule *submodule); - -/** - * Set the branch for the submodule in the configuration - * - * After calling this, you may wish to call `git_submodule_sync()` to - * write the changes to the checked out submodule repository. - * - * @param repo the repository to affect - * @param name the name of the submodule to configure - * @param branch Branch that should be used for the submodule - * @return 0 on success, <0 on failure - */ -GIT_EXTERN(int) git_submodule_set_branch(git_repository *repo, const char *name, const char *branch); - -/** - * Set the URL for the submodule in the configuration - * - * - * After calling this, you may wish to call `git_submodule_sync()` to - * write the changes to the checked out submodule repository. - * - * @param repo the repository to affect - * @param name the name of the submodule to configure - * @param url URL that should be used for the submodule - * @return 0 on success, <0 on failure - */ -GIT_EXTERN(int) git_submodule_set_url(git_repository *repo, const char *name, const char *url); - -/** - * Get the OID for the submodule in the index. - * - * @param submodule Pointer to submodule object - * @return Pointer to git_oid or NULL if submodule is not in index. - */ -GIT_EXTERN(const git_oid *) git_submodule_index_id(git_submodule *submodule); - -/** - * Get the OID for the submodule in the current HEAD tree. - * - * @param submodule Pointer to submodule object - * @return Pointer to git_oid or NULL if submodule is not in the HEAD. - */ -GIT_EXTERN(const git_oid *) git_submodule_head_id(git_submodule *submodule); - -/** - * Get the OID for the submodule in the current working directory. - * - * This returns the OID that corresponds to looking up 'HEAD' in the checked - * out submodule. If there are pending changes in the index or anything - * else, this won't notice that. You should call `git_submodule_status()` - * for a more complete picture about the state of the working directory. - * - * @param submodule Pointer to submodule object - * @return Pointer to git_oid or NULL if submodule is not checked out. - */ -GIT_EXTERN(const git_oid *) git_submodule_wd_id(git_submodule *submodule); - -/** - * Get the ignore rule that will be used for the submodule. - * - * These values control the behavior of `git_submodule_status()` for this - * submodule. There are four ignore values: - * - * - **GIT_SUBMODULE_IGNORE_NONE** will consider any change to the contents - * of the submodule from a clean checkout to be dirty, including the - * addition of untracked files. This is the default if unspecified. - * - **GIT_SUBMODULE_IGNORE_UNTRACKED** examines the contents of the - * working tree (i.e. call `git_status_foreach()` on the submodule) but - * UNTRACKED files will not count as making the submodule dirty. - * - **GIT_SUBMODULE_IGNORE_DIRTY** means to only check if the HEAD of the - * submodule has moved for status. This is fast since it does not need to - * scan the working tree of the submodule at all. - * - **GIT_SUBMODULE_IGNORE_ALL** means not to open the submodule repo. - * The working directory will be consider clean so long as there is a - * checked out version present. - * - * @param submodule The submodule to check - * @return The current git_submodule_ignore_t valyue what will be used for - * this submodule. - */ -GIT_EXTERN(git_submodule_ignore_t) git_submodule_ignore( - git_submodule *submodule); - -/** - * Set the ignore rule for the submodule in the configuration - * - * This does not affect any currently-loaded instances. - * - * @param repo the repository to affect - * @param name the name of the submdule - * @param ignore The new value for the ignore rule - * @return 0 or an error code - */ -GIT_EXTERN(int) git_submodule_set_ignore( - git_repository *repo, - const char *name, - git_submodule_ignore_t ignore); - -/** - * Get the update rule that will be used for the submodule. - * - * This value controls the behavior of the `git submodule update` command. - * There are four useful values documented with `git_submodule_update_t`. - * - * @param submodule The submodule to check - * @return The current git_submodule_update_t value that will be used - * for this submodule. - */ -GIT_EXTERN(git_submodule_update_t) git_submodule_update_strategy( - git_submodule *submodule); - -/** - * Set the update rule for the submodule in the configuration - * - * This setting won't affect any existing instances. - * - * @param repo the repository to affect - * @param name the name of the submodule to configure - * @param update The new value to use - * @return 0 or an error code - */ -GIT_EXTERN(int) git_submodule_set_update( - git_repository *repo, - const char *name, - git_submodule_update_t update); - -/** - * Read the fetchRecurseSubmodules rule for a submodule. - * - * This accesses the submodule..fetchRecurseSubmodules value for - * the submodule that controls fetching behavior for the submodule. - * - * Note that at this time, libgit2 does not honor this setting and the - * fetch functionality current ignores submodules. - * - * @return 0 if fetchRecurseSubmodules is false, 1 if true - */ -GIT_EXTERN(git_submodule_recurse_t) git_submodule_fetch_recurse_submodules( - git_submodule *submodule); - -/** - * Set the fetchRecurseSubmodules rule for a submodule in the configuration - * - * This setting won't affect any existing instances. - * - * @param repo the repository to affect - * @param name the submodule to configure - * @param fetch_recurse_submodules Boolean value - * @return old value for fetchRecurseSubmodules - */ -GIT_EXTERN(int) git_submodule_set_fetch_recurse_submodules( - git_repository *repo, - const char *name, - git_submodule_recurse_t fetch_recurse_submodules); - -/** - * Copy submodule info into ".git/config" file. - * - * Just like "git submodule init", this copies information about the - * submodule into ".git/config". You can use the accessor functions - * above to alter the in-memory git_submodule object and control what - * is written to the config, overriding what is in .gitmodules. - * - * @param submodule The submodule to write into the superproject config - * @param overwrite By default, existing entries will not be overwritten, - * but setting this to true forces them to be updated. - * @return 0 on success, <0 on failure. - */ -GIT_EXTERN(int) git_submodule_init(git_submodule *submodule, int overwrite); - -/** - * Set up the subrepository for a submodule in preparation for clone. - * - * This function can be called to init and set up a submodule - * repository from a submodule in preparation to clone it from - * its remote. - * - * @param out Output pointer to the created git repository. - * @param sm The submodule to create a new subrepository from. - * @param use_gitlink Should the workdir contain a gitlink to - * the repo in .git/modules vs. repo directly in workdir. - * @return 0 on success, <0 on failure. - */ -GIT_EXTERN(int) git_submodule_repo_init( - git_repository **out, - const git_submodule *sm, - int use_gitlink); - -/** - * Copy submodule remote info into submodule repo. - * - * This copies the information about the submodules URL into the checked out - * submodule config, acting like "git submodule sync". This is useful if - * you have altered the URL for the submodule (or it has been altered by a - * fetch of upstream changes) and you need to update your local repo. - * - * @param submodule The submodule to copy. - * @return 0 or an error code. - */ -GIT_EXTERN(int) git_submodule_sync(git_submodule *submodule); - -/** - * Open the repository for a submodule. - * - * This is a newly opened repository object. The caller is responsible for - * calling `git_repository_free()` on it when done. Multiple calls to this - * function will return distinct `git_repository` objects. This will only - * work if the submodule is checked out into the working directory. - * - * @param repo Pointer to the submodule repo which was opened - * @param submodule Submodule to be opened - * @return 0 on success, <0 if submodule repo could not be opened. - */ -GIT_EXTERN(int) git_submodule_open( - git_repository **repo, - git_submodule *submodule); - -/** - * Reread submodule info from config, index, and HEAD. - * - * Call this to reread cached submodule information for this submodule if - * you have reason to believe that it has changed. - * - * @param submodule The submodule to reload - * @param force Force reload even if the data doesn't seem out of date - * @return 0 on success, <0 on error - */ -GIT_EXTERN(int) git_submodule_reload(git_submodule *submodule, int force); - -/** - * Get the status for a submodule. - * - * This looks at a submodule and tries to determine the status. It - * will return a combination of the `GIT_SUBMODULE_STATUS` values above. - * How deeply it examines the working directory to do this will depend - * on the `git_submodule_ignore_t` value for the submodule. - * - * @param status Combination of `GIT_SUBMODULE_STATUS` flags - * @param repo the repository in which to look - * @param name name of the submodule - * @param ignore the ignore rules to follow - * @return 0 on success, <0 on error - */ -GIT_EXTERN(int) git_submodule_status( - unsigned int *status, - git_repository *repo, - const char *name, - git_submodule_ignore_t ignore); - -/** - * Get the locations of submodule information. - * - * This is a bit like a very lightweight version of `git_submodule_status`. - * It just returns a made of the first four submodule status values (i.e. - * the ones like GIT_SUBMODULE_STATUS_IN_HEAD, etc) that tell you where the - * submodule data comes from (i.e. the HEAD commit, gitmodules file, etc.). - * This can be useful if you want to know if the submodule is present in the - * working directory at this point in time, etc. - * - * @param location_status Combination of first four `GIT_SUBMODULE_STATUS` flags - * @param submodule Submodule for which to get status - * @return 0 on success, <0 on error - */ -GIT_EXTERN(int) git_submodule_location( - unsigned int *location_status, - git_submodule *submodule); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_submodule_h__ +#define INCLUDE_git_submodule_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "remote.h" +#include "checkout.h" + +/** + * @file git2/submodule.h + * @brief Git submodule management utilities + * + * Submodule support in libgit2 builds a list of known submodules and keeps + * it in the repository. The list is built from the .gitmodules file, the + * .git/config file, the index, and the HEAD tree. Items in the working + * directory that look like submodules (i.e. a git repo) but are not + * mentioned in those places won't be tracked. + * + * @defgroup git_submodule Git submodule management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Return codes for submodule status. + * + * A combination of these flags will be returned to describe the status of a + * submodule. Depending on the "ignore" property of the submodule, some of + * the flags may never be returned because they indicate changes that are + * supposed to be ignored. + * + * Submodule info is contained in 4 places: the HEAD tree, the index, config + * files (both .git/config and .gitmodules), and the working directory. Any + * or all of those places might be missing information about the submodule + * depending on what state the repo is in. We consider all four places to + * build the combination of status flags. + * + * There are four values that are not really status, but give basic info + * about what sources of submodule data are available. These will be + * returned even if ignore is set to "ALL". + * + * * IN_HEAD - superproject head contains submodule + * * IN_INDEX - superproject index contains submodule + * * IN_CONFIG - superproject gitmodules has submodule + * * IN_WD - superproject workdir has submodule + * + * The following values will be returned so long as ignore is not "ALL". + * + * * INDEX_ADDED - in index, not in head + * * INDEX_DELETED - in head, not in index + * * INDEX_MODIFIED - index and head don't match + * * WD_UNINITIALIZED - workdir contains empty directory + * * WD_ADDED - in workdir, not index + * * WD_DELETED - in index, not workdir + * * WD_MODIFIED - index and workdir head don't match + * + * The following can only be returned if ignore is "NONE" or "UNTRACKED". + * + * * WD_INDEX_MODIFIED - submodule workdir index is dirty + * * WD_WD_MODIFIED - submodule workdir has modified files + * + * Lastly, the following will only be returned for ignore "NONE". + * + * * WD_UNTRACKED - wd contains untracked files + */ +typedef enum { + GIT_SUBMODULE_STATUS_IN_HEAD = (1u << 0), + GIT_SUBMODULE_STATUS_IN_INDEX = (1u << 1), + GIT_SUBMODULE_STATUS_IN_CONFIG = (1u << 2), + GIT_SUBMODULE_STATUS_IN_WD = (1u << 3), + GIT_SUBMODULE_STATUS_INDEX_ADDED = (1u << 4), + GIT_SUBMODULE_STATUS_INDEX_DELETED = (1u << 5), + GIT_SUBMODULE_STATUS_INDEX_MODIFIED = (1u << 6), + GIT_SUBMODULE_STATUS_WD_UNINITIALIZED = (1u << 7), + GIT_SUBMODULE_STATUS_WD_ADDED = (1u << 8), + GIT_SUBMODULE_STATUS_WD_DELETED = (1u << 9), + GIT_SUBMODULE_STATUS_WD_MODIFIED = (1u << 10), + GIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED = (1u << 11), + GIT_SUBMODULE_STATUS_WD_WD_MODIFIED = (1u << 12), + GIT_SUBMODULE_STATUS_WD_UNTRACKED = (1u << 13) +} git_submodule_status_t; + +#define GIT_SUBMODULE_STATUS__IN_FLAGS 0x000Fu +#define GIT_SUBMODULE_STATUS__INDEX_FLAGS 0x0070u +#define GIT_SUBMODULE_STATUS__WD_FLAGS 0x3F80u + +#define GIT_SUBMODULE_STATUS_IS_UNMODIFIED(S) \ + (((S) & ~GIT_SUBMODULE_STATUS__IN_FLAGS) == 0) + +#define GIT_SUBMODULE_STATUS_IS_INDEX_UNMODIFIED(S) \ + (((S) & GIT_SUBMODULE_STATUS__INDEX_FLAGS) == 0) + +#define GIT_SUBMODULE_STATUS_IS_WD_UNMODIFIED(S) \ + (((S) & (GIT_SUBMODULE_STATUS__WD_FLAGS & \ + ~GIT_SUBMODULE_STATUS_WD_UNINITIALIZED)) == 0) + +#define GIT_SUBMODULE_STATUS_IS_WD_DIRTY(S) \ + (((S) & (GIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED | \ + GIT_SUBMODULE_STATUS_WD_WD_MODIFIED | \ + GIT_SUBMODULE_STATUS_WD_UNTRACKED)) != 0) + +/** + * Function pointer to receive each submodule + * + * @param sm git_submodule currently being visited + * @param name name of the submodule + * @param payload value you passed to the foreach function as payload + * @return 0 on success or error code + */ +typedef int GIT_CALLBACK(git_submodule_cb)( + git_submodule *sm, const char *name, void *payload); + +/** + * Submodule update options structure + * + * Initialize with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. Alternatively, you can + * use `git_submodule_update_options_init`. + * + */ +typedef struct git_submodule_update_options { + unsigned int version; + + /** + * These options are passed to the checkout step. To disable + * checkout, set the `checkout_strategy` to + * `GIT_CHECKOUT_NONE`. Generally you will want the use + * GIT_CHECKOUT_SAFE to update files in the working + * directory. + */ + git_checkout_options checkout_opts; + + /** + * Options which control the fetch, including callbacks. + * + * The callbacks to use for reporting fetch progress, and for acquiring + * credentials in the event they are needed. + */ + git_fetch_options fetch_opts; + + /** + * Allow fetching from the submodule's default remote if the target + * commit isn't found. Enabled by default. + */ + int allow_fetch; +} git_submodule_update_options; + +#define GIT_SUBMODULE_UPDATE_OPTIONS_VERSION 1 +#define GIT_SUBMODULE_UPDATE_OPTIONS_INIT \ + { GIT_SUBMODULE_UPDATE_OPTIONS_VERSION, \ + { GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE }, \ + GIT_FETCH_OPTIONS_INIT, 1 } + +/** + * Initialize git_submodule_update_options structure + * + * Initializes a `git_submodule_update_options` with default values. Equivalent to + * creating an instance with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. + * + * @param opts The `git_submodule_update_options` struct to initialize. + * @param version The struct version; pass `GIT_SUBMODULE_UPDATE_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_submodule_update_options_init( + git_submodule_update_options *opts, unsigned int version); + +/** + * Update a submodule. This will clone a missing submodule and + * checkout the subrepository to the commit specified in the index of + * the containing repository. If the submodule repository doesn't contain + * the target commit (e.g. because fetchRecurseSubmodules isn't set), then + * the submodule is fetched using the fetch options supplied in options. + * + * @param submodule Submodule object + * @param init If the submodule is not initialized, setting this flag to true + * will initialize the submodule before updating. Otherwise, this will + * return an error if attempting to update an uninitialized repository. + * but setting this to true forces them to be updated. + * @param options configuration options for the update. If NULL, the + * function works as though GIT_SUBMODULE_UPDATE_OPTIONS_INIT was passed. + * @return 0 on success, any non-zero return value from a callback + * function, or a negative value to indicate an error (use + * `git_error_last` for a detailed error message). + */ +GIT_EXTERN(int) git_submodule_update(git_submodule *submodule, int init, git_submodule_update_options *options); + +/** + * Lookup submodule information by name or path. + * + * Given either the submodule name or path (they are usually the same), this + * returns a structure describing the submodule. + * + * There are two expected error scenarios: + * + * - The submodule is not mentioned in the HEAD, the index, and the config, + * but does "exist" in the working directory (i.e. there is a subdirectory + * that appears to be a Git repository). In this case, this function + * returns GIT_EEXISTS to indicate a sub-repository exists but not in a + * state where a git_submodule can be instantiated. + * - The submodule is not mentioned in the HEAD, index, or config and the + * working directory doesn't contain a value git repo at that path. + * There may or may not be anything else at that path, but nothing that + * looks like a submodule. In this case, this returns GIT_ENOTFOUND. + * + * You must call `git_submodule_free` when done with the submodule. + * + * @param out Output ptr to submodule; pass NULL to just get return code + * @param repo The parent repository + * @param name The name of or path to the submodule; trailing slashes okay + * @return 0 on success, GIT_ENOTFOUND if submodule does not exist, + * GIT_EEXISTS if a repository is found in working directory only, + * -1 on other errors. + */ +GIT_EXTERN(int) git_submodule_lookup( + git_submodule **out, + git_repository *repo, + const char *name); + +/** + * Create an in-memory copy of a submodule. The copy must be explicitly + * free'd or it will leak. + * + * @param out Pointer to store the copy of the submodule. + * @param source Original submodule to copy. + * @return 0 + */ +GIT_EXTERN(int) git_submodule_dup(git_submodule **out, git_submodule *source); + +/** + * Release a submodule + * + * @param submodule Submodule object + */ +GIT_EXTERN(void) git_submodule_free(git_submodule *submodule); + +/** + * Iterate over all tracked submodules of a repository. + * + * See the note on `git_submodule` above. This iterates over the tracked + * submodules as described therein. + * + * If you are concerned about items in the working directory that look like + * submodules but are not tracked, the diff API will generate a diff record + * for workdir items that look like submodules but are not tracked, showing + * them as added in the workdir. Also, the status API will treat the entire + * subdirectory of a contained git repo as a single GIT_STATUS_WT_NEW item. + * + * @param repo The repository + * @param callback Function to be called with the name of each submodule. + * Return a non-zero value to terminate the iteration. + * @param payload Extra data to pass to callback + * @return 0 on success, -1 on error, or non-zero return value of callback + */ +GIT_EXTERN(int) git_submodule_foreach( + git_repository *repo, + git_submodule_cb callback, + void *payload); + +/** + * Set up a new git submodule for checkout. + * + * This does "git submodule add" up to the fetch and checkout of the + * submodule contents. It preps a new submodule, creates an entry in + * .gitmodules and creates an empty initialized repository either at the + * given path in the working directory or in .git/modules with a gitlink + * from the working directory to the new repo. + * + * To fully emulate "git submodule add" call this function, then open the + * submodule repo and perform the clone step as needed (if you don't need + * anything custom see `git_submodule_add_clone()`). Lastly, call + * `git_submodule_add_finalize()` to wrap up adding the new submodule and + * .gitmodules to the index to be ready to commit. + * + * You must call `git_submodule_free` on the submodule object when done. + * + * @param out The newly created submodule ready to open for clone + * @param repo The repository in which you want to create the submodule + * @param url URL for the submodule's remote + * @param path Path at which the submodule should be created + * @param use_gitlink Should workdir contain a gitlink to the repo in + * .git/modules vs. repo directly in workdir. + * @return 0 on success, GIT_EEXISTS if submodule already exists, + * -1 on other errors. + */ +GIT_EXTERN(int) git_submodule_add_setup( + git_submodule **out, + git_repository *repo, + const char *url, + const char *path, + int use_gitlink); + +/** + * Perform the clone step for a newly created submodule. + * + * This performs the necessary `git_clone` to setup a newly-created submodule. + * + * @param out The newly created repository object. Optional. + * @param submodule The submodule currently waiting for its clone. + * @param opts The options to use. + * + * @return 0 on success, -1 on other errors (see git_clone). + */ +GIT_EXTERN(int) git_submodule_clone( + git_repository **out, + git_submodule *submodule, + const git_submodule_update_options *opts); + +/** + * Resolve the setup of a new git submodule. + * + * This should be called on a submodule once you have called add setup + * and done the clone of the submodule. This adds the .gitmodules file + * and the newly cloned submodule to the index to be ready to be committed + * (but doesn't actually do the commit). + * + * @param submodule The submodule to finish adding. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_submodule_add_finalize(git_submodule *submodule); + +/** + * Add current submodule HEAD commit to index of superproject. + * + * @param submodule The submodule to add to the index + * @param write_index Boolean if this should immediately write the index + * file. If you pass this as false, you will have to get the + * git_index and explicitly call `git_index_write()` on it to + * save the change. + * @return 0 on success, <0 on failure + */ +GIT_EXTERN(int) git_submodule_add_to_index( + git_submodule *submodule, + int write_index); + +/** + * Get the containing repository for a submodule. + * + * This returns a pointer to the repository that contains the submodule. + * This is a just a reference to the repository that was passed to the + * original `git_submodule_lookup()` call, so if that repository has been + * freed, then this may be a dangling reference. + * + * @param submodule Pointer to submodule object + * @return Pointer to `git_repository` + */ +GIT_EXTERN(git_repository *) git_submodule_owner(git_submodule *submodule); + +/** + * Get the name of submodule. + * + * @param submodule Pointer to submodule object + * @return Pointer to the submodule name + */ +GIT_EXTERN(const char *) git_submodule_name(git_submodule *submodule); + +/** + * Get the path to the submodule. + * + * The path is almost always the same as the submodule name, but the + * two are actually not required to match. + * + * @param submodule Pointer to submodule object + * @return Pointer to the submodule path + */ +GIT_EXTERN(const char *) git_submodule_path(git_submodule *submodule); + +/** + * Get the URL for the submodule. + * + * @param submodule Pointer to submodule object + * @return Pointer to the submodule url + */ +GIT_EXTERN(const char *) git_submodule_url(git_submodule *submodule); + +/** + * Resolve a submodule url relative to the given repository. + * + * @param out buffer to store the absolute submodule url in + * @param repo Pointer to repository object + * @param url Relative url + * @return 0 or an error code + */ +GIT_EXTERN(int) git_submodule_resolve_url(git_buf *out, git_repository *repo, const char *url); + +/** +* Get the branch for the submodule. +* +* @param submodule Pointer to submodule object +* @return Pointer to the submodule branch +*/ +GIT_EXTERN(const char *) git_submodule_branch(git_submodule *submodule); + +/** + * Set the branch for the submodule in the configuration + * + * After calling this, you may wish to call `git_submodule_sync()` to + * write the changes to the checked out submodule repository. + * + * @param repo the repository to affect + * @param name the name of the submodule to configure + * @param branch Branch that should be used for the submodule + * @return 0 on success, <0 on failure + */ +GIT_EXTERN(int) git_submodule_set_branch(git_repository *repo, const char *name, const char *branch); + +/** + * Set the URL for the submodule in the configuration + * + * + * After calling this, you may wish to call `git_submodule_sync()` to + * write the changes to the checked out submodule repository. + * + * @param repo the repository to affect + * @param name the name of the submodule to configure + * @param url URL that should be used for the submodule + * @return 0 on success, <0 on failure + */ +GIT_EXTERN(int) git_submodule_set_url(git_repository *repo, const char *name, const char *url); + +/** + * Get the OID for the submodule in the index. + * + * @param submodule Pointer to submodule object + * @return Pointer to git_oid or NULL if submodule is not in index. + */ +GIT_EXTERN(const git_oid *) git_submodule_index_id(git_submodule *submodule); + +/** + * Get the OID for the submodule in the current HEAD tree. + * + * @param submodule Pointer to submodule object + * @return Pointer to git_oid or NULL if submodule is not in the HEAD. + */ +GIT_EXTERN(const git_oid *) git_submodule_head_id(git_submodule *submodule); + +/** + * Get the OID for the submodule in the current working directory. + * + * This returns the OID that corresponds to looking up 'HEAD' in the checked + * out submodule. If there are pending changes in the index or anything + * else, this won't notice that. You should call `git_submodule_status()` + * for a more complete picture about the state of the working directory. + * + * @param submodule Pointer to submodule object + * @return Pointer to git_oid or NULL if submodule is not checked out. + */ +GIT_EXTERN(const git_oid *) git_submodule_wd_id(git_submodule *submodule); + +/** + * Get the ignore rule that will be used for the submodule. + * + * These values control the behavior of `git_submodule_status()` for this + * submodule. There are four ignore values: + * + * - **GIT_SUBMODULE_IGNORE_NONE** will consider any change to the contents + * of the submodule from a clean checkout to be dirty, including the + * addition of untracked files. This is the default if unspecified. + * - **GIT_SUBMODULE_IGNORE_UNTRACKED** examines the contents of the + * working tree (i.e. call `git_status_foreach()` on the submodule) but + * UNTRACKED files will not count as making the submodule dirty. + * - **GIT_SUBMODULE_IGNORE_DIRTY** means to only check if the HEAD of the + * submodule has moved for status. This is fast since it does not need to + * scan the working tree of the submodule at all. + * - **GIT_SUBMODULE_IGNORE_ALL** means not to open the submodule repo. + * The working directory will be consider clean so long as there is a + * checked out version present. + * + * @param submodule The submodule to check + * @return The current git_submodule_ignore_t valyue what will be used for + * this submodule. + */ +GIT_EXTERN(git_submodule_ignore_t) git_submodule_ignore( + git_submodule *submodule); + +/** + * Set the ignore rule for the submodule in the configuration + * + * This does not affect any currently-loaded instances. + * + * @param repo the repository to affect + * @param name the name of the submdule + * @param ignore The new value for the ignore rule + * @return 0 or an error code + */ +GIT_EXTERN(int) git_submodule_set_ignore( + git_repository *repo, + const char *name, + git_submodule_ignore_t ignore); + +/** + * Get the update rule that will be used for the submodule. + * + * This value controls the behavior of the `git submodule update` command. + * There are four useful values documented with `git_submodule_update_t`. + * + * @param submodule The submodule to check + * @return The current git_submodule_update_t value that will be used + * for this submodule. + */ +GIT_EXTERN(git_submodule_update_t) git_submodule_update_strategy( + git_submodule *submodule); + +/** + * Set the update rule for the submodule in the configuration + * + * This setting won't affect any existing instances. + * + * @param repo the repository to affect + * @param name the name of the submodule to configure + * @param update The new value to use + * @return 0 or an error code + */ +GIT_EXTERN(int) git_submodule_set_update( + git_repository *repo, + const char *name, + git_submodule_update_t update); + +/** + * Read the fetchRecurseSubmodules rule for a submodule. + * + * This accesses the submodule..fetchRecurseSubmodules value for + * the submodule that controls fetching behavior for the submodule. + * + * Note that at this time, libgit2 does not honor this setting and the + * fetch functionality current ignores submodules. + * + * @return 0 if fetchRecurseSubmodules is false, 1 if true + */ +GIT_EXTERN(git_submodule_recurse_t) git_submodule_fetch_recurse_submodules( + git_submodule *submodule); + +/** + * Set the fetchRecurseSubmodules rule for a submodule in the configuration + * + * This setting won't affect any existing instances. + * + * @param repo the repository to affect + * @param name the submodule to configure + * @param fetch_recurse_submodules Boolean value + * @return old value for fetchRecurseSubmodules + */ +GIT_EXTERN(int) git_submodule_set_fetch_recurse_submodules( + git_repository *repo, + const char *name, + git_submodule_recurse_t fetch_recurse_submodules); + +/** + * Copy submodule info into ".git/config" file. + * + * Just like "git submodule init", this copies information about the + * submodule into ".git/config". You can use the accessor functions + * above to alter the in-memory git_submodule object and control what + * is written to the config, overriding what is in .gitmodules. + * + * @param submodule The submodule to write into the superproject config + * @param overwrite By default, existing entries will not be overwritten, + * but setting this to true forces them to be updated. + * @return 0 on success, <0 on failure. + */ +GIT_EXTERN(int) git_submodule_init(git_submodule *submodule, int overwrite); + +/** + * Set up the subrepository for a submodule in preparation for clone. + * + * This function can be called to init and set up a submodule + * repository from a submodule in preparation to clone it from + * its remote. + * + * @param out Output pointer to the created git repository. + * @param sm The submodule to create a new subrepository from. + * @param use_gitlink Should the workdir contain a gitlink to + * the repo in .git/modules vs. repo directly in workdir. + * @return 0 on success, <0 on failure. + */ +GIT_EXTERN(int) git_submodule_repo_init( + git_repository **out, + const git_submodule *sm, + int use_gitlink); + +/** + * Copy submodule remote info into submodule repo. + * + * This copies the information about the submodules URL into the checked out + * submodule config, acting like "git submodule sync". This is useful if + * you have altered the URL for the submodule (or it has been altered by a + * fetch of upstream changes) and you need to update your local repo. + * + * @param submodule The submodule to copy. + * @return 0 or an error code. + */ +GIT_EXTERN(int) git_submodule_sync(git_submodule *submodule); + +/** + * Open the repository for a submodule. + * + * This is a newly opened repository object. The caller is responsible for + * calling `git_repository_free()` on it when done. Multiple calls to this + * function will return distinct `git_repository` objects. This will only + * work if the submodule is checked out into the working directory. + * + * @param repo Pointer to the submodule repo which was opened + * @param submodule Submodule to be opened + * @return 0 on success, <0 if submodule repo could not be opened. + */ +GIT_EXTERN(int) git_submodule_open( + git_repository **repo, + git_submodule *submodule); + +/** + * Reread submodule info from config, index, and HEAD. + * + * Call this to reread cached submodule information for this submodule if + * you have reason to believe that it has changed. + * + * @param submodule The submodule to reload + * @param force Force reload even if the data doesn't seem out of date + * @return 0 on success, <0 on error + */ +GIT_EXTERN(int) git_submodule_reload(git_submodule *submodule, int force); + +/** + * Get the status for a submodule. + * + * This looks at a submodule and tries to determine the status. It + * will return a combination of the `GIT_SUBMODULE_STATUS` values above. + * How deeply it examines the working directory to do this will depend + * on the `git_submodule_ignore_t` value for the submodule. + * + * @param status Combination of `GIT_SUBMODULE_STATUS` flags + * @param repo the repository in which to look + * @param name name of the submodule + * @param ignore the ignore rules to follow + * @return 0 on success, <0 on error + */ +GIT_EXTERN(int) git_submodule_status( + unsigned int *status, + git_repository *repo, + const char *name, + git_submodule_ignore_t ignore); + +/** + * Get the locations of submodule information. + * + * This is a bit like a very lightweight version of `git_submodule_status`. + * It just returns a made of the first four submodule status values (i.e. + * the ones like GIT_SUBMODULE_STATUS_IN_HEAD, etc) that tell you where the + * submodule data comes from (i.e. the HEAD commit, gitmodules file, etc.). + * This can be useful if you want to know if the submodule is present in the + * working directory at this point in time, etc. + * + * @param location_status Combination of first four `GIT_SUBMODULE_STATUS` flags + * @param submodule Submodule for which to get status + * @return 0 on success, <0 on error + */ +GIT_EXTERN(int) git_submodule_location( + unsigned int *location_status, + git_submodule *submodule); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/alloc.h b/3rdparty/libgit2/include/git2/sys/alloc.h index e7f85b8..f96aadc 100644 --- a/3rdparty/libgit2/include/git2/sys/alloc.h +++ b/3rdparty/libgit2/include/git2/sys/alloc.h @@ -1,67 +1,67 @@ -/* - * 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_sys_git_alloc_h__ -#define INCLUDE_sys_git_alloc_h__ - -#include "git2/common.h" - -GIT_BEGIN_DECL - -/** - * An instance for a custom memory allocator - * - * Setting the pointers of this structure allows the developer to implement - * custom memory allocators. The global memory allocator can be set by using - * "GIT_OPT_SET_ALLOCATOR" with the `git_libgit2_opts` function. Keep in mind - * that all fields need to be set to a proper function. - */ -typedef struct { - /** Allocate `n` bytes of memory */ - void * GIT_CALLBACK(gmalloc)(size_t n, const char *file, int line); - - /** - * This function shall deallocate the old object `ptr` and return a - * pointer to a new object that has the size specified by `size`. In - * case `ptr` is `NULL`, a new array shall be allocated. - */ - void * GIT_CALLBACK(grealloc)(void *ptr, size_t size, const char *file, int line); - - /** - * This function shall free the memory pointed to by `ptr`. In case - * `ptr` is `NULL`, this shall be a no-op. - */ - void GIT_CALLBACK(gfree)(void *ptr); -} git_allocator; - -/** - * Initialize the allocator structure to use the `stdalloc` pointer. - * - * Set up the structure so that all of its members are using the standard - * "stdalloc" allocator functions. The structure can then be used with - * `git_allocator_setup`. - * - * @param allocator The allocator that is to be initialized. - * @return An error code or 0. - */ -int git_stdalloc_init_allocator(git_allocator *allocator); - -/** - * Initialize the allocator structure to use the `crtdbg` pointer. - * - * Set up the structure so that all of its members are using the "crtdbg" - * allocator functions. Note that this allocator is only available on Windows - * platforms and only if libgit2 is being compiled with "-DMSVC_CRTDBG". - * - * @param allocator The allocator that is to be initialized. - * @return An error code or 0. - */ -int git_win32_crtdbg_init_allocator(git_allocator *allocator); - -GIT_END_DECL - -#endif +/* + * 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_sys_git_alloc_h__ +#define INCLUDE_sys_git_alloc_h__ + +#include "git2/common.h" + +GIT_BEGIN_DECL + +/** + * An instance for a custom memory allocator + * + * Setting the pointers of this structure allows the developer to implement + * custom memory allocators. The global memory allocator can be set by using + * "GIT_OPT_SET_ALLOCATOR" with the `git_libgit2_opts` function. Keep in mind + * that all fields need to be set to a proper function. + */ +typedef struct { + /** Allocate `n` bytes of memory */ + void * GIT_CALLBACK(gmalloc)(size_t n, const char *file, int line); + + /** + * This function shall deallocate the old object `ptr` and return a + * pointer to a new object that has the size specified by `size`. In + * case `ptr` is `NULL`, a new array shall be allocated. + */ + void * GIT_CALLBACK(grealloc)(void *ptr, size_t size, const char *file, int line); + + /** + * This function shall free the memory pointed to by `ptr`. In case + * `ptr` is `NULL`, this shall be a no-op. + */ + void GIT_CALLBACK(gfree)(void *ptr); +} git_allocator; + +/** + * Initialize the allocator structure to use the `stdalloc` pointer. + * + * Set up the structure so that all of its members are using the standard + * "stdalloc" allocator functions. The structure can then be used with + * `git_allocator_setup`. + * + * @param allocator The allocator that is to be initialized. + * @return An error code or 0. + */ +int git_stdalloc_init_allocator(git_allocator *allocator); + +/** + * Initialize the allocator structure to use the `crtdbg` pointer. + * + * Set up the structure so that all of its members are using the "crtdbg" + * allocator functions. Note that this allocator is only available on Windows + * platforms and only if libgit2 is being compiled with "-DMSVC_CRTDBG". + * + * @param allocator The allocator that is to be initialized. + * @return An error code or 0. + */ +int git_win32_crtdbg_init_allocator(git_allocator *allocator); + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/sys/commit.h b/3rdparty/libgit2/include/git2/sys/commit.h index ba67106..06b76fd 100644 --- a/3rdparty/libgit2/include/git2/sys/commit.h +++ b/3rdparty/libgit2/include/git2/sys/commit.h @@ -1,80 +1,80 @@ -/* - * 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_sys_git_commit_h__ -#define INCLUDE_sys_git_commit_h__ - -#include "git2/common.h" -#include "git2/types.h" -#include "git2/oid.h" - -/** - * @file git2/sys/commit.h - * @brief Low-level Git commit creation - * @defgroup git_backend Git custom backend APIs - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Create new commit in the repository from a list of `git_oid` values. - * - * See documentation for `git_commit_create()` for information about the - * parameters, as the meaning is identical excepting that `tree` and - * `parents` now take `git_oid`. This is a dangerous API in that nor - * the `tree`, neither the `parents` list of `git_oid`s are checked for - * validity. - * - * @see git_commit_create - */ -GIT_EXTERN(int) git_commit_create_from_ids( - git_oid *id, - git_repository *repo, - const char *update_ref, - const git_signature *author, - const git_signature *committer, - const char *message_encoding, - const char *message, - const git_oid *tree, - size_t parent_count, - const git_oid *parents[]); - -/** - * Callback function to return parents for commit. - * - * This is invoked with the count of the number of parents processed so far - * along with the user supplied payload. This should return a git_oid of - * the next parent or NULL if all parents have been provided. - */ -typedef const git_oid * GIT_CALLBACK(git_commit_parent_callback)(size_t idx, void *payload); - -/** - * Create a new commit in the repository with an callback to supply parents. - * - * See documentation for `git_commit_create()` for information about the - * parameters, as the meaning is identical excepting that `tree` takes a - * `git_oid` and doesn't check for validity, and `parent_cb` is invoked - * with `parent_payload` and should return `git_oid` values or NULL to - * indicate that all parents are accounted for. - * - * @see git_commit_create - */ -GIT_EXTERN(int) git_commit_create_from_callback( - git_oid *id, - git_repository *repo, - const char *update_ref, - const git_signature *author, - const git_signature *committer, - const char *message_encoding, - const char *message, - const git_oid *tree, - git_commit_parent_callback parent_cb, - void *parent_payload); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_commit_h__ +#define INCLUDE_sys_git_commit_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" + +/** + * @file git2/sys/commit.h + * @brief Low-level Git commit creation + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create new commit in the repository from a list of `git_oid` values. + * + * See documentation for `git_commit_create()` for information about the + * parameters, as the meaning is identical excepting that `tree` and + * `parents` now take `git_oid`. This is a dangerous API in that nor + * the `tree`, neither the `parents` list of `git_oid`s are checked for + * validity. + * + * @see git_commit_create + */ +GIT_EXTERN(int) git_commit_create_from_ids( + git_oid *id, + git_repository *repo, + const char *update_ref, + const git_signature *author, + const git_signature *committer, + const char *message_encoding, + const char *message, + const git_oid *tree, + size_t parent_count, + const git_oid *parents[]); + +/** + * Callback function to return parents for commit. + * + * This is invoked with the count of the number of parents processed so far + * along with the user supplied payload. This should return a git_oid of + * the next parent or NULL if all parents have been provided. + */ +typedef const git_oid * GIT_CALLBACK(git_commit_parent_callback)(size_t idx, void *payload); + +/** + * Create a new commit in the repository with an callback to supply parents. + * + * See documentation for `git_commit_create()` for information about the + * parameters, as the meaning is identical excepting that `tree` takes a + * `git_oid` and doesn't check for validity, and `parent_cb` is invoked + * with `parent_payload` and should return `git_oid` values or NULL to + * indicate that all parents are accounted for. + * + * @see git_commit_create + */ +GIT_EXTERN(int) git_commit_create_from_callback( + git_oid *id, + git_repository *repo, + const char *update_ref, + const git_signature *author, + const git_signature *committer, + const char *message_encoding, + const char *message, + const git_oid *tree, + git_commit_parent_callback parent_cb, + void *parent_payload); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/commit_graph.h b/3rdparty/libgit2/include/git2/sys/commit_graph.h index 06e045f..3bb86b9 100644 --- a/3rdparty/libgit2/include/git2/sys/commit_graph.h +++ b/3rdparty/libgit2/include/git2/sys/commit_graph.h @@ -1,184 +1,184 @@ -/* - * 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_sys_git_commit_graph_h__ -#define INCLUDE_sys_git_commit_graph_h__ - -#include "git2/common.h" -#include "git2/types.h" - -/** - * @file git2/sys/commit_graph.h - * @brief Git commit-graph - * @defgroup git_commit_graph Git commit-graph APIs - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Opens a `git_commit_graph` from a path to an objects directory. - * - * This finds, opens, and validates the `commit-graph` file. - * - * @param cgraph_out the `git_commit_graph` struct to initialize. - * @param objects_dir the path to a git objects directory. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_commit_graph_open( - git_commit_graph **cgraph_out, - const char *objects_dir -#ifdef GIT_EXPERIMENTAL_SHA256 - , git_oid_t oid_type -#endif - ); - -/** - * Frees commit-graph data. This should only be called when memory allocated - * using `git_commit_graph_open` is not returned to libgit2 because it was not - * associated with the ODB through a successful call to - * `git_odb_set_commit_graph`. - * - * @param cgraph the commit-graph object to free. If NULL, no action is taken. - */ -GIT_EXTERN(void) git_commit_graph_free(git_commit_graph *cgraph); - -/** - * Create a new writer for `commit-graph` files. - * - * @param out Location to store the writer pointer. - * @param objects_info_dir The `objects/info` directory. - * The `commit-graph` file will be written in this directory. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_graph_writer_new( - git_commit_graph_writer **out, - const char *objects_info_dir -#ifdef GIT_EXPERIMENTAL_SHA256 - , git_oid_t oid_type -#endif - ); - -/** - * Free the commit-graph writer and its resources. - * - * @param w The writer to free. If NULL no action is taken. - */ -GIT_EXTERN(void) git_commit_graph_writer_free(git_commit_graph_writer *w); - -/** - * Add an `.idx` file (associated to a packfile) to the writer. - * - * @param w The writer. - * @param repo The repository that owns the `.idx` file. - * @param idx_path The path of an `.idx` file. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_graph_writer_add_index_file( - git_commit_graph_writer *w, - git_repository *repo, - const char *idx_path); - -/** - * Add a revwalk to the writer. This will add all the commits from the revwalk - * to the commit-graph. - * - * @param w The writer. - * @param walk The git_revwalk. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_graph_writer_add_revwalk( - git_commit_graph_writer *w, - git_revwalk *walk); - - -/** - * The strategy to use when adding a new set of commits to a pre-existing - * commit-graph chain. - */ -typedef enum { - /** - * Do not split commit-graph files. The other split strategy-related option - * fields are ignored. - */ - GIT_COMMIT_GRAPH_SPLIT_STRATEGY_SINGLE_FILE = 0 -} git_commit_graph_split_strategy_t; - -/** - * Options structure for - * `git_commit_graph_writer_commit`/`git_commit_graph_writer_dump`. - * - * Initialize with `GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT`. Alternatively, you - * can use `git_commit_graph_writer_options_init`. - */ -typedef struct { - unsigned int version; - - /** - * The strategy to use when adding new commits to a pre-existing commit-graph - * chain. - */ - git_commit_graph_split_strategy_t split_strategy; - - /** - * The number of commits in level N is less than X times the number of - * commits in level N + 1. Default is 2. - */ - float size_multiple; - - /** - * The number of commits in level N + 1 is more than C commits. - * Default is 64000. - */ - size_t max_commits; -} git_commit_graph_writer_options; - -#define GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION 1 -#define GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT { \ - GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION \ - } - -/** - * Initialize git_commit_graph_writer_options structure - * - * Initializes a `git_commit_graph_writer_options` with default values. Equivalent to - * creating an instance with `GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT`. - * - * @param opts The `git_commit_graph_writer_options` struct to initialize. - * @param version The struct version; pass `GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_commit_graph_writer_options_init( - git_commit_graph_writer_options *opts, - unsigned int version); - -/** - * Write a `commit-graph` file to a file. - * - * @param w The writer - * @param opts Pointer to git_commit_graph_writer_options struct. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_graph_writer_commit( - git_commit_graph_writer *w, - git_commit_graph_writer_options *opts); - -/** - * Dump the contents of the `commit-graph` to an in-memory buffer. - * - * @param buffer Buffer where to store the contents of the `commit-graph`. - * @param w The writer. - * @param opts Pointer to git_commit_graph_writer_options struct. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_commit_graph_writer_dump( - git_buf *buffer, - git_commit_graph_writer *w, - git_commit_graph_writer_options *opts); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_commit_graph_h__ +#define INCLUDE_sys_git_commit_graph_h__ + +#include "git2/common.h" +#include "git2/types.h" + +/** + * @file git2/sys/commit_graph.h + * @brief Git commit-graph + * @defgroup git_commit_graph Git commit-graph APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Opens a `git_commit_graph` from a path to an objects directory. + * + * This finds, opens, and validates the `commit-graph` file. + * + * @param cgraph_out the `git_commit_graph` struct to initialize. + * @param objects_dir the path to a git objects directory. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_commit_graph_open( + git_commit_graph **cgraph_out, + const char *objects_dir +#ifdef GIT_EXPERIMENTAL_SHA256 + , git_oid_t oid_type +#endif + ); + +/** + * Frees commit-graph data. This should only be called when memory allocated + * using `git_commit_graph_open` is not returned to libgit2 because it was not + * associated with the ODB through a successful call to + * `git_odb_set_commit_graph`. + * + * @param cgraph the commit-graph object to free. If NULL, no action is taken. + */ +GIT_EXTERN(void) git_commit_graph_free(git_commit_graph *cgraph); + +/** + * Create a new writer for `commit-graph` files. + * + * @param out Location to store the writer pointer. + * @param objects_info_dir The `objects/info` directory. + * The `commit-graph` file will be written in this directory. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_graph_writer_new( + git_commit_graph_writer **out, + const char *objects_info_dir +#ifdef GIT_EXPERIMENTAL_SHA256 + , git_oid_t oid_type +#endif + ); + +/** + * Free the commit-graph writer and its resources. + * + * @param w The writer to free. If NULL no action is taken. + */ +GIT_EXTERN(void) git_commit_graph_writer_free(git_commit_graph_writer *w); + +/** + * Add an `.idx` file (associated to a packfile) to the writer. + * + * @param w The writer. + * @param repo The repository that owns the `.idx` file. + * @param idx_path The path of an `.idx` file. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_graph_writer_add_index_file( + git_commit_graph_writer *w, + git_repository *repo, + const char *idx_path); + +/** + * Add a revwalk to the writer. This will add all the commits from the revwalk + * to the commit-graph. + * + * @param w The writer. + * @param walk The git_revwalk. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_graph_writer_add_revwalk( + git_commit_graph_writer *w, + git_revwalk *walk); + + +/** + * The strategy to use when adding a new set of commits to a pre-existing + * commit-graph chain. + */ +typedef enum { + /** + * Do not split commit-graph files. The other split strategy-related option + * fields are ignored. + */ + GIT_COMMIT_GRAPH_SPLIT_STRATEGY_SINGLE_FILE = 0 +} git_commit_graph_split_strategy_t; + +/** + * Options structure for + * `git_commit_graph_writer_commit`/`git_commit_graph_writer_dump`. + * + * Initialize with `GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT`. Alternatively, you + * can use `git_commit_graph_writer_options_init`. + */ +typedef struct { + unsigned int version; + + /** + * The strategy to use when adding new commits to a pre-existing commit-graph + * chain. + */ + git_commit_graph_split_strategy_t split_strategy; + + /** + * The number of commits in level N is less than X times the number of + * commits in level N + 1. Default is 2. + */ + float size_multiple; + + /** + * The number of commits in level N + 1 is more than C commits. + * Default is 64000. + */ + size_t max_commits; +} git_commit_graph_writer_options; + +#define GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION 1 +#define GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT { \ + GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION \ + } + +/** + * Initialize git_commit_graph_writer_options structure + * + * Initializes a `git_commit_graph_writer_options` with default values. Equivalent to + * creating an instance with `GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT`. + * + * @param opts The `git_commit_graph_writer_options` struct to initialize. + * @param version The struct version; pass `GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_commit_graph_writer_options_init( + git_commit_graph_writer_options *opts, + unsigned int version); + +/** + * Write a `commit-graph` file to a file. + * + * @param w The writer + * @param opts Pointer to git_commit_graph_writer_options struct. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_graph_writer_commit( + git_commit_graph_writer *w, + git_commit_graph_writer_options *opts); + +/** + * Dump the contents of the `commit-graph` to an in-memory buffer. + * + * @param buffer Buffer where to store the contents of the `commit-graph`. + * @param w The writer. + * @param opts Pointer to git_commit_graph_writer_options struct. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_graph_writer_dump( + git_buf *buffer, + git_commit_graph_writer *w, + git_commit_graph_writer_options *opts); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/config.h b/3rdparty/libgit2/include/git2/sys/config.h index 75d2075..7d408e0 100644 --- a/3rdparty/libgit2/include/git2/sys/config.h +++ b/3rdparty/libgit2/include/git2/sys/config.h @@ -1,181 +1,181 @@ -/* - * 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_sys_git_config_backend_h__ -#define INCLUDE_sys_git_config_backend_h__ - -#include "git2/common.h" -#include "git2/types.h" -#include "git2/config.h" - -/** - * @file git2/sys/config.h - * @brief Git config backend routines - * @defgroup git_backend Git custom backend APIs - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Every iterator must have this struct as its first element, so the - * API can talk to it. You'd define your iterator as - * - * struct my_iterator { - * git_config_iterator parent; - * ... - * } - * - * and assign `iter->parent.backend` to your `git_config_backend`. - */ -struct git_config_iterator { - git_config_backend *backend; - unsigned int flags; - - /** - * Return the current entry and advance the iterator. The - * memory belongs to the library. - */ - int GIT_CALLBACK(next)(git_config_entry **entry, git_config_iterator *iter); - - /** - * Free the iterator - */ - void GIT_CALLBACK(free)(git_config_iterator *iter); -}; - -/** - * Generic backend that implements the interface to - * access a configuration file - */ -struct git_config_backend { - unsigned int version; - /** True if this backend is for a snapshot */ - int readonly; - struct git_config *cfg; - - /* Open means open the file/database and parse if necessary */ - int GIT_CALLBACK(open)(struct git_config_backend *, git_config_level_t level, const git_repository *repo); - int GIT_CALLBACK(get)(struct git_config_backend *, const char *key, git_config_entry **entry); - int GIT_CALLBACK(set)(struct git_config_backend *, const char *key, const char *value); - int GIT_CALLBACK(set_multivar)(git_config_backend *cfg, const char *name, const char *regexp, const char *value); - int GIT_CALLBACK(del)(struct git_config_backend *, const char *key); - int GIT_CALLBACK(del_multivar)(struct git_config_backend *, const char *key, const char *regexp); - int GIT_CALLBACK(iterator)(git_config_iterator **, struct git_config_backend *); - /** Produce a read-only version of this backend */ - int GIT_CALLBACK(snapshot)(struct git_config_backend **, struct git_config_backend *); - /** - * Lock this backend. - * - * Prevent any writes to the data store backing this - * backend. Any updates must not be visible to any other - * readers. - */ - int GIT_CALLBACK(lock)(struct git_config_backend *); - /** - * Unlock the data store backing this backend. If success is - * true, the changes should be committed, otherwise rolled - * back. - */ - int GIT_CALLBACK(unlock)(struct git_config_backend *, int success); - void GIT_CALLBACK(free)(struct git_config_backend *); -}; -#define GIT_CONFIG_BACKEND_VERSION 1 -#define GIT_CONFIG_BACKEND_INIT {GIT_CONFIG_BACKEND_VERSION} - -/** - * Initializes a `git_config_backend` with default values. Equivalent to - * creating an instance with GIT_CONFIG_BACKEND_INIT. - * - * @param backend the `git_config_backend` struct to initialize. - * @param version Version of struct; pass `GIT_CONFIG_BACKEND_VERSION` - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_config_init_backend( - git_config_backend *backend, - unsigned int version); - -/** - * Add a generic config file instance to an existing config - * - * Note that the configuration object will free the file - * automatically. - * - * Further queries on this config object will access each - * of the config file instances in order (instances with - * a higher priority level will be accessed first). - * - * @param cfg the configuration to add the file to - * @param file the configuration file (backend) to add - * @param level the priority level of the backend - * @param repo optional repository to allow parsing of - * conditional includes - * @param force if a config file already exists for the given - * priority level, replace it - * @return 0 on success, GIT_EEXISTS when adding more than one file - * for a given priority level (and force_replace set to 0), or error code - */ -GIT_EXTERN(int) git_config_add_backend( - git_config *cfg, - git_config_backend *file, - git_config_level_t level, - const git_repository *repo, - int force); - -/** Options for in-memory configuration backends. */ -typedef struct { - unsigned int version; - - /** - * The type of this backend (eg, "command line"). If this is - * NULL, then this will be "in-memory". - */ - const char *backend_type; - - /** - * The path to the origin; if this is NULL then it will be - * left unset in the resulting configuration entries. - */ - const char *origin_path; -} git_config_backend_memory_options; - -#define GIT_CONFIG_BACKEND_MEMORY_OPTIONS_VERSION 1 -#define GIT_CONFIG_BACKEND_MEMORY_OPTIONS_INIT { GIT_CONFIG_BACKEND_MEMORY_OPTIONS_VERSION } - - -/** - * Create an in-memory configuration backend from a string in standard - * git configuration file format. - * - * @param out the new backend - * @param cfg the configuration that is to be parsed - * @param len the length of the string pointed to by `cfg` - * @param opts the options to initialize this backend with, or NULL - */ -extern int git_config_backend_from_string( - git_config_backend **out, - const char *cfg, - size_t len, - git_config_backend_memory_options *opts); - -/** - * Create an in-memory configuration backend from a list of name/value - * pairs. - * - * @param out the new backend - * @param values the configuration values to set (in "key=value" format) - * @param len the length of the values array - * @param opts the options to initialize this backend with, or NULL - */ -extern int git_config_backend_from_values( - git_config_backend **out, - const char **values, - size_t len, - git_config_backend_memory_options *opts); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_config_backend_h__ +#define INCLUDE_sys_git_config_backend_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/config.h" + +/** + * @file git2/sys/config.h + * @brief Git config backend routines + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Every iterator must have this struct as its first element, so the + * API can talk to it. You'd define your iterator as + * + * struct my_iterator { + * git_config_iterator parent; + * ... + * } + * + * and assign `iter->parent.backend` to your `git_config_backend`. + */ +struct git_config_iterator { + git_config_backend *backend; + unsigned int flags; + + /** + * Return the current entry and advance the iterator. The + * memory belongs to the library. + */ + int GIT_CALLBACK(next)(git_config_entry **entry, git_config_iterator *iter); + + /** + * Free the iterator + */ + void GIT_CALLBACK(free)(git_config_iterator *iter); +}; + +/** + * Generic backend that implements the interface to + * access a configuration file + */ +struct git_config_backend { + unsigned int version; + /** True if this backend is for a snapshot */ + int readonly; + struct git_config *cfg; + + /* Open means open the file/database and parse if necessary */ + int GIT_CALLBACK(open)(struct git_config_backend *, git_config_level_t level, const git_repository *repo); + int GIT_CALLBACK(get)(struct git_config_backend *, const char *key, git_config_entry **entry); + int GIT_CALLBACK(set)(struct git_config_backend *, const char *key, const char *value); + int GIT_CALLBACK(set_multivar)(git_config_backend *cfg, const char *name, const char *regexp, const char *value); + int GIT_CALLBACK(del)(struct git_config_backend *, const char *key); + int GIT_CALLBACK(del_multivar)(struct git_config_backend *, const char *key, const char *regexp); + int GIT_CALLBACK(iterator)(git_config_iterator **, struct git_config_backend *); + /** Produce a read-only version of this backend */ + int GIT_CALLBACK(snapshot)(struct git_config_backend **, struct git_config_backend *); + /** + * Lock this backend. + * + * Prevent any writes to the data store backing this + * backend. Any updates must not be visible to any other + * readers. + */ + int GIT_CALLBACK(lock)(struct git_config_backend *); + /** + * Unlock the data store backing this backend. If success is + * true, the changes should be committed, otherwise rolled + * back. + */ + int GIT_CALLBACK(unlock)(struct git_config_backend *, int success); + void GIT_CALLBACK(free)(struct git_config_backend *); +}; +#define GIT_CONFIG_BACKEND_VERSION 1 +#define GIT_CONFIG_BACKEND_INIT {GIT_CONFIG_BACKEND_VERSION} + +/** + * Initializes a `git_config_backend` with default values. Equivalent to + * creating an instance with GIT_CONFIG_BACKEND_INIT. + * + * @param backend the `git_config_backend` struct to initialize. + * @param version Version of struct; pass `GIT_CONFIG_BACKEND_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_config_init_backend( + git_config_backend *backend, + unsigned int version); + +/** + * Add a generic config file instance to an existing config + * + * Note that the configuration object will free the file + * automatically. + * + * Further queries on this config object will access each + * of the config file instances in order (instances with + * a higher priority level will be accessed first). + * + * @param cfg the configuration to add the file to + * @param file the configuration file (backend) to add + * @param level the priority level of the backend + * @param repo optional repository to allow parsing of + * conditional includes + * @param force if a config file already exists for the given + * priority level, replace it + * @return 0 on success, GIT_EEXISTS when adding more than one file + * for a given priority level (and force_replace set to 0), or error code + */ +GIT_EXTERN(int) git_config_add_backend( + git_config *cfg, + git_config_backend *file, + git_config_level_t level, + const git_repository *repo, + int force); + +/** Options for in-memory configuration backends. */ +typedef struct { + unsigned int version; + + /** + * The type of this backend (eg, "command line"). If this is + * NULL, then this will be "in-memory". + */ + const char *backend_type; + + /** + * The path to the origin; if this is NULL then it will be + * left unset in the resulting configuration entries. + */ + const char *origin_path; +} git_config_backend_memory_options; + +#define GIT_CONFIG_BACKEND_MEMORY_OPTIONS_VERSION 1 +#define GIT_CONFIG_BACKEND_MEMORY_OPTIONS_INIT { GIT_CONFIG_BACKEND_MEMORY_OPTIONS_VERSION } + + +/** + * Create an in-memory configuration backend from a string in standard + * git configuration file format. + * + * @param out the new backend + * @param cfg the configuration that is to be parsed + * @param len the length of the string pointed to by `cfg` + * @param opts the options to initialize this backend with, or NULL + */ +extern int git_config_backend_from_string( + git_config_backend **out, + const char *cfg, + size_t len, + git_config_backend_memory_options *opts); + +/** + * Create an in-memory configuration backend from a list of name/value + * pairs. + * + * @param out the new backend + * @param values the configuration values to set (in "key=value" format) + * @param len the length of the values array + * @param opts the options to initialize this backend with, or NULL + */ +extern int git_config_backend_from_values( + git_config_backend **out, + const char **values, + size_t len, + git_config_backend_memory_options *opts); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/cred.h b/3rdparty/libgit2/include/git2/sys/cred.h index 4d2a59a..d993f5b 100644 --- a/3rdparty/libgit2/include/git2/sys/cred.h +++ b/3rdparty/libgit2/include/git2/sys/cred.h @@ -1,15 +1,15 @@ -/* - * 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_sys_git_cred_h__ -#define INCLUDE_sys_git_cred_h__ - -/* These declarations have moved. */ -#ifndef GIT_DEPRECATE_HARD -# include "git2/sys/credential.h" -#endif - -#endif +/* + * 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_sys_git_cred_h__ +#define INCLUDE_sys_git_cred_h__ + +/* These declarations have moved. */ +#ifndef GIT_DEPRECATE_HARD +# include "git2/sys/credential.h" +#endif + +#endif diff --git a/3rdparty/libgit2/include/git2/sys/credential.h b/3rdparty/libgit2/include/git2/sys/credential.h index bb4c9f9..f38cafa 100644 --- a/3rdparty/libgit2/include/git2/sys/credential.h +++ b/3rdparty/libgit2/include/git2/sys/credential.h @@ -1,90 +1,90 @@ -/* - * 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_sys_git_credential_h__ -#define INCLUDE_sys_git_credential_h__ - -#include "git2/common.h" -#include "git2/credential.h" - -/** - * @file git2/sys/cred.h - * @brief Git credentials low-level implementation - * @defgroup git_credential Git credentials low-level implementation - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * The base structure for all credential types - */ -struct git_credential { - git_credential_t credtype; /**< A type of credential */ - - /** The deallocator for this type of credentials */ - void GIT_CALLBACK(free)(git_credential *cred); -}; - -/** A plaintext username and password */ -struct git_credential_userpass_plaintext { - git_credential parent; /**< The parent credential */ - char *username; /**< The username to authenticate as */ - char *password; /**< The password to use */ -}; - -/** Username-only credential information */ -struct git_credential_username { - git_credential parent; /**< The parent credential */ - char username[1]; /**< The username to authenticate as */ -}; - -/** - * A ssh key from disk - */ -struct git_credential_ssh_key { - git_credential parent; /**< The parent credential */ - char *username; /**< The username to authenticate as */ - char *publickey; /**< The path to a public key */ - char *privatekey; /**< The path to a private key */ - char *passphrase; /**< Passphrase to decrypt the private key */ -}; - -/** - * Keyboard-interactive based ssh authentication - */ -struct git_credential_ssh_interactive { - git_credential parent; /**< The parent credential */ - char *username; /**< The username to authenticate as */ - - /** - * Callback used for authentication. - */ - git_credential_ssh_interactive_cb prompt_callback; - - void *payload; /**< Payload passed to prompt_callback */ -}; - -/** - * A key with a custom signature function - */ -struct git_credential_ssh_custom { - git_credential parent; /**< The parent credential */ - char *username; /**< The username to authenticate as */ - char *publickey; /**< The public key data */ - size_t publickey_len; /**< Length of the public key */ - - /** - * Callback used to sign the data. - */ - git_credential_sign_cb sign_callback; - - void *payload; /**< Payload passed to prompt_callback */ -}; - -GIT_END_DECL - -#endif +/* + * 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_sys_git_credential_h__ +#define INCLUDE_sys_git_credential_h__ + +#include "git2/common.h" +#include "git2/credential.h" + +/** + * @file git2/sys/cred.h + * @brief Git credentials low-level implementation + * @defgroup git_credential Git credentials low-level implementation + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * The base structure for all credential types + */ +struct git_credential { + git_credential_t credtype; /**< A type of credential */ + + /** The deallocator for this type of credentials */ + void GIT_CALLBACK(free)(git_credential *cred); +}; + +/** A plaintext username and password */ +struct git_credential_userpass_plaintext { + git_credential parent; /**< The parent credential */ + char *username; /**< The username to authenticate as */ + char *password; /**< The password to use */ +}; + +/** Username-only credential information */ +struct git_credential_username { + git_credential parent; /**< The parent credential */ + char username[1]; /**< The username to authenticate as */ +}; + +/** + * A ssh key from disk + */ +struct git_credential_ssh_key { + git_credential parent; /**< The parent credential */ + char *username; /**< The username to authenticate as */ + char *publickey; /**< The path to a public key */ + char *privatekey; /**< The path to a private key */ + char *passphrase; /**< Passphrase to decrypt the private key */ +}; + +/** + * Keyboard-interactive based ssh authentication + */ +struct git_credential_ssh_interactive { + git_credential parent; /**< The parent credential */ + char *username; /**< The username to authenticate as */ + + /** + * Callback used for authentication. + */ + git_credential_ssh_interactive_cb prompt_callback; + + void *payload; /**< Payload passed to prompt_callback */ +}; + +/** + * A key with a custom signature function + */ +struct git_credential_ssh_custom { + git_credential parent; /**< The parent credential */ + char *username; /**< The username to authenticate as */ + char *publickey; /**< The public key data */ + size_t publickey_len; /**< Length of the public key */ + + /** + * Callback used to sign the data. + */ + git_credential_sign_cb sign_callback; + + void *payload; /**< Payload passed to prompt_callback */ +}; + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/sys/diff.h b/3rdparty/libgit2/include/git2/sys/diff.h index aefd7b9..703fe26 100644 --- a/3rdparty/libgit2/include/git2/sys/diff.h +++ b/3rdparty/libgit2/include/git2/sys/diff.h @@ -1,94 +1,94 @@ -/* - * 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_sys_git_diff_h__ -#define INCLUDE_sys_git_diff_h__ - -#include "git2/common.h" -#include "git2/types.h" -#include "git2/oid.h" -#include "git2/diff.h" -#include "git2/status.h" - -/** - * @file git2/sys/diff.h - * @brief Low-level Git diff utilities - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Diff print callback that writes to a git_buf. - * - * This function is provided not for you to call it directly, but instead - * so you can use it as a function pointer to the `git_diff_print` or - * `git_patch_print` APIs. When using those APIs, you specify a callback - * to actually handle the diff and/or patch data. - * - * Use this callback to easily write that data to a `git_buf` buffer. You - * must pass a `git_buf *` value as the payload to the `git_diff_print` - * and/or `git_patch_print` function. The data will be appended to the - * buffer (after any existing content). - */ -GIT_EXTERN(int) git_diff_print_callback__to_buf( - const git_diff_delta *delta, - const git_diff_hunk *hunk, - const git_diff_line *line, - void *payload); /**< payload must be a `git_buf *` */ - -/** - * Diff print callback that writes to stdio FILE handle. - * - * This function is provided not for you to call it directly, but instead - * so you can use it as a function pointer to the `git_diff_print` or - * `git_patch_print` APIs. When using those APIs, you specify a callback - * to actually handle the diff and/or patch data. - * - * Use this callback to easily write that data to a stdio FILE handle. You - * must pass a `FILE *` value (such as `stdout` or `stderr` or the return - * value from `fopen()`) as the payload to the `git_diff_print` - * and/or `git_patch_print` function. If you pass NULL, this will write - * data to `stdout`. - */ -GIT_EXTERN(int) git_diff_print_callback__to_file_handle( - const git_diff_delta *delta, - const git_diff_hunk *hunk, - const git_diff_line *line, - void *payload); /**< payload must be a `FILE *` */ - - -/** - * Performance data from diffing - */ -typedef struct { - unsigned int version; - size_t stat_calls; /**< Number of stat() calls performed */ - size_t oid_calculations; /**< Number of ID calculations */ -} git_diff_perfdata; - -#define GIT_DIFF_PERFDATA_VERSION 1 -#define GIT_DIFF_PERFDATA_INIT {GIT_DIFF_PERFDATA_VERSION,0,0} - -/** - * Get performance data for a diff object. - * - * @param out Structure to be filled with diff performance data - * @param diff Diff to read performance data from - * @return 0 for success, <0 for error - */ -GIT_EXTERN(int) git_diff_get_perfdata( - git_diff_perfdata *out, const git_diff *diff); - -/** - * Get performance data for diffs from a git_status_list - */ -GIT_EXTERN(int) git_status_list_get_perfdata( - git_diff_perfdata *out, const git_status_list *status); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_diff_h__ +#define INCLUDE_sys_git_diff_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" +#include "git2/diff.h" +#include "git2/status.h" + +/** + * @file git2/sys/diff.h + * @brief Low-level Git diff utilities + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Diff print callback that writes to a git_buf. + * + * This function is provided not for you to call it directly, but instead + * so you can use it as a function pointer to the `git_diff_print` or + * `git_patch_print` APIs. When using those APIs, you specify a callback + * to actually handle the diff and/or patch data. + * + * Use this callback to easily write that data to a `git_buf` buffer. You + * must pass a `git_buf *` value as the payload to the `git_diff_print` + * and/or `git_patch_print` function. The data will be appended to the + * buffer (after any existing content). + */ +GIT_EXTERN(int) git_diff_print_callback__to_buf( + const git_diff_delta *delta, + const git_diff_hunk *hunk, + const git_diff_line *line, + void *payload); /**< payload must be a `git_buf *` */ + +/** + * Diff print callback that writes to stdio FILE handle. + * + * This function is provided not for you to call it directly, but instead + * so you can use it as a function pointer to the `git_diff_print` or + * `git_patch_print` APIs. When using those APIs, you specify a callback + * to actually handle the diff and/or patch data. + * + * Use this callback to easily write that data to a stdio FILE handle. You + * must pass a `FILE *` value (such as `stdout` or `stderr` or the return + * value from `fopen()`) as the payload to the `git_diff_print` + * and/or `git_patch_print` function. If you pass NULL, this will write + * data to `stdout`. + */ +GIT_EXTERN(int) git_diff_print_callback__to_file_handle( + const git_diff_delta *delta, + const git_diff_hunk *hunk, + const git_diff_line *line, + void *payload); /**< payload must be a `FILE *` */ + + +/** + * Performance data from diffing + */ +typedef struct { + unsigned int version; + size_t stat_calls; /**< Number of stat() calls performed */ + size_t oid_calculations; /**< Number of ID calculations */ +} git_diff_perfdata; + +#define GIT_DIFF_PERFDATA_VERSION 1 +#define GIT_DIFF_PERFDATA_INIT {GIT_DIFF_PERFDATA_VERSION,0,0} + +/** + * Get performance data for a diff object. + * + * @param out Structure to be filled with diff performance data + * @param diff Diff to read performance data from + * @return 0 for success, <0 for error + */ +GIT_EXTERN(int) git_diff_get_perfdata( + git_diff_perfdata *out, const git_diff *diff); + +/** + * Get performance data for diffs from a git_status_list + */ +GIT_EXTERN(int) git_status_list_get_perfdata( + git_diff_perfdata *out, const git_status_list *status); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/email.h b/3rdparty/libgit2/include/git2/sys/email.h index 6f4a286..82446a5 100644 --- a/3rdparty/libgit2/include/git2/sys/email.h +++ b/3rdparty/libgit2/include/git2/sys/email.h @@ -1,45 +1,45 @@ -/* - * 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_sys_git_email_h__ -#define INCLUDE_sys_git_email_h__ - -/** - * @file git2/sys/email.h - * @brief Advanced git email creation routines - * @defgroup git_email Advanced git email creation routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Create a diff for a commit in mbox format for sending via email. - * - * @param out buffer to store the e-mail patch in - * @param diff the changes to include in the email - * @param patch_idx the patch index - * @param patch_count the total number of patches that will be included - * @param commit_id the commit id for this change - * @param summary the commit message for this change - * @param body optional text to include above the diffstat - * @param author the person who authored this commit - * @param opts email creation options - */ -GIT_EXTERN(int) git_email_create_from_diff( - git_buf *out, - git_diff *diff, - size_t patch_idx, - size_t patch_count, - const git_oid *commit_id, - const char *summary, - const char *body, - const git_signature *author, - const git_email_create_options *opts); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_email_h__ +#define INCLUDE_sys_git_email_h__ + +/** + * @file git2/sys/email.h + * @brief Advanced git email creation routines + * @defgroup git_email Advanced git email creation routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a diff for a commit in mbox format for sending via email. + * + * @param out buffer to store the e-mail patch in + * @param diff the changes to include in the email + * @param patch_idx the patch index + * @param patch_count the total number of patches that will be included + * @param commit_id the commit id for this change + * @param summary the commit message for this change + * @param body optional text to include above the diffstat + * @param author the person who authored this commit + * @param opts email creation options + */ +GIT_EXTERN(int) git_email_create_from_diff( + git_buf *out, + git_diff *diff, + size_t patch_idx, + size_t patch_count, + const git_oid *commit_id, + const char *summary, + const char *body, + const git_signature *author, + const git_email_create_options *opts); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/errors.h b/3rdparty/libgit2/include/git2/sys/errors.h index 3ae1215..6a83c03 100644 --- a/3rdparty/libgit2/include/git2/sys/errors.h +++ b/3rdparty/libgit2/include/git2/sys/errors.h @@ -1,66 +1,66 @@ -/* - * 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_sys_git_errors_h__ -#define INCLUDE_sys_git_errors_h__ - -#include "git2/common.h" - -GIT_BEGIN_DECL - -/** - * Clear the last library error that occurred for this thread. - */ -GIT_EXTERN(void) git_error_clear(void); - -/** - * Set the error message string for this thread, using `printf`-style - * formatting. - * - * This function is public so that custom ODB backends and the like can - * relay an error message through libgit2. Most regular users of libgit2 - * will never need to call this function -- actually, calling it in most - * circumstances (for example, calling from within a callback function) - * will just end up having the value overwritten by libgit2 internals. - * - * This error message is stored in thread-local storage and only applies - * to the particular thread that this libgit2 call is made from. - * - * @param error_class One of the `git_error_t` enum above describing the - * general subsystem that is responsible for the error. - * @param fmt The `printf`-style format string; subsequent arguments must - * be the arguments for the format string. - */ -GIT_EXTERN(void) git_error_set(int error_class, const char *fmt, ...) - GIT_FORMAT_PRINTF(2, 3); - -/** - * Set the error message string for this thread. This function is like - * `git_error_set` but takes a static string instead of a `printf`-style - * format. - * - * @param error_class One of the `git_error_t` enum above describing the - * general subsystem that is responsible for the error. - * @param string The error message to keep - * @return 0 on success or -1 on failure - */ -GIT_EXTERN(int) git_error_set_str(int error_class, const char *string); - -/** - * Set the error message to a special value for memory allocation failure. - * - * The normal `git_error_set_str()` function attempts to `strdup()` the - * string that is passed in. This is not a good idea when the error in - * question is a memory allocation failure. That circumstance has a - * special setter function that sets the error string to a known and - * statically allocated internal value. - */ -GIT_EXTERN(void) git_error_set_oom(void); - -GIT_END_DECL - -#endif +/* + * 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_sys_git_errors_h__ +#define INCLUDE_sys_git_errors_h__ + +#include "git2/common.h" + +GIT_BEGIN_DECL + +/** + * Clear the last library error that occurred for this thread. + */ +GIT_EXTERN(void) git_error_clear(void); + +/** + * Set the error message string for this thread, using `printf`-style + * formatting. + * + * This function is public so that custom ODB backends and the like can + * relay an error message through libgit2. Most regular users of libgit2 + * will never need to call this function -- actually, calling it in most + * circumstances (for example, calling from within a callback function) + * will just end up having the value overwritten by libgit2 internals. + * + * This error message is stored in thread-local storage and only applies + * to the particular thread that this libgit2 call is made from. + * + * @param error_class One of the `git_error_t` enum above describing the + * general subsystem that is responsible for the error. + * @param fmt The `printf`-style format string; subsequent arguments must + * be the arguments for the format string. + */ +GIT_EXTERN(void) git_error_set(int error_class, const char *fmt, ...) + GIT_FORMAT_PRINTF(2, 3); + +/** + * Set the error message string for this thread. This function is like + * `git_error_set` but takes a static string instead of a `printf`-style + * format. + * + * @param error_class One of the `git_error_t` enum above describing the + * general subsystem that is responsible for the error. + * @param string The error message to keep + * @return 0 on success or -1 on failure + */ +GIT_EXTERN(int) git_error_set_str(int error_class, const char *string); + +/** + * Set the error message to a special value for memory allocation failure. + * + * The normal `git_error_set_str()` function attempts to `strdup()` the + * string that is passed in. This is not a good idea when the error in + * question is a memory allocation failure. That circumstance has a + * special setter function that sets the error string to a known and + * statically allocated internal value. + */ +GIT_EXTERN(void) git_error_set_oom(void); + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/sys/filter.h b/3rdparty/libgit2/include/git2/sys/filter.h index b375941..7748aba 100644 --- a/3rdparty/libgit2/include/git2/sys/filter.h +++ b/3rdparty/libgit2/include/git2/sys/filter.h @@ -1,353 +1,353 @@ -/* - * 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_sys_git_filter_h__ -#define INCLUDE_sys_git_filter_h__ - -#include "git2/filter.h" - -/** - * @file git2/sys/filter.h - * @brief Git filter backend and plugin routines - * @defgroup git_backend Git custom backend APIs - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Look up a filter by name - * - * @param name The name of the filter - * @return Pointer to the filter object or NULL if not found - */ -GIT_EXTERN(git_filter *) git_filter_lookup(const char *name); - -#define GIT_FILTER_CRLF "crlf" -#define GIT_FILTER_IDENT "ident" - -/** - * This is priority that the internal CRLF filter will be registered with - */ -#define GIT_FILTER_CRLF_PRIORITY 0 - -/** - * This is priority that the internal ident filter will be registered with - */ -#define GIT_FILTER_IDENT_PRIORITY 100 - -/** - * This is priority to use with a custom filter to imitate a core Git - * filter driver, so that it will be run last on checkout and first on - * checkin. You do not have to use this, but it helps compatibility. - */ -#define GIT_FILTER_DRIVER_PRIORITY 200 - -/** - * Create a new empty filter list - * - * Normally you won't use this because `git_filter_list_load` will create - * the filter list for you, but you can use this in combination with the - * `git_filter_lookup` and `git_filter_list_push` functions to assemble - * your own chains of filters. - */ -GIT_EXTERN(int) git_filter_list_new( - git_filter_list **out, - git_repository *repo, - git_filter_mode_t mode, - uint32_t options); - -/** - * Add a filter to a filter list with the given payload. - * - * Normally you won't have to do this because the filter list is created - * by calling the "check" function on registered filters when the filter - * attributes are set, but this does allow more direct manipulation of - * filter lists when desired. - * - * Note that normally the "check" function can set up a payload for the - * filter. Using this function, you can either pass in a payload if you - * know the expected payload format, or you can pass NULL. Some filters - * may fail with a NULL payload. Good luck! - */ -GIT_EXTERN(int) git_filter_list_push( - git_filter_list *fl, git_filter *filter, void *payload); - -/** - * Look up how many filters are in the list - * - * We will attempt to apply all of these filters to any data passed in, - * but note that the filter apply action still has the option of skipping - * data that is passed in (for example, the CRLF filter will skip data - * that appears to be binary). - * - * @param fl A filter list - * @return The number of filters in the list - */ -GIT_EXTERN(size_t) git_filter_list_length(const git_filter_list *fl); - -/** - * A filter source represents a file/blob to be processed - */ -typedef struct git_filter_source git_filter_source; - -/** - * Get the repository that the source data is coming from. - */ -GIT_EXTERN(git_repository *) git_filter_source_repo(const git_filter_source *src); - -/** - * Get the path that the source data is coming from. - */ -GIT_EXTERN(const char *) git_filter_source_path(const git_filter_source *src); - -/** - * Get the file mode of the source file - * If the mode is unknown, this will return 0 - */ -GIT_EXTERN(uint16_t) git_filter_source_filemode(const git_filter_source *src); - -/** - * Get the OID of the source - * If the OID is unknown (often the case with GIT_FILTER_CLEAN) then - * this will return NULL. - */ -GIT_EXTERN(const git_oid *) git_filter_source_id(const git_filter_source *src); - -/** - * Get the git_filter_mode_t to be used - */ -GIT_EXTERN(git_filter_mode_t) git_filter_source_mode(const git_filter_source *src); - -/** - * Get the combination git_filter_flag_t options to be applied - */ -GIT_EXTERN(uint32_t) git_filter_source_flags(const git_filter_source *src); - -/** - * Initialize callback on filter - * - * Specified as `filter.initialize`, this is an optional callback invoked - * before a filter is first used. It will be called once at most. - * - * If non-NULL, the filter's `initialize` callback will be invoked right - * before the first use of the filter, so you can defer expensive - * initialization operations (in case libgit2 is being used in a way that - * doesn't need the filter). - */ -typedef int GIT_CALLBACK(git_filter_init_fn)(git_filter *self); - -/** - * Shutdown callback on filter - * - * Specified as `filter.shutdown`, this is an optional callback invoked - * when the filter is unregistered or when libgit2 is shutting down. It - * will be called once at most and should release resources as needed. - * This may be called even if the `initialize` callback was not made. - * - * Typically this function will free the `git_filter` object itself. - */ -typedef void GIT_CALLBACK(git_filter_shutdown_fn)(git_filter *self); - -/** - * Callback to decide if a given source needs this filter - * - * Specified as `filter.check`, this is an optional callback that checks - * if filtering is needed for a given source. - * - * It should return 0 if the filter should be applied (i.e. success), - * GIT_PASSTHROUGH if the filter should not be applied, or an error code - * to fail out of the filter processing pipeline and return to the caller. - * - * The `attr_values` will be set to the values of any attributes given in - * the filter definition. See `git_filter` below for more detail. - * - * The `payload` will be a pointer to a reference payload for the filter. - * This will start as NULL, but `check` can assign to this pointer for - * later use by the `stream` callback. Note that the value should be heap - * allocated (not stack), so that it doesn't go away before the `stream` - * callback can use it. If a filter allocates and assigns a value to the - * `payload`, it will need a `cleanup` callback to free the payload. - */ -typedef int GIT_CALLBACK(git_filter_check_fn)( - git_filter *self, - void **payload, /* NULL on entry, may be set */ - const git_filter_source *src, - const char **attr_values); - -#ifndef GIT_DEPRECATE_HARD -/** - * Callback to actually perform the data filtering - * - * Specified as `filter.apply`, this is the callback that actually filters - * data. If it successfully writes the output, it should return 0. Like - * `check`, it can return GIT_PASSTHROUGH to indicate that the filter - * doesn't want to run. Other error codes will stop filter processing and - * return to the caller. - * - * The `payload` value will refer to any payload that was set by the - * `check` callback. It may be read from or written to as needed. - * - * @deprecated use git_filter_stream_fn - */ -typedef int GIT_CALLBACK(git_filter_apply_fn)( - git_filter *self, - void **payload, /* may be read and/or set */ - git_buf *to, - const git_buf *from, - const git_filter_source *src); -#endif - -/** - * Callback to perform the data filtering. - * - * Specified as `filter.stream`, this is a callback that filters data - * in a streaming manner. This function will provide a - * `git_writestream` that will the original data will be written to; - * with that data, the `git_writestream` will then perform the filter - * translation and stream the filtered data out to the `next` location. - */ -typedef int GIT_CALLBACK(git_filter_stream_fn)( - git_writestream **out, - git_filter *self, - void **payload, - const git_filter_source *src, - git_writestream *next); - -/** - * Callback to clean up after filtering has been applied - * - * Specified as `filter.cleanup`, this is an optional callback invoked - * after the filter has been applied. If the `check`, `apply`, or - * `stream` callbacks allocated a `payload` to keep per-source filter - * state, use this callback to free that payload and release resources - * as required. - */ -typedef void GIT_CALLBACK(git_filter_cleanup_fn)( - git_filter *self, - void *payload); - -/** - * Filter structure used to register custom filters. - * - * To associate extra data with a filter, allocate extra data and put the - * `git_filter` struct at the start of your data buffer, then cast the - * `self` pointer to your larger structure when your callback is invoked. - */ -struct git_filter { - /** The `version` field should be set to `GIT_FILTER_VERSION`. */ - unsigned int version; - - /** - * A whitespace-separated list of attribute names to check for this - * filter (e.g. "eol crlf text"). If the attribute name is bare, it - * will be simply loaded and passed to the `check` callback. If it - * has a value (i.e. "name=value"), the attribute must match that - * value for the filter to be applied. The value may be a wildcard - * (eg, "name=*"), in which case the filter will be invoked for any - * value for the given attribute name. See the attribute parameter - * of the `check` callback for the attribute value that was specified. - */ - const char *attributes; - - /** Called when the filter is first used for any file. */ - git_filter_init_fn initialize; - - /** Called when the filter is removed or unregistered from the system. */ - git_filter_shutdown_fn shutdown; - - /** - * Called to determine whether the filter should be invoked for a - * given file. If this function returns `GIT_PASSTHROUGH` then the - * `stream` or `apply` functions will not be invoked and the - * contents will be passed through unmodified. - */ - git_filter_check_fn check; - -#ifdef GIT_DEPRECATE_HARD - void *reserved; -#else - /** - * Provided for backward compatibility; this will apply the - * filter to the given contents in a `git_buf`. Callers should - * provide a `stream` function instead. - */ - git_filter_apply_fn apply; -#endif - - /** - * Called to apply the filter, this function will provide a - * `git_writestream` that will the original data will be - * written to; with that data, the `git_writestream` will then - * perform the filter translation and stream the filtered data - * out to the `next` location. - */ - git_filter_stream_fn stream; - - /** Called when the system is done filtering for a file. */ - git_filter_cleanup_fn cleanup; -}; - -#define GIT_FILTER_VERSION 1 -#define GIT_FILTER_INIT {GIT_FILTER_VERSION} - -/** - * Initializes a `git_filter` with default values. Equivalent to - * creating an instance with GIT_FILTER_INIT. - * - * @param filter the `git_filter` struct to initialize. - * @param version Version the struct; pass `GIT_FILTER_VERSION` - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_filter_init(git_filter *filter, unsigned int version); - -/** - * Register a filter under a given name with a given priority. - * - * As mentioned elsewhere, the initialize callback will not be invoked - * immediately. It is deferred until the filter is used in some way. - * - * A filter's attribute checks and `check` and `stream` (or `apply`) - * callbacks will be issued in order of `priority` on smudge (to - * workdir), and in reverse order of `priority` on clean (to odb). - * - * Two filters are preregistered with libgit2: - * - GIT_FILTER_CRLF with priority 0 - * - GIT_FILTER_IDENT with priority 100 - * - * Currently the filter registry is not thread safe, so any registering or - * deregistering of filters must be done outside of any possible usage of - * the filters (i.e. during application setup or shutdown). - * - * @param name A name by which the filter can be referenced. Attempting - * to register with an in-use name will return GIT_EEXISTS. - * @param filter The filter definition. This pointer will be stored as is - * by libgit2 so it must be a durable allocation (either static - * or on the heap). - * @param priority The priority for filter application - * @return 0 on successful registry, error code <0 on failure - */ -GIT_EXTERN(int) git_filter_register( - const char *name, git_filter *filter, int priority); - -/** - * Remove the filter with the given name - * - * Attempting to remove the builtin libgit2 filters is not permitted and - * will return an error. - * - * Currently the filter registry is not thread safe, so any registering or - * deregistering of filters must be done outside of any possible usage of - * the filters (i.e. during application setup or shutdown). - * - * @param name The name under which the filter was registered - * @return 0 on success, error code <0 on failure - */ -GIT_EXTERN(int) git_filter_unregister(const char *name); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_filter_h__ +#define INCLUDE_sys_git_filter_h__ + +#include "git2/filter.h" + +/** + * @file git2/sys/filter.h + * @brief Git filter backend and plugin routines + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Look up a filter by name + * + * @param name The name of the filter + * @return Pointer to the filter object or NULL if not found + */ +GIT_EXTERN(git_filter *) git_filter_lookup(const char *name); + +#define GIT_FILTER_CRLF "crlf" +#define GIT_FILTER_IDENT "ident" + +/** + * This is priority that the internal CRLF filter will be registered with + */ +#define GIT_FILTER_CRLF_PRIORITY 0 + +/** + * This is priority that the internal ident filter will be registered with + */ +#define GIT_FILTER_IDENT_PRIORITY 100 + +/** + * This is priority to use with a custom filter to imitate a core Git + * filter driver, so that it will be run last on checkout and first on + * checkin. You do not have to use this, but it helps compatibility. + */ +#define GIT_FILTER_DRIVER_PRIORITY 200 + +/** + * Create a new empty filter list + * + * Normally you won't use this because `git_filter_list_load` will create + * the filter list for you, but you can use this in combination with the + * `git_filter_lookup` and `git_filter_list_push` functions to assemble + * your own chains of filters. + */ +GIT_EXTERN(int) git_filter_list_new( + git_filter_list **out, + git_repository *repo, + git_filter_mode_t mode, + uint32_t options); + +/** + * Add a filter to a filter list with the given payload. + * + * Normally you won't have to do this because the filter list is created + * by calling the "check" function on registered filters when the filter + * attributes are set, but this does allow more direct manipulation of + * filter lists when desired. + * + * Note that normally the "check" function can set up a payload for the + * filter. Using this function, you can either pass in a payload if you + * know the expected payload format, or you can pass NULL. Some filters + * may fail with a NULL payload. Good luck! + */ +GIT_EXTERN(int) git_filter_list_push( + git_filter_list *fl, git_filter *filter, void *payload); + +/** + * Look up how many filters are in the list + * + * We will attempt to apply all of these filters to any data passed in, + * but note that the filter apply action still has the option of skipping + * data that is passed in (for example, the CRLF filter will skip data + * that appears to be binary). + * + * @param fl A filter list + * @return The number of filters in the list + */ +GIT_EXTERN(size_t) git_filter_list_length(const git_filter_list *fl); + +/** + * A filter source represents a file/blob to be processed + */ +typedef struct git_filter_source git_filter_source; + +/** + * Get the repository that the source data is coming from. + */ +GIT_EXTERN(git_repository *) git_filter_source_repo(const git_filter_source *src); + +/** + * Get the path that the source data is coming from. + */ +GIT_EXTERN(const char *) git_filter_source_path(const git_filter_source *src); + +/** + * Get the file mode of the source file + * If the mode is unknown, this will return 0 + */ +GIT_EXTERN(uint16_t) git_filter_source_filemode(const git_filter_source *src); + +/** + * Get the OID of the source + * If the OID is unknown (often the case with GIT_FILTER_CLEAN) then + * this will return NULL. + */ +GIT_EXTERN(const git_oid *) git_filter_source_id(const git_filter_source *src); + +/** + * Get the git_filter_mode_t to be used + */ +GIT_EXTERN(git_filter_mode_t) git_filter_source_mode(const git_filter_source *src); + +/** + * Get the combination git_filter_flag_t options to be applied + */ +GIT_EXTERN(uint32_t) git_filter_source_flags(const git_filter_source *src); + +/** + * Initialize callback on filter + * + * Specified as `filter.initialize`, this is an optional callback invoked + * before a filter is first used. It will be called once at most. + * + * If non-NULL, the filter's `initialize` callback will be invoked right + * before the first use of the filter, so you can defer expensive + * initialization operations (in case libgit2 is being used in a way that + * doesn't need the filter). + */ +typedef int GIT_CALLBACK(git_filter_init_fn)(git_filter *self); + +/** + * Shutdown callback on filter + * + * Specified as `filter.shutdown`, this is an optional callback invoked + * when the filter is unregistered or when libgit2 is shutting down. It + * will be called once at most and should release resources as needed. + * This may be called even if the `initialize` callback was not made. + * + * Typically this function will free the `git_filter` object itself. + */ +typedef void GIT_CALLBACK(git_filter_shutdown_fn)(git_filter *self); + +/** + * Callback to decide if a given source needs this filter + * + * Specified as `filter.check`, this is an optional callback that checks + * if filtering is needed for a given source. + * + * It should return 0 if the filter should be applied (i.e. success), + * GIT_PASSTHROUGH if the filter should not be applied, or an error code + * to fail out of the filter processing pipeline and return to the caller. + * + * The `attr_values` will be set to the values of any attributes given in + * the filter definition. See `git_filter` below for more detail. + * + * The `payload` will be a pointer to a reference payload for the filter. + * This will start as NULL, but `check` can assign to this pointer for + * later use by the `stream` callback. Note that the value should be heap + * allocated (not stack), so that it doesn't go away before the `stream` + * callback can use it. If a filter allocates and assigns a value to the + * `payload`, it will need a `cleanup` callback to free the payload. + */ +typedef int GIT_CALLBACK(git_filter_check_fn)( + git_filter *self, + void **payload, /* NULL on entry, may be set */ + const git_filter_source *src, + const char **attr_values); + +#ifndef GIT_DEPRECATE_HARD +/** + * Callback to actually perform the data filtering + * + * Specified as `filter.apply`, this is the callback that actually filters + * data. If it successfully writes the output, it should return 0. Like + * `check`, it can return GIT_PASSTHROUGH to indicate that the filter + * doesn't want to run. Other error codes will stop filter processing and + * return to the caller. + * + * The `payload` value will refer to any payload that was set by the + * `check` callback. It may be read from or written to as needed. + * + * @deprecated use git_filter_stream_fn + */ +typedef int GIT_CALLBACK(git_filter_apply_fn)( + git_filter *self, + void **payload, /* may be read and/or set */ + git_buf *to, + const git_buf *from, + const git_filter_source *src); +#endif + +/** + * Callback to perform the data filtering. + * + * Specified as `filter.stream`, this is a callback that filters data + * in a streaming manner. This function will provide a + * `git_writestream` that will the original data will be written to; + * with that data, the `git_writestream` will then perform the filter + * translation and stream the filtered data out to the `next` location. + */ +typedef int GIT_CALLBACK(git_filter_stream_fn)( + git_writestream **out, + git_filter *self, + void **payload, + const git_filter_source *src, + git_writestream *next); + +/** + * Callback to clean up after filtering has been applied + * + * Specified as `filter.cleanup`, this is an optional callback invoked + * after the filter has been applied. If the `check`, `apply`, or + * `stream` callbacks allocated a `payload` to keep per-source filter + * state, use this callback to free that payload and release resources + * as required. + */ +typedef void GIT_CALLBACK(git_filter_cleanup_fn)( + git_filter *self, + void *payload); + +/** + * Filter structure used to register custom filters. + * + * To associate extra data with a filter, allocate extra data and put the + * `git_filter` struct at the start of your data buffer, then cast the + * `self` pointer to your larger structure when your callback is invoked. + */ +struct git_filter { + /** The `version` field should be set to `GIT_FILTER_VERSION`. */ + unsigned int version; + + /** + * A whitespace-separated list of attribute names to check for this + * filter (e.g. "eol crlf text"). If the attribute name is bare, it + * will be simply loaded and passed to the `check` callback. If it + * has a value (i.e. "name=value"), the attribute must match that + * value for the filter to be applied. The value may be a wildcard + * (eg, "name=*"), in which case the filter will be invoked for any + * value for the given attribute name. See the attribute parameter + * of the `check` callback for the attribute value that was specified. + */ + const char *attributes; + + /** Called when the filter is first used for any file. */ + git_filter_init_fn initialize; + + /** Called when the filter is removed or unregistered from the system. */ + git_filter_shutdown_fn shutdown; + + /** + * Called to determine whether the filter should be invoked for a + * given file. If this function returns `GIT_PASSTHROUGH` then the + * `stream` or `apply` functions will not be invoked and the + * contents will be passed through unmodified. + */ + git_filter_check_fn check; + +#ifdef GIT_DEPRECATE_HARD + void *reserved; +#else + /** + * Provided for backward compatibility; this will apply the + * filter to the given contents in a `git_buf`. Callers should + * provide a `stream` function instead. + */ + git_filter_apply_fn apply; +#endif + + /** + * Called to apply the filter, this function will provide a + * `git_writestream` that will the original data will be + * written to; with that data, the `git_writestream` will then + * perform the filter translation and stream the filtered data + * out to the `next` location. + */ + git_filter_stream_fn stream; + + /** Called when the system is done filtering for a file. */ + git_filter_cleanup_fn cleanup; +}; + +#define GIT_FILTER_VERSION 1 +#define GIT_FILTER_INIT {GIT_FILTER_VERSION} + +/** + * Initializes a `git_filter` with default values. Equivalent to + * creating an instance with GIT_FILTER_INIT. + * + * @param filter the `git_filter` struct to initialize. + * @param version Version the struct; pass `GIT_FILTER_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_filter_init(git_filter *filter, unsigned int version); + +/** + * Register a filter under a given name with a given priority. + * + * As mentioned elsewhere, the initialize callback will not be invoked + * immediately. It is deferred until the filter is used in some way. + * + * A filter's attribute checks and `check` and `stream` (or `apply`) + * callbacks will be issued in order of `priority` on smudge (to + * workdir), and in reverse order of `priority` on clean (to odb). + * + * Two filters are preregistered with libgit2: + * - GIT_FILTER_CRLF with priority 0 + * - GIT_FILTER_IDENT with priority 100 + * + * Currently the filter registry is not thread safe, so any registering or + * deregistering of filters must be done outside of any possible usage of + * the filters (i.e. during application setup or shutdown). + * + * @param name A name by which the filter can be referenced. Attempting + * to register with an in-use name will return GIT_EEXISTS. + * @param filter The filter definition. This pointer will be stored as is + * by libgit2 so it must be a durable allocation (either static + * or on the heap). + * @param priority The priority for filter application + * @return 0 on successful registry, error code <0 on failure + */ +GIT_EXTERN(int) git_filter_register( + const char *name, git_filter *filter, int priority); + +/** + * Remove the filter with the given name + * + * Attempting to remove the builtin libgit2 filters is not permitted and + * will return an error. + * + * Currently the filter registry is not thread safe, so any registering or + * deregistering of filters must be done outside of any possible usage of + * the filters (i.e. during application setup or shutdown). + * + * @param name The name under which the filter was registered + * @return 0 on success, error code <0 on failure + */ +GIT_EXTERN(int) git_filter_unregister(const char *name); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/hashsig.h b/3rdparty/libgit2/include/git2/sys/hashsig.h index 09c19ae..8f36c8f 100644 --- a/3rdparty/libgit2/include/git2/sys/hashsig.h +++ b/3rdparty/libgit2/include/git2/sys/hashsig.h @@ -1,106 +1,106 @@ -/* - * 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_sys_hashsig_h__ -#define INCLUDE_sys_hashsig_h__ - -#include "git2/common.h" - -GIT_BEGIN_DECL - -/** - * Similarity signature of arbitrary text content based on line hashes - */ -typedef struct git_hashsig git_hashsig; - -/** - * Options for hashsig computation - * - * The options GIT_HASHSIG_NORMAL, GIT_HASHSIG_IGNORE_WHITESPACE, - * GIT_HASHSIG_SMART_WHITESPACE are exclusive and should not be combined. - */ -typedef enum { - /** - * Use all data - */ - GIT_HASHSIG_NORMAL = 0, - - /** - * Ignore whitespace - */ - GIT_HASHSIG_IGNORE_WHITESPACE = (1 << 0), - - /** - * Ignore \r and all space after \n - */ - GIT_HASHSIG_SMART_WHITESPACE = (1 << 1), - - /** - * Allow hashing of small files - */ - GIT_HASHSIG_ALLOW_SMALL_FILES = (1 << 2) -} git_hashsig_option_t; - -/** - * Compute a similarity signature for a text buffer - * - * If you have passed the option GIT_HASHSIG_IGNORE_WHITESPACE, then the - * whitespace will be removed from the buffer while it is being processed, - * modifying the buffer in place. Sorry about that! - * - * @param out The computed similarity signature. - * @param buf The input buffer. - * @param buflen The input buffer size. - * @param opts The signature computation options (see above). - * @return 0 on success, GIT_EBUFS if the buffer doesn't contain enough data to - * compute a valid signature (unless GIT_HASHSIG_ALLOW_SMALL_FILES is set), or - * error code. - */ -GIT_EXTERN(int) git_hashsig_create( - git_hashsig **out, - const char *buf, - size_t buflen, - git_hashsig_option_t opts); - -/** - * Compute a similarity signature for a text file - * - * This walks through the file, only loading a maximum of 4K of file data at - * a time. Otherwise, it acts just like `git_hashsig_create`. - * - * @param out The computed similarity signature. - * @param path The path to the input file. - * @param opts The signature computation options (see above). - * @return 0 on success, GIT_EBUFS if the buffer doesn't contain enough data to - * compute a valid signature (unless GIT_HASHSIG_ALLOW_SMALL_FILES is set), or - * error code. - */ -GIT_EXTERN(int) git_hashsig_create_fromfile( - git_hashsig **out, - const char *path, - git_hashsig_option_t opts); - -/** - * Release memory for a content similarity signature - * - * @param sig The similarity signature to free. - */ -GIT_EXTERN(void) git_hashsig_free(git_hashsig *sig); - -/** - * Measure similarity score between two similarity signatures - * - * @param a The first similarity signature to compare. - * @param b The second similarity signature to compare. - * @return [0 to 100] on success as the similarity score, or error code. - */ -GIT_EXTERN(int) git_hashsig_compare( - const git_hashsig *a, - const git_hashsig *b); - -GIT_END_DECL - -#endif +/* + * 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_sys_hashsig_h__ +#define INCLUDE_sys_hashsig_h__ + +#include "git2/common.h" + +GIT_BEGIN_DECL + +/** + * Similarity signature of arbitrary text content based on line hashes + */ +typedef struct git_hashsig git_hashsig; + +/** + * Options for hashsig computation + * + * The options GIT_HASHSIG_NORMAL, GIT_HASHSIG_IGNORE_WHITESPACE, + * GIT_HASHSIG_SMART_WHITESPACE are exclusive and should not be combined. + */ +typedef enum { + /** + * Use all data + */ + GIT_HASHSIG_NORMAL = 0, + + /** + * Ignore whitespace + */ + GIT_HASHSIG_IGNORE_WHITESPACE = (1 << 0), + + /** + * Ignore \r and all space after \n + */ + GIT_HASHSIG_SMART_WHITESPACE = (1 << 1), + + /** + * Allow hashing of small files + */ + GIT_HASHSIG_ALLOW_SMALL_FILES = (1 << 2) +} git_hashsig_option_t; + +/** + * Compute a similarity signature for a text buffer + * + * If you have passed the option GIT_HASHSIG_IGNORE_WHITESPACE, then the + * whitespace will be removed from the buffer while it is being processed, + * modifying the buffer in place. Sorry about that! + * + * @param out The computed similarity signature. + * @param buf The input buffer. + * @param buflen The input buffer size. + * @param opts The signature computation options (see above). + * @return 0 on success, GIT_EBUFS if the buffer doesn't contain enough data to + * compute a valid signature (unless GIT_HASHSIG_ALLOW_SMALL_FILES is set), or + * error code. + */ +GIT_EXTERN(int) git_hashsig_create( + git_hashsig **out, + const char *buf, + size_t buflen, + git_hashsig_option_t opts); + +/** + * Compute a similarity signature for a text file + * + * This walks through the file, only loading a maximum of 4K of file data at + * a time. Otherwise, it acts just like `git_hashsig_create`. + * + * @param out The computed similarity signature. + * @param path The path to the input file. + * @param opts The signature computation options (see above). + * @return 0 on success, GIT_EBUFS if the buffer doesn't contain enough data to + * compute a valid signature (unless GIT_HASHSIG_ALLOW_SMALL_FILES is set), or + * error code. + */ +GIT_EXTERN(int) git_hashsig_create_fromfile( + git_hashsig **out, + const char *path, + git_hashsig_option_t opts); + +/** + * Release memory for a content similarity signature + * + * @param sig The similarity signature to free. + */ +GIT_EXTERN(void) git_hashsig_free(git_hashsig *sig); + +/** + * Measure similarity score between two similarity signatures + * + * @param a The first similarity signature to compare. + * @param b The second similarity signature to compare. + * @return [0 to 100] on success as the similarity score, or error code. + */ +GIT_EXTERN(int) git_hashsig_compare( + const git_hashsig *a, + const git_hashsig *b); + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/sys/index.h b/3rdparty/libgit2/include/git2/sys/index.h index 1f6d93f..b974c08 100644 --- a/3rdparty/libgit2/include/git2/sys/index.h +++ b/3rdparty/libgit2/include/git2/sys/index.h @@ -1,182 +1,182 @@ -/* - * 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_sys_git_index_h__ -#define INCLUDE_sys_git_index_h__ - -#include "git2/common.h" -#include "git2/types.h" - -/** - * @file git2/sys/index.h - * @brief Low-level Git index manipulation routines - * @defgroup git_backend Git custom backend APIs - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** Representation of a rename conflict entry in the index. */ -typedef struct git_index_name_entry { - char *ancestor; - char *ours; - char *theirs; -} git_index_name_entry; - -/** Representation of a resolve undo entry in the index. */ -typedef struct git_index_reuc_entry { - uint32_t mode[3]; - git_oid oid[3]; - char *path; -} git_index_reuc_entry; - -/** @name Conflict Name entry functions - * - * These functions work on rename conflict entries. - */ -/**@{*/ - -/** - * Get the count of filename conflict entries currently in the index. - * - * @param index an existing index object - * @return integer of count of current filename conflict entries - */ -GIT_EXTERN(size_t) git_index_name_entrycount(git_index *index); - -/** - * Get a filename conflict entry from the index. - * - * The returned entry is read-only and should not be modified - * or freed by the caller. - * - * @param index an existing index object - * @param n the position of the entry - * @return a pointer to the filename conflict entry; NULL if out of bounds - */ -GIT_EXTERN(const git_index_name_entry *) git_index_name_get_byindex( - git_index *index, size_t n); - -/** - * Record the filenames involved in a rename conflict. - * - * @param index an existing index object - * @param ancestor the path of the file as it existed in the ancestor - * @param ours the path of the file as it existed in our tree - * @param theirs the path of the file as it existed in their tree - */ -GIT_EXTERN(int) git_index_name_add(git_index *index, - const char *ancestor, const char *ours, const char *theirs); - -/** - * Remove all filename conflict entries. - * - * @param index an existing index object - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_name_clear(git_index *index); - -/**@}*/ - -/** @name Resolve Undo (REUC) index entry manipulation. - * - * These functions work on the Resolve Undo index extension and contains - * data about the original files that led to a merge conflict. - */ -/**@{*/ - -/** - * Get the count of resolve undo entries currently in the index. - * - * @param index an existing index object - * @return integer of count of current resolve undo entries - */ -GIT_EXTERN(size_t) git_index_reuc_entrycount(git_index *index); - -/** - * Finds the resolve undo entry that points to the given path in the Git - * index. - * - * @param at_pos the address to which the position of the reuc entry is written (optional) - * @param index an existing index object - * @param path path to search - * @return 0 if found, < 0 otherwise (GIT_ENOTFOUND) - */ -GIT_EXTERN(int) git_index_reuc_find(size_t *at_pos, git_index *index, const char *path); - -/** - * Get a resolve undo entry from the index. - * - * The returned entry is read-only and should not be modified - * or freed by the caller. - * - * @param index an existing index object - * @param path path to search - * @return the resolve undo entry; NULL if not found - */ -GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_bypath(git_index *index, const char *path); - -/** - * Get a resolve undo entry from the index. - * - * The returned entry is read-only and should not be modified - * or freed by the caller. - * - * @param index an existing index object - * @param n the position of the entry - * @return a pointer to the resolve undo entry; NULL if out of bounds - */ -GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_byindex(git_index *index, size_t n); - -/** - * Adds a resolve undo entry for a file based on the given parameters. - * - * The resolve undo entry contains the OIDs of files that were involved - * in a merge conflict after the conflict has been resolved. This allows - * conflicts to be re-resolved later. - * - * If there exists a resolve undo entry for the given path in the index, - * it will be removed. - * - * This method will fail in bare index instances. - * - * @param index an existing index object - * @param path filename to add - * @param ancestor_mode mode of the ancestor file - * @param ancestor_id oid of the ancestor file - * @param our_mode mode of our file - * @param our_id oid of our file - * @param their_mode mode of their file - * @param their_id oid of their file - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_reuc_add(git_index *index, const char *path, - int ancestor_mode, const git_oid *ancestor_id, - int our_mode, const git_oid *our_id, - int their_mode, const git_oid *their_id); - -/** - * Remove an resolve undo entry from the index - * - * @param index an existing index object - * @param n position of the resolve undo entry to remove - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_reuc_remove(git_index *index, size_t n); - -/** - * Remove all resolve undo entries from the index - * - * @param index an existing index object - * @return 0 or an error code - */ -GIT_EXTERN(int) git_index_reuc_clear(git_index *index); - -/**@}*/ - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_index_h__ +#define INCLUDE_sys_git_index_h__ + +#include "git2/common.h" +#include "git2/types.h" + +/** + * @file git2/sys/index.h + * @brief Low-level Git index manipulation routines + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** Representation of a rename conflict entry in the index. */ +typedef struct git_index_name_entry { + char *ancestor; + char *ours; + char *theirs; +} git_index_name_entry; + +/** Representation of a resolve undo entry in the index. */ +typedef struct git_index_reuc_entry { + uint32_t mode[3]; + git_oid oid[3]; + char *path; +} git_index_reuc_entry; + +/** @name Conflict Name entry functions + * + * These functions work on rename conflict entries. + */ +/**@{*/ + +/** + * Get the count of filename conflict entries currently in the index. + * + * @param index an existing index object + * @return integer of count of current filename conflict entries + */ +GIT_EXTERN(size_t) git_index_name_entrycount(git_index *index); + +/** + * Get a filename conflict entry from the index. + * + * The returned entry is read-only and should not be modified + * or freed by the caller. + * + * @param index an existing index object + * @param n the position of the entry + * @return a pointer to the filename conflict entry; NULL if out of bounds + */ +GIT_EXTERN(const git_index_name_entry *) git_index_name_get_byindex( + git_index *index, size_t n); + +/** + * Record the filenames involved in a rename conflict. + * + * @param index an existing index object + * @param ancestor the path of the file as it existed in the ancestor + * @param ours the path of the file as it existed in our tree + * @param theirs the path of the file as it existed in their tree + */ +GIT_EXTERN(int) git_index_name_add(git_index *index, + const char *ancestor, const char *ours, const char *theirs); + +/** + * Remove all filename conflict entries. + * + * @param index an existing index object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_name_clear(git_index *index); + +/**@}*/ + +/** @name Resolve Undo (REUC) index entry manipulation. + * + * These functions work on the Resolve Undo index extension and contains + * data about the original files that led to a merge conflict. + */ +/**@{*/ + +/** + * Get the count of resolve undo entries currently in the index. + * + * @param index an existing index object + * @return integer of count of current resolve undo entries + */ +GIT_EXTERN(size_t) git_index_reuc_entrycount(git_index *index); + +/** + * Finds the resolve undo entry that points to the given path in the Git + * index. + * + * @param at_pos the address to which the position of the reuc entry is written (optional) + * @param index an existing index object + * @param path path to search + * @return 0 if found, < 0 otherwise (GIT_ENOTFOUND) + */ +GIT_EXTERN(int) git_index_reuc_find(size_t *at_pos, git_index *index, const char *path); + +/** + * Get a resolve undo entry from the index. + * + * The returned entry is read-only and should not be modified + * or freed by the caller. + * + * @param index an existing index object + * @param path path to search + * @return the resolve undo entry; NULL if not found + */ +GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_bypath(git_index *index, const char *path); + +/** + * Get a resolve undo entry from the index. + * + * The returned entry is read-only and should not be modified + * or freed by the caller. + * + * @param index an existing index object + * @param n the position of the entry + * @return a pointer to the resolve undo entry; NULL if out of bounds + */ +GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_byindex(git_index *index, size_t n); + +/** + * Adds a resolve undo entry for a file based on the given parameters. + * + * The resolve undo entry contains the OIDs of files that were involved + * in a merge conflict after the conflict has been resolved. This allows + * conflicts to be re-resolved later. + * + * If there exists a resolve undo entry for the given path in the index, + * it will be removed. + * + * This method will fail in bare index instances. + * + * @param index an existing index object + * @param path filename to add + * @param ancestor_mode mode of the ancestor file + * @param ancestor_id oid of the ancestor file + * @param our_mode mode of our file + * @param our_id oid of our file + * @param their_mode mode of their file + * @param their_id oid of their file + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_reuc_add(git_index *index, const char *path, + int ancestor_mode, const git_oid *ancestor_id, + int our_mode, const git_oid *our_id, + int their_mode, const git_oid *their_id); + +/** + * Remove an resolve undo entry from the index + * + * @param index an existing index object + * @param n position of the resolve undo entry to remove + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_reuc_remove(git_index *index, size_t n); + +/** + * Remove all resolve undo entries from the index + * + * @param index an existing index object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_reuc_clear(git_index *index); + +/**@}*/ + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/mempack.h b/3rdparty/libgit2/include/git2/sys/mempack.h index 17da590..2e90d60 100644 --- a/3rdparty/libgit2/include/git2/sys/mempack.h +++ b/3rdparty/libgit2/include/git2/sys/mempack.h @@ -1,87 +1,87 @@ -/* - * 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_sys_git_odb_mempack_h__ -#define INCLUDE_sys_git_odb_mempack_h__ - -#include "git2/common.h" -#include "git2/types.h" -#include "git2/oid.h" -#include "git2/odb.h" -#include "git2/buffer.h" - -/** - * @file git2/sys/mempack.h - * @brief Custom ODB backend that permits packing objects in-memory - * @defgroup git_backend Git custom backend APIs - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Instantiate a new mempack backend. - * - * The backend must be added to an existing ODB with the highest - * priority. - * - * git_mempack_new(&mempacker); - * git_repository_odb(&odb, repository); - * git_odb_add_backend(odb, mempacker, 999); - * - * Once the backend has been loaded, all writes to the ODB will - * instead be queued in memory, and can be finalized with - * `git_mempack_dump`. - * - * Subsequent reads will also be served from the in-memory store - * to ensure consistency, until the memory store is dumped. - * - * @param out Pointer where to store the ODB backend - * @return 0 on success; error code otherwise - */ -GIT_EXTERN(int) git_mempack_new(git_odb_backend **out); - -/** - * Dump all the queued in-memory writes to a packfile. - * - * The contents of the packfile will be stored in the given buffer. - * It is the caller's responsibility to ensure that the generated - * packfile is available to the repository (e.g. by writing it - * to disk, or doing something crazy like distributing it across - * several copies of the repository over a network). - * - * Once the generated packfile is available to the repository, - * call `git_mempack_reset` to cleanup the memory store. - * - * Calling `git_mempack_reset` before the packfile has been - * written to disk will result in an inconsistent repository - * (the objects in the memory store won't be accessible). - * - * @param pack Buffer where to store the raw packfile - * @param repo The active repository where the backend is loaded - * @param backend The mempack backend - * @return 0 on success; error code otherwise - */ -GIT_EXTERN(int) git_mempack_dump(git_buf *pack, git_repository *repo, git_odb_backend *backend); - -/** - * Reset the memory packer by clearing all the queued objects. - * - * This assumes that `git_mempack_dump` has been called before to - * store all the queued objects into a single packfile. - * - * Alternatively, call `reset` without a previous dump to "undo" - * all the recently written objects, giving transaction-like - * semantics to the Git repository. - * - * @param backend The mempack backend - * @return 0 on success; error code otherwise - */ -GIT_EXTERN(int) git_mempack_reset(git_odb_backend *backend); - -GIT_END_DECL - -#endif +/* + * 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_sys_git_odb_mempack_h__ +#define INCLUDE_sys_git_odb_mempack_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" +#include "git2/odb.h" +#include "git2/buffer.h" + +/** + * @file git2/sys/mempack.h + * @brief Custom ODB backend that permits packing objects in-memory + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Instantiate a new mempack backend. + * + * The backend must be added to an existing ODB with the highest + * priority. + * + * git_mempack_new(&mempacker); + * git_repository_odb(&odb, repository); + * git_odb_add_backend(odb, mempacker, 999); + * + * Once the backend has been loaded, all writes to the ODB will + * instead be queued in memory, and can be finalized with + * `git_mempack_dump`. + * + * Subsequent reads will also be served from the in-memory store + * to ensure consistency, until the memory store is dumped. + * + * @param out Pointer where to store the ODB backend + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_mempack_new(git_odb_backend **out); + +/** + * Dump all the queued in-memory writes to a packfile. + * + * The contents of the packfile will be stored in the given buffer. + * It is the caller's responsibility to ensure that the generated + * packfile is available to the repository (e.g. by writing it + * to disk, or doing something crazy like distributing it across + * several copies of the repository over a network). + * + * Once the generated packfile is available to the repository, + * call `git_mempack_reset` to cleanup the memory store. + * + * Calling `git_mempack_reset` before the packfile has been + * written to disk will result in an inconsistent repository + * (the objects in the memory store won't be accessible). + * + * @param pack Buffer where to store the raw packfile + * @param repo The active repository where the backend is loaded + * @param backend The mempack backend + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_mempack_dump(git_buf *pack, git_repository *repo, git_odb_backend *backend); + +/** + * Reset the memory packer by clearing all the queued objects. + * + * This assumes that `git_mempack_dump` has been called before to + * store all the queued objects into a single packfile. + * + * Alternatively, call `reset` without a previous dump to "undo" + * all the recently written objects, giving transaction-like + * semantics to the Git repository. + * + * @param backend The mempack backend + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_mempack_reset(git_odb_backend *backend); + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/sys/merge.h b/3rdparty/libgit2/include/git2/sys/merge.h index ef4bc5a..5a8843b 100644 --- a/3rdparty/libgit2/include/git2/sys/merge.h +++ b/3rdparty/libgit2/include/git2/sys/merge.h @@ -1,182 +1,182 @@ -/* - * 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_sys_git_merge_h__ -#define INCLUDE_sys_git_merge_h__ - -#include "git2/common.h" -#include "git2/types.h" -#include "git2/index.h" -#include "git2/merge.h" - -/** - * @file git2/sys/merge.h - * @brief Git merge driver backend and plugin routines - * @defgroup git_merge Git merge driver APIs - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -typedef struct git_merge_driver git_merge_driver; - -/** - * Look up a merge driver by name - * - * @param name The name of the merge driver - * @return Pointer to the merge driver object or NULL if not found - */ -GIT_EXTERN(git_merge_driver *) git_merge_driver_lookup(const char *name); - -#define GIT_MERGE_DRIVER_TEXT "text" -#define GIT_MERGE_DRIVER_BINARY "binary" -#define GIT_MERGE_DRIVER_UNION "union" - -/** - * A merge driver source represents the file to be merged - */ -typedef struct git_merge_driver_source git_merge_driver_source; - -/** Get the repository that the source data is coming from. */ -GIT_EXTERN(git_repository *) git_merge_driver_source_repo( - const git_merge_driver_source *src); - -/** Gets the ancestor of the file to merge. */ -GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ancestor( - const git_merge_driver_source *src); - -/** Gets the ours side of the file to merge. */ -GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ours( - const git_merge_driver_source *src); - -/** Gets the theirs side of the file to merge. */ -GIT_EXTERN(const git_index_entry *) git_merge_driver_source_theirs( - const git_merge_driver_source *src); - -/** Gets the merge file options that the merge was invoked with */ -GIT_EXTERN(const git_merge_file_options *) git_merge_driver_source_file_options( - const git_merge_driver_source *src); - - -/** - * Initialize callback on merge driver - * - * Specified as `driver.initialize`, this is an optional callback invoked - * before a merge driver is first used. It will be called once at most - * per library lifetime. - * - * If non-NULL, the merge driver's `initialize` callback will be invoked - * right before the first use of the driver, so you can defer expensive - * initialization operations (in case libgit2 is being used in a way that - * doesn't need the merge driver). - */ -typedef int GIT_CALLBACK(git_merge_driver_init_fn)(git_merge_driver *self); - -/** - * Shutdown callback on merge driver - * - * Specified as `driver.shutdown`, this is an optional callback invoked - * when the merge driver is unregistered or when libgit2 is shutting down. - * It will be called once at most and should release resources as needed. - * This may be called even if the `initialize` callback was not made. - * - * Typically this function will free the `git_merge_driver` object itself. - */ -typedef void GIT_CALLBACK(git_merge_driver_shutdown_fn)(git_merge_driver *self); - -/** - * Callback to perform the merge. - * - * Specified as `driver.apply`, this is the callback that actually does the - * merge. If it can successfully perform a merge, it should populate - * `path_out` with a pointer to the filename to accept, `mode_out` with - * the resultant mode, and `merged_out` with the buffer of the merged file - * and then return 0. If the driver returns `GIT_PASSTHROUGH`, then the - * default merge driver should instead be run. It can also return - * `GIT_EMERGECONFLICT` if the driver is not able to produce a merge result, - * and the file will remain conflicted. Any other errors will fail and - * return to the caller. - * - * The `filter_name` contains the name of the filter that was invoked, as - * specified by the file's attributes. - * - * The `src` contains the data about the file to be merged. - */ -typedef int GIT_CALLBACK(git_merge_driver_apply_fn)( - git_merge_driver *self, - const char **path_out, - uint32_t *mode_out, - git_buf *merged_out, - const char *filter_name, - const git_merge_driver_source *src); - -/** - * Merge driver structure used to register custom merge drivers. - * - * To associate extra data with a driver, allocate extra data and put the - * `git_merge_driver` struct at the start of your data buffer, then cast - * the `self` pointer to your larger structure when your callback is invoked. - */ -struct git_merge_driver { - /** The `version` should be set to `GIT_MERGE_DRIVER_VERSION`. */ - unsigned int version; - - /** Called when the merge driver is first used for any file. */ - git_merge_driver_init_fn initialize; - - /** Called when the merge driver is unregistered from the system. */ - git_merge_driver_shutdown_fn shutdown; - - /** - * Called to merge the contents of a conflict. If this function - * returns `GIT_PASSTHROUGH` then the default (`text`) merge driver - * will instead be invoked. If this function returns - * `GIT_EMERGECONFLICT` then the file will remain conflicted. - */ - git_merge_driver_apply_fn apply; -}; - -#define GIT_MERGE_DRIVER_VERSION 1 - -/** - * Register a merge driver under a given name. - * - * As mentioned elsewhere, the initialize callback will not be invoked - * immediately. It is deferred until the driver is used in some way. - * - * Currently the merge driver registry is not thread safe, so any - * registering or deregistering of merge drivers must be done outside of - * any possible usage of the drivers (i.e. during application setup or - * shutdown). - * - * @param name The name of this driver to match an attribute. Attempting - * to register with an in-use name will return GIT_EEXISTS. - * @param driver The merge driver definition. This pointer will be stored - * as is by libgit2 so it must be a durable allocation (either - * static or on the heap). - * @return 0 on successful registry, error code <0 on failure - */ -GIT_EXTERN(int) git_merge_driver_register( - const char *name, git_merge_driver *driver); - -/** - * Remove the merge driver with the given name. - * - * Attempting to remove the builtin libgit2 merge drivers is not permitted - * and will return an error. - * - * Currently the merge driver registry is not thread safe, so any - * registering or deregistering of drivers must be done outside of any - * possible usage of the drivers (i.e. during application setup or shutdown). - * - * @param name The name under which the merge driver was registered - * @return 0 on success, error code <0 on failure - */ -GIT_EXTERN(int) git_merge_driver_unregister(const char *name); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_merge_h__ +#define INCLUDE_sys_git_merge_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/index.h" +#include "git2/merge.h" + +/** + * @file git2/sys/merge.h + * @brief Git merge driver backend and plugin routines + * @defgroup git_merge Git merge driver APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +typedef struct git_merge_driver git_merge_driver; + +/** + * Look up a merge driver by name + * + * @param name The name of the merge driver + * @return Pointer to the merge driver object or NULL if not found + */ +GIT_EXTERN(git_merge_driver *) git_merge_driver_lookup(const char *name); + +#define GIT_MERGE_DRIVER_TEXT "text" +#define GIT_MERGE_DRIVER_BINARY "binary" +#define GIT_MERGE_DRIVER_UNION "union" + +/** + * A merge driver source represents the file to be merged + */ +typedef struct git_merge_driver_source git_merge_driver_source; + +/** Get the repository that the source data is coming from. */ +GIT_EXTERN(git_repository *) git_merge_driver_source_repo( + const git_merge_driver_source *src); + +/** Gets the ancestor of the file to merge. */ +GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ancestor( + const git_merge_driver_source *src); + +/** Gets the ours side of the file to merge. */ +GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ours( + const git_merge_driver_source *src); + +/** Gets the theirs side of the file to merge. */ +GIT_EXTERN(const git_index_entry *) git_merge_driver_source_theirs( + const git_merge_driver_source *src); + +/** Gets the merge file options that the merge was invoked with */ +GIT_EXTERN(const git_merge_file_options *) git_merge_driver_source_file_options( + const git_merge_driver_source *src); + + +/** + * Initialize callback on merge driver + * + * Specified as `driver.initialize`, this is an optional callback invoked + * before a merge driver is first used. It will be called once at most + * per library lifetime. + * + * If non-NULL, the merge driver's `initialize` callback will be invoked + * right before the first use of the driver, so you can defer expensive + * initialization operations (in case libgit2 is being used in a way that + * doesn't need the merge driver). + */ +typedef int GIT_CALLBACK(git_merge_driver_init_fn)(git_merge_driver *self); + +/** + * Shutdown callback on merge driver + * + * Specified as `driver.shutdown`, this is an optional callback invoked + * when the merge driver is unregistered or when libgit2 is shutting down. + * It will be called once at most and should release resources as needed. + * This may be called even if the `initialize` callback was not made. + * + * Typically this function will free the `git_merge_driver` object itself. + */ +typedef void GIT_CALLBACK(git_merge_driver_shutdown_fn)(git_merge_driver *self); + +/** + * Callback to perform the merge. + * + * Specified as `driver.apply`, this is the callback that actually does the + * merge. If it can successfully perform a merge, it should populate + * `path_out` with a pointer to the filename to accept, `mode_out` with + * the resultant mode, and `merged_out` with the buffer of the merged file + * and then return 0. If the driver returns `GIT_PASSTHROUGH`, then the + * default merge driver should instead be run. It can also return + * `GIT_EMERGECONFLICT` if the driver is not able to produce a merge result, + * and the file will remain conflicted. Any other errors will fail and + * return to the caller. + * + * The `filter_name` contains the name of the filter that was invoked, as + * specified by the file's attributes. + * + * The `src` contains the data about the file to be merged. + */ +typedef int GIT_CALLBACK(git_merge_driver_apply_fn)( + git_merge_driver *self, + const char **path_out, + uint32_t *mode_out, + git_buf *merged_out, + const char *filter_name, + const git_merge_driver_source *src); + +/** + * Merge driver structure used to register custom merge drivers. + * + * To associate extra data with a driver, allocate extra data and put the + * `git_merge_driver` struct at the start of your data buffer, then cast + * the `self` pointer to your larger structure when your callback is invoked. + */ +struct git_merge_driver { + /** The `version` should be set to `GIT_MERGE_DRIVER_VERSION`. */ + unsigned int version; + + /** Called when the merge driver is first used for any file. */ + git_merge_driver_init_fn initialize; + + /** Called when the merge driver is unregistered from the system. */ + git_merge_driver_shutdown_fn shutdown; + + /** + * Called to merge the contents of a conflict. If this function + * returns `GIT_PASSTHROUGH` then the default (`text`) merge driver + * will instead be invoked. If this function returns + * `GIT_EMERGECONFLICT` then the file will remain conflicted. + */ + git_merge_driver_apply_fn apply; +}; + +#define GIT_MERGE_DRIVER_VERSION 1 + +/** + * Register a merge driver under a given name. + * + * As mentioned elsewhere, the initialize callback will not be invoked + * immediately. It is deferred until the driver is used in some way. + * + * Currently the merge driver registry is not thread safe, so any + * registering or deregistering of merge drivers must be done outside of + * any possible usage of the drivers (i.e. during application setup or + * shutdown). + * + * @param name The name of this driver to match an attribute. Attempting + * to register with an in-use name will return GIT_EEXISTS. + * @param driver The merge driver definition. This pointer will be stored + * as is by libgit2 so it must be a durable allocation (either + * static or on the heap). + * @return 0 on successful registry, error code <0 on failure + */ +GIT_EXTERN(int) git_merge_driver_register( + const char *name, git_merge_driver *driver); + +/** + * Remove the merge driver with the given name. + * + * Attempting to remove the builtin libgit2 merge drivers is not permitted + * and will return an error. + * + * Currently the merge driver registry is not thread safe, so any + * registering or deregistering of drivers must be done outside of any + * possible usage of the drivers (i.e. during application setup or shutdown). + * + * @param name The name under which the merge driver was registered + * @return 0 on success, error code <0 on failure + */ +GIT_EXTERN(int) git_merge_driver_unregister(const char *name); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/midx.h b/3rdparty/libgit2/include/git2/sys/midx.h index 3a87484..a14b05e 100644 --- a/3rdparty/libgit2/include/git2/sys/midx.h +++ b/3rdparty/libgit2/include/git2/sys/midx.h @@ -1,78 +1,78 @@ -/* - * 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_sys_git_midx_h__ -#define INCLUDE_sys_git_midx_h__ - -#include "git2/common.h" -#include "git2/types.h" - -/** - * @file git2/midx.h - * @brief Git multi-pack-index routines - * @defgroup git_midx Git multi-pack-index routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Create a new writer for `multi-pack-index` files. - * - * @param out location to store the writer pointer. - * @param pack_dir the directory where the `.pack` and `.idx` files are. The - * `multi-pack-index` file will be written in this directory, too. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_midx_writer_new( - git_midx_writer **out, - const char *pack_dir -#ifdef GIT_EXPERIMENTAL_SHA256 - , git_oid_t oid_type -#endif - ); - -/** - * Free the multi-pack-index writer and its resources. - * - * @param w the writer to free. If NULL no action is taken. - */ -GIT_EXTERN(void) git_midx_writer_free(git_midx_writer *w); - -/** - * Add an `.idx` file to the writer. - * - * @param w the writer - * @param idx_path the path of an `.idx` file. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_midx_writer_add( - git_midx_writer *w, - const char *idx_path); - -/** - * Write a `multi-pack-index` file to a file. - * - * @param w the writer - * @return 0 or an error code - */ -GIT_EXTERN(int) git_midx_writer_commit( - git_midx_writer *w); - -/** - * Dump the contents of the `multi-pack-index` to an in-memory buffer. - * - * @param midx Buffer where to store the contents of the `multi-pack-index`. - * @param w the writer - * @return 0 or an error code - */ -GIT_EXTERN(int) git_midx_writer_dump( - git_buf *midx, - git_midx_writer *w); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_midx_h__ +#define INCLUDE_sys_git_midx_h__ + +#include "git2/common.h" +#include "git2/types.h" + +/** + * @file git2/midx.h + * @brief Git multi-pack-index routines + * @defgroup git_midx Git multi-pack-index routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a new writer for `multi-pack-index` files. + * + * @param out location to store the writer pointer. + * @param pack_dir the directory where the `.pack` and `.idx` files are. The + * `multi-pack-index` file will be written in this directory, too. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_midx_writer_new( + git_midx_writer **out, + const char *pack_dir +#ifdef GIT_EXPERIMENTAL_SHA256 + , git_oid_t oid_type +#endif + ); + +/** + * Free the multi-pack-index writer and its resources. + * + * @param w the writer to free. If NULL no action is taken. + */ +GIT_EXTERN(void) git_midx_writer_free(git_midx_writer *w); + +/** + * Add an `.idx` file to the writer. + * + * @param w the writer + * @param idx_path the path of an `.idx` file. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_midx_writer_add( + git_midx_writer *w, + const char *idx_path); + +/** + * Write a `multi-pack-index` file to a file. + * + * @param w the writer + * @return 0 or an error code + */ +GIT_EXTERN(int) git_midx_writer_commit( + git_midx_writer *w); + +/** + * Dump the contents of the `multi-pack-index` to an in-memory buffer. + * + * @param midx Buffer where to store the contents of the `multi-pack-index`. + * @param w the writer + * @return 0 or an error code + */ +GIT_EXTERN(int) git_midx_writer_dump( + git_buf *midx, + git_midx_writer *w); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/odb_backend.h b/3rdparty/libgit2/include/git2/sys/odb_backend.h index c42abd3..e317012 100644 --- a/3rdparty/libgit2/include/git2/sys/odb_backend.h +++ b/3rdparty/libgit2/include/git2/sys/odb_backend.h @@ -1,172 +1,172 @@ -/* - * 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_sys_git_odb_backend_h__ -#define INCLUDE_sys_git_odb_backend_h__ - -#include "git2/common.h" -#include "git2/types.h" -#include "git2/oid.h" -#include "git2/odb.h" - -/** - * @file git2/sys/backend.h - * @brief Git custom backend implementors functions - * @defgroup git_backend Git custom backend APIs - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * An instance for a custom backend - */ -struct git_odb_backend { - unsigned int version; - git_odb *odb; - - /* read and read_prefix each return to libgit2 a buffer which - * will be freed later. The buffer should be allocated using - * the function git_odb_backend_data_alloc to ensure that libgit2 - * can safely free it later. */ - int GIT_CALLBACK(read)( - void **, size_t *, git_object_t *, git_odb_backend *, const git_oid *); - - /* To find a unique object given a prefix of its oid. The oid given - * must be so that the remaining (GIT_OID_SHA1_HEXSIZE - len)*4 bits are 0s. - */ - int GIT_CALLBACK(read_prefix)( - git_oid *, void **, size_t *, git_object_t *, - git_odb_backend *, const git_oid *, size_t); - - int GIT_CALLBACK(read_header)( - size_t *, git_object_t *, git_odb_backend *, const git_oid *); - - /** - * Write an object into the backend. The id of the object has - * already been calculated and is passed in. - */ - int GIT_CALLBACK(write)( - git_odb_backend *, const git_oid *, const void *, size_t, git_object_t); - - int GIT_CALLBACK(writestream)( - git_odb_stream **, git_odb_backend *, git_object_size_t, git_object_t); - - int GIT_CALLBACK(readstream)( - git_odb_stream **, size_t *, git_object_t *, - git_odb_backend *, const git_oid *); - - int GIT_CALLBACK(exists)( - git_odb_backend *, const git_oid *); - - int GIT_CALLBACK(exists_prefix)( - git_oid *, git_odb_backend *, const git_oid *, size_t); - - /** - * If the backend implements a refreshing mechanism, it should be exposed - * through this endpoint. Each call to `git_odb_refresh()` will invoke it. - * - * The odb layer will automatically call this when needed on failed - * lookups (ie. `exists()`, `read()`, `read_header()`). - */ - int GIT_CALLBACK(refresh)(git_odb_backend *); - - int GIT_CALLBACK(foreach)( - git_odb_backend *, git_odb_foreach_cb cb, void *payload); - - int GIT_CALLBACK(writepack)( - git_odb_writepack **, git_odb_backend *, git_odb *odb, - git_indexer_progress_cb progress_cb, void *progress_payload); - - /** - * If the backend supports pack files, this will create a - * `multi-pack-index` file which will contain an index of all objects - * across all the `.pack` files. - */ - int GIT_CALLBACK(writemidx)(git_odb_backend *); - - /** - * "Freshens" an already existing object, updating its last-used - * time. This occurs when `git_odb_write` was called, but the - * object already existed (and will not be re-written). The - * underlying implementation may want to update last-used timestamps. - * - * If callers implement this, they should return `0` if the object - * exists and was freshened, and non-zero otherwise. - */ - int GIT_CALLBACK(freshen)(git_odb_backend *, const git_oid *); - - /** - * Frees any resources held by the odb (including the `git_odb_backend` - * itself). An odb backend implementation must provide this function. - */ - void GIT_CALLBACK(free)(git_odb_backend *); -}; - -#define GIT_ODB_BACKEND_VERSION 1 -#define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION} - -/** - * Initializes a `git_odb_backend` with default values. Equivalent to - * creating an instance with GIT_ODB_BACKEND_INIT. - * - * @param backend the `git_odb_backend` struct to initialize. - * @param version Version the struct; pass `GIT_ODB_BACKEND_VERSION` - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_odb_init_backend( - git_odb_backend *backend, - unsigned int version); - -/** - * Allocate data for an ODB object. Custom ODB backends may use this - * to provide data back to the ODB from their read function. This - * memory should not be freed once it is returned to libgit2. If a - * custom ODB uses this function but encounters an error and does not - * return this data to libgit2, then they should use the corresponding - * git_odb_backend_data_free function. - * - * @param backend the ODB backend that is allocating this memory - * @param len the number of bytes to allocate - * @return the allocated buffer on success or NULL if out of memory - */ -GIT_EXTERN(void *) git_odb_backend_data_alloc(git_odb_backend *backend, size_t len); - -/** - * Frees custom allocated ODB data. This should only be called when - * memory allocated using git_odb_backend_data_alloc is not returned - * to libgit2 because the backend encountered an error in the read - * function after allocation and did not return this data to libgit2. - * - * @param backend the ODB backend that is freeing this memory - * @param data the buffer to free - */ -GIT_EXTERN(void) git_odb_backend_data_free(git_odb_backend *backend, void *data); - - -/* - * Users can avoid deprecated functions by defining `GIT_DEPRECATE_HARD`. - */ -#ifndef GIT_DEPRECATE_HARD - -/** - * Allocate memory for an ODB object from a custom backend. This is - * an alias of `git_odb_backend_data_alloc` and is preserved for - * backward compatibility. - * - * This function is deprecated, but there is no plan to remove this - * function at this time. - * - * @deprecated git_odb_backend_data_alloc - * @see git_odb_backend_data_alloc - */ -GIT_EXTERN(void *) git_odb_backend_malloc(git_odb_backend *backend, size_t len); - -#endif - -GIT_END_DECL - -#endif +/* + * 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_sys_git_odb_backend_h__ +#define INCLUDE_sys_git_odb_backend_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" +#include "git2/odb.h" + +/** + * @file git2/sys/backend.h + * @brief Git custom backend implementors functions + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * An instance for a custom backend + */ +struct git_odb_backend { + unsigned int version; + git_odb *odb; + + /* read and read_prefix each return to libgit2 a buffer which + * will be freed later. The buffer should be allocated using + * the function git_odb_backend_data_alloc to ensure that libgit2 + * can safely free it later. */ + int GIT_CALLBACK(read)( + void **, size_t *, git_object_t *, git_odb_backend *, const git_oid *); + + /* To find a unique object given a prefix of its oid. The oid given + * must be so that the remaining (GIT_OID_SHA1_HEXSIZE - len)*4 bits are 0s. + */ + int GIT_CALLBACK(read_prefix)( + git_oid *, void **, size_t *, git_object_t *, + git_odb_backend *, const git_oid *, size_t); + + int GIT_CALLBACK(read_header)( + size_t *, git_object_t *, git_odb_backend *, const git_oid *); + + /** + * Write an object into the backend. The id of the object has + * already been calculated and is passed in. + */ + int GIT_CALLBACK(write)( + git_odb_backend *, const git_oid *, const void *, size_t, git_object_t); + + int GIT_CALLBACK(writestream)( + git_odb_stream **, git_odb_backend *, git_object_size_t, git_object_t); + + int GIT_CALLBACK(readstream)( + git_odb_stream **, size_t *, git_object_t *, + git_odb_backend *, const git_oid *); + + int GIT_CALLBACK(exists)( + git_odb_backend *, const git_oid *); + + int GIT_CALLBACK(exists_prefix)( + git_oid *, git_odb_backend *, const git_oid *, size_t); + + /** + * If the backend implements a refreshing mechanism, it should be exposed + * through this endpoint. Each call to `git_odb_refresh()` will invoke it. + * + * The odb layer will automatically call this when needed on failed + * lookups (ie. `exists()`, `read()`, `read_header()`). + */ + int GIT_CALLBACK(refresh)(git_odb_backend *); + + int GIT_CALLBACK(foreach)( + git_odb_backend *, git_odb_foreach_cb cb, void *payload); + + int GIT_CALLBACK(writepack)( + git_odb_writepack **, git_odb_backend *, git_odb *odb, + git_indexer_progress_cb progress_cb, void *progress_payload); + + /** + * If the backend supports pack files, this will create a + * `multi-pack-index` file which will contain an index of all objects + * across all the `.pack` files. + */ + int GIT_CALLBACK(writemidx)(git_odb_backend *); + + /** + * "Freshens" an already existing object, updating its last-used + * time. This occurs when `git_odb_write` was called, but the + * object already existed (and will not be re-written). The + * underlying implementation may want to update last-used timestamps. + * + * If callers implement this, they should return `0` if the object + * exists and was freshened, and non-zero otherwise. + */ + int GIT_CALLBACK(freshen)(git_odb_backend *, const git_oid *); + + /** + * Frees any resources held by the odb (including the `git_odb_backend` + * itself). An odb backend implementation must provide this function. + */ + void GIT_CALLBACK(free)(git_odb_backend *); +}; + +#define GIT_ODB_BACKEND_VERSION 1 +#define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION} + +/** + * Initializes a `git_odb_backend` with default values. Equivalent to + * creating an instance with GIT_ODB_BACKEND_INIT. + * + * @param backend the `git_odb_backend` struct to initialize. + * @param version Version the struct; pass `GIT_ODB_BACKEND_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_odb_init_backend( + git_odb_backend *backend, + unsigned int version); + +/** + * Allocate data for an ODB object. Custom ODB backends may use this + * to provide data back to the ODB from their read function. This + * memory should not be freed once it is returned to libgit2. If a + * custom ODB uses this function but encounters an error and does not + * return this data to libgit2, then they should use the corresponding + * git_odb_backend_data_free function. + * + * @param backend the ODB backend that is allocating this memory + * @param len the number of bytes to allocate + * @return the allocated buffer on success or NULL if out of memory + */ +GIT_EXTERN(void *) git_odb_backend_data_alloc(git_odb_backend *backend, size_t len); + +/** + * Frees custom allocated ODB data. This should only be called when + * memory allocated using git_odb_backend_data_alloc is not returned + * to libgit2 because the backend encountered an error in the read + * function after allocation and did not return this data to libgit2. + * + * @param backend the ODB backend that is freeing this memory + * @param data the buffer to free + */ +GIT_EXTERN(void) git_odb_backend_data_free(git_odb_backend *backend, void *data); + + +/* + * Users can avoid deprecated functions by defining `GIT_DEPRECATE_HARD`. + */ +#ifndef GIT_DEPRECATE_HARD + +/** + * Allocate memory for an ODB object from a custom backend. This is + * an alias of `git_odb_backend_data_alloc` and is preserved for + * backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated git_odb_backend_data_alloc + * @see git_odb_backend_data_alloc + */ +GIT_EXTERN(void *) git_odb_backend_malloc(git_odb_backend *backend, size_t len); + +#endif + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/sys/openssl.h b/3rdparty/libgit2/include/git2/sys/openssl.h index b41c55c..a4cd9ea 100644 --- a/3rdparty/libgit2/include/git2/sys/openssl.h +++ b/3rdparty/libgit2/include/git2/sys/openssl.h @@ -1,38 +1,38 @@ -/* - * 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_openssl_h__ -#define INCLUDE_git_openssl_h__ - -#include "git2/common.h" - -GIT_BEGIN_DECL - -/** - * Initialize the OpenSSL locks - * - * OpenSSL requires the application to determine how it performs - * locking. - * - * This is a last-resort convenience function which libgit2 provides for - * allocating and initializing the locks as well as setting the - * locking function to use the system's native locking functions. - * - * The locking function will be cleared and the memory will be freed - * when you call git_threads_sutdown(). - * - * If your programming language has an OpenSSL package/bindings, it - * likely sets up locking. You should very strongly prefer that over - * this function. - * - * @return 0 on success, -1 if there are errors or if libgit2 was not - * built with OpenSSL and threading support. - */ -GIT_EXTERN(int) git_openssl_set_locking(void); - -GIT_END_DECL -#endif - +/* + * 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_openssl_h__ +#define INCLUDE_git_openssl_h__ + +#include "git2/common.h" + +GIT_BEGIN_DECL + +/** + * Initialize the OpenSSL locks + * + * OpenSSL requires the application to determine how it performs + * locking. + * + * This is a last-resort convenience function which libgit2 provides for + * allocating and initializing the locks as well as setting the + * locking function to use the system's native locking functions. + * + * The locking function will be cleared and the memory will be freed + * when you call git_threads_sutdown(). + * + * If your programming language has an OpenSSL package/bindings, it + * likely sets up locking. You should very strongly prefer that over + * this function. + * + * @return 0 on success, -1 if there are errors or if libgit2 was not + * built with OpenSSL and threading support. + */ +GIT_EXTERN(int) git_openssl_set_locking(void); + +GIT_END_DECL +#endif + diff --git a/3rdparty/libgit2/include/git2/sys/path.h b/3rdparty/libgit2/include/git2/sys/path.h index 2a0c7e0..91a82d2 100644 --- a/3rdparty/libgit2/include/git2/sys/path.h +++ b/3rdparty/libgit2/include/git2/sys/path.h @@ -1,64 +1,64 @@ -/* - * 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_sys_git_path_h__ -#define INCLUDE_sys_git_path_h__ - -#include "git2/common.h" - -GIT_BEGIN_DECL - -/** - * The kinds of git-specific files we know about. - * - * The order needs to stay the same to not break the `gitfiles` - * array in path.c - */ -typedef enum { - /** Check for the .gitignore file */ - GIT_PATH_GITFILE_GITIGNORE, - /** Check for the .gitmodules file */ - GIT_PATH_GITFILE_GITMODULES, - /** Check for the .gitattributes file */ - GIT_PATH_GITFILE_GITATTRIBUTES -} git_path_gitfile; - -/** - * The kinds of checks to perform according to which filesystem we are trying to - * protect. - */ -typedef enum { - /** Do both NTFS- and HFS-specific checks */ - GIT_PATH_FS_GENERIC, - /** Do NTFS-specific checks only */ - GIT_PATH_FS_NTFS, - /** Do HFS-specific checks only */ - GIT_PATH_FS_HFS -} git_path_fs; - -/** - * Check whether a path component corresponds to a .git$SUFFIX - * file. - * - * As some filesystems do special things to filenames when - * writing files to disk, you cannot always do a plain string - * comparison to verify whether a file name matches an expected - * path or not. This function can do the comparison for you, - * depending on the filesystem you're on. - * - * @param path the path component to check - * @param pathlen the length of `path` that is to be checked - * @param gitfile which file to check against - * @param fs which filesystem-specific checks to use - * @return 0 in case the file does not match, a positive value if - * it does; -1 in case of an error - */ -GIT_EXTERN(int) git_path_is_gitfile(const char *path, size_t pathlen, git_path_gitfile gitfile, git_path_fs fs); - -GIT_END_DECL - -#endif /* INCLUDE_sys_git_path */ +/* + * 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_sys_git_path_h__ +#define INCLUDE_sys_git_path_h__ + +#include "git2/common.h" + +GIT_BEGIN_DECL + +/** + * The kinds of git-specific files we know about. + * + * The order needs to stay the same to not break the `gitfiles` + * array in path.c + */ +typedef enum { + /** Check for the .gitignore file */ + GIT_PATH_GITFILE_GITIGNORE, + /** Check for the .gitmodules file */ + GIT_PATH_GITFILE_GITMODULES, + /** Check for the .gitattributes file */ + GIT_PATH_GITFILE_GITATTRIBUTES +} git_path_gitfile; + +/** + * The kinds of checks to perform according to which filesystem we are trying to + * protect. + */ +typedef enum { + /** Do both NTFS- and HFS-specific checks */ + GIT_PATH_FS_GENERIC, + /** Do NTFS-specific checks only */ + GIT_PATH_FS_NTFS, + /** Do HFS-specific checks only */ + GIT_PATH_FS_HFS +} git_path_fs; + +/** + * Check whether a path component corresponds to a .git$SUFFIX + * file. + * + * As some filesystems do special things to filenames when + * writing files to disk, you cannot always do a plain string + * comparison to verify whether a file name matches an expected + * path or not. This function can do the comparison for you, + * depending on the filesystem you're on. + * + * @param path the path component to check + * @param pathlen the length of `path` that is to be checked + * @param gitfile which file to check against + * @param fs which filesystem-specific checks to use + * @return 0 in case the file does not match, a positive value if + * it does; -1 in case of an error + */ +GIT_EXTERN(int) git_path_is_gitfile(const char *path, size_t pathlen, git_path_gitfile gitfile, git_path_fs fs); + +GIT_END_DECL + +#endif /* INCLUDE_sys_git_path */ diff --git a/3rdparty/libgit2/include/git2/sys/refdb_backend.h b/3rdparty/libgit2/include/git2/sys/refdb_backend.h index c31e26d..b0d227f 100644 --- a/3rdparty/libgit2/include/git2/sys/refdb_backend.h +++ b/3rdparty/libgit2/include/git2/sys/refdb_backend.h @@ -1,361 +1,361 @@ -/* - * 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_sys_git_refdb_backend_h__ -#define INCLUDE_sys_git_refdb_backend_h__ - -#include "git2/common.h" -#include "git2/types.h" -#include "git2/oid.h" - -/** - * @file git2/refdb_backend.h - * @brief Git custom refs backend functions - * @defgroup git_refdb_backend Git custom refs backend API - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - - -/** - * Every backend's iterator must have a pointer to itself as the first - * element, so the API can talk to it. You'd define your iterator as - * - * struct my_iterator { - * git_reference_iterator parent; - * ... - * } - * - * and assign `iter->parent.backend` to your `git_refdb_backend`. - */ -struct git_reference_iterator { - git_refdb *db; - - /** - * Return the current reference and advance the iterator. - */ - int GIT_CALLBACK(next)( - git_reference **ref, - git_reference_iterator *iter); - - /** - * Return the name of the current reference and advance the iterator - */ - int GIT_CALLBACK(next_name)( - const char **ref_name, - git_reference_iterator *iter); - - /** - * Free the iterator - */ - void GIT_CALLBACK(free)( - git_reference_iterator *iter); -}; - -/** An instance for a custom backend */ -struct git_refdb_backend { - unsigned int version; /**< The backend API version */ - - /** - * Queries the refdb backend for the existence of a reference. - * - * A refdb implementation must provide this function. - * - * @arg exists The implementation shall set this to `0` if a ref does - * not exist, otherwise to `1`. - * @arg ref_name The reference's name that should be checked for - * existence. - * @return `0` on success, a negative error value code. - */ - int GIT_CALLBACK(exists)( - int *exists, - git_refdb_backend *backend, - const char *ref_name); - - /** - * Queries the refdb backend for a given reference. - * - * A refdb implementation must provide this function. - * - * @arg out The implementation shall set this to the allocated - * reference, if it could be found, otherwise to `NULL`. - * @arg ref_name The reference's name that should be checked for - * existence. - * @return `0` on success, `GIT_ENOTFOUND` if the reference does - * exist, otherwise a negative error code. - */ - int GIT_CALLBACK(lookup)( - git_reference **out, - git_refdb_backend *backend, - const char *ref_name); - - /** - * Allocate an iterator object for the backend. - * - * A refdb implementation must provide this function. - * - * @arg out The implementation shall set this to the allocated - * reference iterator. A custom structure may be used with an - * embedded `git_reference_iterator` structure. Both `next` - * and `next_name` functions of `git_reference_iterator` need - * to be populated. - * @arg glob A pattern to filter references by. If given, the iterator - * shall only return references that match the glob when - * passed to `wildmatch`. - * @return `0` on success, otherwise a negative error code. - */ - int GIT_CALLBACK(iterator)( - git_reference_iterator **iter, - struct git_refdb_backend *backend, - const char *glob); - - /** - * Writes the given reference to the refdb. - * - * A refdb implementation must provide this function. - * - * @arg ref The reference to persist. May either be a symbolic or - * direct reference. - * @arg force Whether to write the reference if a reference with the - * same name already exists. - * @arg who The person updating the reference. Shall be used to create - * a reflog entry. - * @arg message The message detailing what kind of reference update is - * performed. Shall be used to create a reflog entry. - * @arg old If not `NULL` and `force` is not set, then the - * implementation needs to ensure that the reference is currently at - * the given OID before writing the new value. If both `old` - * and `old_target` are `NULL`, then the reference should not - * exist at the point of writing. - * @arg old_target If not `NULL` and `force` is not set, then the - * implementation needs to ensure that the symbolic - * reference is currently at the given target before - * writing the new value. If both `old` and - * `old_target` are `NULL`, then the reference should - * not exist at the point of writing. - * @return `0` on success, otherwise a negative error code. - */ - int GIT_CALLBACK(write)(git_refdb_backend *backend, - const git_reference *ref, int force, - const git_signature *who, const char *message, - const git_oid *old, const char *old_target); - - /** - * Rename a reference in the refdb. - * - * A refdb implementation must provide this function. - * - * @arg out The implementation shall set this to the newly created - * reference or `NULL` on error. - * @arg old_name The current name of the reference that is to be renamed. - * @arg new_name The new name that the old reference shall be renamed to. - * @arg force Whether to write the reference if a reference with the - * target name already exists. - * @arg who The person updating the reference. Shall be used to create - * a reflog entry. - * @arg message The message detailing what kind of reference update is - * performed. Shall be used to create a reflog entry. - * @return `0` on success, otherwise a negative error code. - */ - int GIT_CALLBACK(rename)( - git_reference **out, git_refdb_backend *backend, - const char *old_name, const char *new_name, int force, - const git_signature *who, const char *message); - - /** - * Deletes the given reference from the refdb. - * - * If it exists, its reflog should be deleted as well. - * - * A refdb implementation must provide this function. - * - * @arg ref_name The name of the reference name that shall be deleted. - * @arg old_id If not `NULL` and `force` is not set, then the - * implementation needs to ensure that the reference is currently at - * the given OID before writing the new value. - * @arg old_target If not `NULL` and `force` is not set, then the - * implementation needs to ensure that the symbolic - * reference is currently at the given target before - * writing the new value. - * @return `0` on success, otherwise a negative error code. - */ - int GIT_CALLBACK(del)(git_refdb_backend *backend, const char *ref_name, const git_oid *old_id, const char *old_target); - - /** - * Suggests that the given refdb compress or optimize its references. - * - * This mechanism is implementation specific. For on-disk reference - * databases, this may pack all loose references. - * - * A refdb implementation may provide this function; if it is not - * provided, nothing will be done. - * - * @return `0` on success a negative error code otherwise - */ - int GIT_CALLBACK(compress)(git_refdb_backend *backend); - - /** - * Query whether a particular reference has a log (may be empty) - * - * Shall return 1 if it has a reflog, 0 it it doesn't and negative in - * case an error occurred. - * - * A refdb implementation must provide this function. - * - * @return `0` on success, `1` if the reflog for the given reference - * exists, a negative error code otherwise - */ - int GIT_CALLBACK(has_log)(git_refdb_backend *backend, const char *refname); - - /** - * Make sure a particular reference will have a reflog which - * will be appended to on writes. - * - * A refdb implementation must provide this function. - * - * @return `0` on success, a negative error code otherwise - */ - int GIT_CALLBACK(ensure_log)(git_refdb_backend *backend, const char *refname); - - /** - * Frees any resources held by the refdb (including the `git_refdb_backend` - * itself). - * - * A refdb backend implementation must provide this function. - */ - void GIT_CALLBACK(free)(git_refdb_backend *backend); - - /** - * Read the reflog for the given reference name. - * - * A refdb implementation must provide this function. - * - * @return `0` on success, a negative error code otherwise - */ - int GIT_CALLBACK(reflog_read)(git_reflog **out, git_refdb_backend *backend, const char *name); - - /** - * Write a reflog to disk. - * - * A refdb implementation must provide this function. - * - * @arg reflog The complete reference log for a given reference. Note - * that this may contain entries that have already been - * written to disk. - * @return `0` on success, a negative error code otherwise - */ - int GIT_CALLBACK(reflog_write)(git_refdb_backend *backend, git_reflog *reflog); - - /** - * Rename a reflog. - * - * A refdb implementation must provide this function. - * - * @arg old_name The name of old reference whose reflog shall be renamed from. - * @arg new_name The name of new reference whose reflog shall be renamed to. - * @return `0` on success, a negative error code otherwise - */ - int GIT_CALLBACK(reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name); - - /** - * Remove a reflog. - * - * A refdb implementation must provide this function. - * - * @arg name The name of the reference whose reflog shall be deleted. - * @return `0` on success, a negative error code otherwise - */ - int GIT_CALLBACK(reflog_delete)(git_refdb_backend *backend, const char *name); - - /** - * Lock a reference. - * - * A refdb implementation may provide this function; if it is not - * provided, the transaction API will fail to work. - * - * @arg payload_out Opaque parameter that will be passed verbosely to - * `unlock`. - * @arg refname Reference that shall be locked. - * @return `0` on success, a negative error code otherwise - */ - int GIT_CALLBACK(lock)(void **payload_out, git_refdb_backend *backend, const char *refname); - - /** - * Unlock a reference. - * - * Only one of target or symbolic_target will be set. - * `success` will be true if the reference should be update, false if - * the lock must be discarded. - * - * A refdb implementation must provide this function if a `lock` - * implementation is provided. - * - * @arg payload The payload returned by `lock`. - * @arg success `1` if a reference should be updated, `2` if - * a reference should be deleted, `0` if the lock must be - * discarded. - * @arg update_reflog `1` in case the reflog should be updated, `0` - * otherwise. - * @arg ref The reference which should be unlocked. - * @arg who The person updating the reference. Shall be used to create - * a reflog entry in case `update_reflog` is set. - * @arg message The message detailing what kind of reference update is - * performed. Shall be used to create a reflog entry in - * case `update_reflog` is set. - * @return `0` on success, a negative error code otherwise - */ - int GIT_CALLBACK(unlock)(git_refdb_backend *backend, void *payload, int success, int update_reflog, - const git_reference *ref, const git_signature *sig, const char *message); -}; - -#define GIT_REFDB_BACKEND_VERSION 1 -#define GIT_REFDB_BACKEND_INIT {GIT_REFDB_BACKEND_VERSION} - -/** - * Initializes a `git_refdb_backend` with default values. Equivalent to - * creating an instance with GIT_REFDB_BACKEND_INIT. - * - * @param backend the `git_refdb_backend` struct to initialize - * @param version Version of struct; pass `GIT_REFDB_BACKEND_VERSION` - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_refdb_init_backend( - git_refdb_backend *backend, - unsigned int version); - -/** - * Constructors for default filesystem-based refdb backend - * - * Under normal usage, this is called for you when the repository is - * opened / created, but you can use this to explicitly construct a - * filesystem refdb backend for a repository. - * - * @param backend_out Output pointer to the git_refdb_backend object - * @param repo Git repository to access - * @return 0 on success, <0 error code on failure - */ -GIT_EXTERN(int) git_refdb_backend_fs( - git_refdb_backend **backend_out, - git_repository *repo); - -/** - * Sets the custom backend to an existing reference DB - * - * The `git_refdb` will take ownership of the `git_refdb_backend` so you - * should NOT free it after calling this function. - * - * @param refdb database to add the backend to - * @param backend pointer to a git_refdb_backend instance - * @return 0 on success; error code otherwise - */ -GIT_EXTERN(int) git_refdb_set_backend( - git_refdb *refdb, - git_refdb_backend *backend); - -GIT_END_DECL - -#endif +/* + * 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_sys_git_refdb_backend_h__ +#define INCLUDE_sys_git_refdb_backend_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" + +/** + * @file git2/refdb_backend.h + * @brief Git custom refs backend functions + * @defgroup git_refdb_backend Git custom refs backend API + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + + +/** + * Every backend's iterator must have a pointer to itself as the first + * element, so the API can talk to it. You'd define your iterator as + * + * struct my_iterator { + * git_reference_iterator parent; + * ... + * } + * + * and assign `iter->parent.backend` to your `git_refdb_backend`. + */ +struct git_reference_iterator { + git_refdb *db; + + /** + * Return the current reference and advance the iterator. + */ + int GIT_CALLBACK(next)( + git_reference **ref, + git_reference_iterator *iter); + + /** + * Return the name of the current reference and advance the iterator + */ + int GIT_CALLBACK(next_name)( + const char **ref_name, + git_reference_iterator *iter); + + /** + * Free the iterator + */ + void GIT_CALLBACK(free)( + git_reference_iterator *iter); +}; + +/** An instance for a custom backend */ +struct git_refdb_backend { + unsigned int version; /**< The backend API version */ + + /** + * Queries the refdb backend for the existence of a reference. + * + * A refdb implementation must provide this function. + * + * @arg exists The implementation shall set this to `0` if a ref does + * not exist, otherwise to `1`. + * @arg ref_name The reference's name that should be checked for + * existence. + * @return `0` on success, a negative error value code. + */ + int GIT_CALLBACK(exists)( + int *exists, + git_refdb_backend *backend, + const char *ref_name); + + /** + * Queries the refdb backend for a given reference. + * + * A refdb implementation must provide this function. + * + * @arg out The implementation shall set this to the allocated + * reference, if it could be found, otherwise to `NULL`. + * @arg ref_name The reference's name that should be checked for + * existence. + * @return `0` on success, `GIT_ENOTFOUND` if the reference does + * exist, otherwise a negative error code. + */ + int GIT_CALLBACK(lookup)( + git_reference **out, + git_refdb_backend *backend, + const char *ref_name); + + /** + * Allocate an iterator object for the backend. + * + * A refdb implementation must provide this function. + * + * @arg out The implementation shall set this to the allocated + * reference iterator. A custom structure may be used with an + * embedded `git_reference_iterator` structure. Both `next` + * and `next_name` functions of `git_reference_iterator` need + * to be populated. + * @arg glob A pattern to filter references by. If given, the iterator + * shall only return references that match the glob when + * passed to `wildmatch`. + * @return `0` on success, otherwise a negative error code. + */ + int GIT_CALLBACK(iterator)( + git_reference_iterator **iter, + struct git_refdb_backend *backend, + const char *glob); + + /** + * Writes the given reference to the refdb. + * + * A refdb implementation must provide this function. + * + * @arg ref The reference to persist. May either be a symbolic or + * direct reference. + * @arg force Whether to write the reference if a reference with the + * same name already exists. + * @arg who The person updating the reference. Shall be used to create + * a reflog entry. + * @arg message The message detailing what kind of reference update is + * performed. Shall be used to create a reflog entry. + * @arg old If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the reference is currently at + * the given OID before writing the new value. If both `old` + * and `old_target` are `NULL`, then the reference should not + * exist at the point of writing. + * @arg old_target If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the symbolic + * reference is currently at the given target before + * writing the new value. If both `old` and + * `old_target` are `NULL`, then the reference should + * not exist at the point of writing. + * @return `0` on success, otherwise a negative error code. + */ + int GIT_CALLBACK(write)(git_refdb_backend *backend, + const git_reference *ref, int force, + const git_signature *who, const char *message, + const git_oid *old, const char *old_target); + + /** + * Rename a reference in the refdb. + * + * A refdb implementation must provide this function. + * + * @arg out The implementation shall set this to the newly created + * reference or `NULL` on error. + * @arg old_name The current name of the reference that is to be renamed. + * @arg new_name The new name that the old reference shall be renamed to. + * @arg force Whether to write the reference if a reference with the + * target name already exists. + * @arg who The person updating the reference. Shall be used to create + * a reflog entry. + * @arg message The message detailing what kind of reference update is + * performed. Shall be used to create a reflog entry. + * @return `0` on success, otherwise a negative error code. + */ + int GIT_CALLBACK(rename)( + git_reference **out, git_refdb_backend *backend, + const char *old_name, const char *new_name, int force, + const git_signature *who, const char *message); + + /** + * Deletes the given reference from the refdb. + * + * If it exists, its reflog should be deleted as well. + * + * A refdb implementation must provide this function. + * + * @arg ref_name The name of the reference name that shall be deleted. + * @arg old_id If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the reference is currently at + * the given OID before writing the new value. + * @arg old_target If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the symbolic + * reference is currently at the given target before + * writing the new value. + * @return `0` on success, otherwise a negative error code. + */ + int GIT_CALLBACK(del)(git_refdb_backend *backend, const char *ref_name, const git_oid *old_id, const char *old_target); + + /** + * Suggests that the given refdb compress or optimize its references. + * + * This mechanism is implementation specific. For on-disk reference + * databases, this may pack all loose references. + * + * A refdb implementation may provide this function; if it is not + * provided, nothing will be done. + * + * @return `0` on success a negative error code otherwise + */ + int GIT_CALLBACK(compress)(git_refdb_backend *backend); + + /** + * Query whether a particular reference has a log (may be empty) + * + * Shall return 1 if it has a reflog, 0 it it doesn't and negative in + * case an error occurred. + * + * A refdb implementation must provide this function. + * + * @return `0` on success, `1` if the reflog for the given reference + * exists, a negative error code otherwise + */ + int GIT_CALLBACK(has_log)(git_refdb_backend *backend, const char *refname); + + /** + * Make sure a particular reference will have a reflog which + * will be appended to on writes. + * + * A refdb implementation must provide this function. + * + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(ensure_log)(git_refdb_backend *backend, const char *refname); + + /** + * Frees any resources held by the refdb (including the `git_refdb_backend` + * itself). + * + * A refdb backend implementation must provide this function. + */ + void GIT_CALLBACK(free)(git_refdb_backend *backend); + + /** + * Read the reflog for the given reference name. + * + * A refdb implementation must provide this function. + * + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(reflog_read)(git_reflog **out, git_refdb_backend *backend, const char *name); + + /** + * Write a reflog to disk. + * + * A refdb implementation must provide this function. + * + * @arg reflog The complete reference log for a given reference. Note + * that this may contain entries that have already been + * written to disk. + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(reflog_write)(git_refdb_backend *backend, git_reflog *reflog); + + /** + * Rename a reflog. + * + * A refdb implementation must provide this function. + * + * @arg old_name The name of old reference whose reflog shall be renamed from. + * @arg new_name The name of new reference whose reflog shall be renamed to. + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name); + + /** + * Remove a reflog. + * + * A refdb implementation must provide this function. + * + * @arg name The name of the reference whose reflog shall be deleted. + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(reflog_delete)(git_refdb_backend *backend, const char *name); + + /** + * Lock a reference. + * + * A refdb implementation may provide this function; if it is not + * provided, the transaction API will fail to work. + * + * @arg payload_out Opaque parameter that will be passed verbosely to + * `unlock`. + * @arg refname Reference that shall be locked. + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(lock)(void **payload_out, git_refdb_backend *backend, const char *refname); + + /** + * Unlock a reference. + * + * Only one of target or symbolic_target will be set. + * `success` will be true if the reference should be update, false if + * the lock must be discarded. + * + * A refdb implementation must provide this function if a `lock` + * implementation is provided. + * + * @arg payload The payload returned by `lock`. + * @arg success `1` if a reference should be updated, `2` if + * a reference should be deleted, `0` if the lock must be + * discarded. + * @arg update_reflog `1` in case the reflog should be updated, `0` + * otherwise. + * @arg ref The reference which should be unlocked. + * @arg who The person updating the reference. Shall be used to create + * a reflog entry in case `update_reflog` is set. + * @arg message The message detailing what kind of reference update is + * performed. Shall be used to create a reflog entry in + * case `update_reflog` is set. + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(unlock)(git_refdb_backend *backend, void *payload, int success, int update_reflog, + const git_reference *ref, const git_signature *sig, const char *message); +}; + +#define GIT_REFDB_BACKEND_VERSION 1 +#define GIT_REFDB_BACKEND_INIT {GIT_REFDB_BACKEND_VERSION} + +/** + * Initializes a `git_refdb_backend` with default values. Equivalent to + * creating an instance with GIT_REFDB_BACKEND_INIT. + * + * @param backend the `git_refdb_backend` struct to initialize + * @param version Version of struct; pass `GIT_REFDB_BACKEND_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_refdb_init_backend( + git_refdb_backend *backend, + unsigned int version); + +/** + * Constructors for default filesystem-based refdb backend + * + * Under normal usage, this is called for you when the repository is + * opened / created, but you can use this to explicitly construct a + * filesystem refdb backend for a repository. + * + * @param backend_out Output pointer to the git_refdb_backend object + * @param repo Git repository to access + * @return 0 on success, <0 error code on failure + */ +GIT_EXTERN(int) git_refdb_backend_fs( + git_refdb_backend **backend_out, + git_repository *repo); + +/** + * Sets the custom backend to an existing reference DB + * + * The `git_refdb` will take ownership of the `git_refdb_backend` so you + * should NOT free it after calling this function. + * + * @param refdb database to add the backend to + * @param backend pointer to a git_refdb_backend instance + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_refdb_set_backend( + git_refdb *refdb, + git_refdb_backend *backend); + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/sys/reflog.h b/3rdparty/libgit2/include/git2/sys/reflog.h index c9d0041..88431d1 100644 --- a/3rdparty/libgit2/include/git2/sys/reflog.h +++ b/3rdparty/libgit2/include/git2/sys/reflog.h @@ -1,21 +1,21 @@ -/* - * 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_sys_git_reflog_h__ -#define INCLUDE_sys_git_reflog_h__ - -#include "git2/common.h" -#include "git2/types.h" -#include "git2/oid.h" - -GIT_BEGIN_DECL - -GIT_EXTERN(git_reflog_entry *) git_reflog_entry__alloc(void); -GIT_EXTERN(void) git_reflog_entry__free(git_reflog_entry *entry); - -GIT_END_DECL - -#endif +/* + * 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_sys_git_reflog_h__ +#define INCLUDE_sys_git_reflog_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" + +GIT_BEGIN_DECL + +GIT_EXTERN(git_reflog_entry *) git_reflog_entry__alloc(void); +GIT_EXTERN(void) git_reflog_entry__free(git_reflog_entry *entry); + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/sys/refs.h b/3rdparty/libgit2/include/git2/sys/refs.h index d2ce2e0..2f85b74 100644 --- a/3rdparty/libgit2/include/git2/sys/refs.h +++ b/3rdparty/libgit2/include/git2/sys/refs.h @@ -1,49 +1,49 @@ -/* - * 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_sys_git_refdb_h__ -#define INCLUDE_sys_git_refdb_h__ - -#include "git2/common.h" -#include "git2/types.h" -#include "git2/oid.h" - -/** - * @file git2/sys/refs.h - * @brief Low-level Git ref creation - * @defgroup git_backend Git custom backend APIs - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Create a new direct reference from an OID. - * - * @param name the reference name - * @param oid the object id for a direct reference - * @param peel the first non-tag object's OID, or NULL - * @return the created git_reference or NULL on error - */ -GIT_EXTERN(git_reference *) git_reference__alloc( - const char *name, - const git_oid *oid, - const git_oid *peel); - -/** - * Create a new symbolic reference. - * - * @param name the reference name - * @param target the target for a symbolic reference - * @return the created git_reference or NULL on error - */ -GIT_EXTERN(git_reference *) git_reference__alloc_symbolic( - const char *name, - const char *target); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_refdb_h__ +#define INCLUDE_sys_git_refdb_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" + +/** + * @file git2/sys/refs.h + * @brief Low-level Git ref creation + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a new direct reference from an OID. + * + * @param name the reference name + * @param oid the object id for a direct reference + * @param peel the first non-tag object's OID, or NULL + * @return the created git_reference or NULL on error + */ +GIT_EXTERN(git_reference *) git_reference__alloc( + const char *name, + const git_oid *oid, + const git_oid *peel); + +/** + * Create a new symbolic reference. + * + * @param name the reference name + * @param target the target for a symbolic reference + * @return the created git_reference or NULL on error + */ +GIT_EXTERN(git_reference *) git_reference__alloc_symbolic( + const char *name, + const char *target); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/remote.h b/3rdparty/libgit2/include/git2/sys/remote.h index 07309ab..95327fa 100644 --- a/3rdparty/libgit2/include/git2/sys/remote.h +++ b/3rdparty/libgit2/include/git2/sys/remote.h @@ -1,49 +1,49 @@ -/* - * 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_sys_git_remote_h -#define INCLUDE_sys_git_remote_h - -#include "git2/remote.h" - -/** - * @file git2/sys/remote.h - * @brief Low-level remote functionality for custom transports - * @defgroup git_remote Low-level remote functionality - * @ingroup Git - * @{ -*/ - -GIT_BEGIN_DECL - -typedef enum { - /** Remote supports fetching an advertised object by ID. */ - GIT_REMOTE_CAPABILITY_TIP_OID = (1 << 0), - - /** Remote supports fetching an individual reachable object. */ - GIT_REMOTE_CAPABILITY_REACHABLE_OID = (1 << 1), - - /** Remote supports push options. */ - GIT_REMOTE_CAPABILITY_PUSH_OPTIONS = (1 << 2), -} git_remote_capability_t; - -/** - * Disposes libgit2-initialized fields from a git_remote_connect_options. - * This should only be used for git_remote_connect_options returned by - * git_transport_remote_connect_options. - * - * Note that this does not free the `git_remote_connect_options` itself, just - * the memory pointed to by it. - * - * @param opts The `git_remote_connect_options` struct to dispose. - */ -GIT_EXTERN(void) git_remote_connect_options_dispose( - git_remote_connect_options *opts); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_remote_h +#define INCLUDE_sys_git_remote_h + +#include "git2/remote.h" + +/** + * @file git2/sys/remote.h + * @brief Low-level remote functionality for custom transports + * @defgroup git_remote Low-level remote functionality + * @ingroup Git + * @{ +*/ + +GIT_BEGIN_DECL + +typedef enum { + /** Remote supports fetching an advertised object by ID. */ + GIT_REMOTE_CAPABILITY_TIP_OID = (1 << 0), + + /** Remote supports fetching an individual reachable object. */ + GIT_REMOTE_CAPABILITY_REACHABLE_OID = (1 << 1), + + /** Remote supports push options. */ + GIT_REMOTE_CAPABILITY_PUSH_OPTIONS = (1 << 2), +} git_remote_capability_t; + +/** + * Disposes libgit2-initialized fields from a git_remote_connect_options. + * This should only be used for git_remote_connect_options returned by + * git_transport_remote_connect_options. + * + * Note that this does not free the `git_remote_connect_options` itself, just + * the memory pointed to by it. + * + * @param opts The `git_remote_connect_options` struct to dispose. + */ +GIT_EXTERN(void) git_remote_connect_options_dispose( + git_remote_connect_options *opts); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/repository.h b/3rdparty/libgit2/include/git2/sys/repository.h index 080a404..775eb74 100644 --- a/3rdparty/libgit2/include/git2/sys/repository.h +++ b/3rdparty/libgit2/include/git2/sys/repository.h @@ -1,185 +1,185 @@ -/* - * 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_sys_git_repository_h__ -#define INCLUDE_sys_git_repository_h__ - -#include "git2/common.h" -#include "git2/types.h" -#include "git2/oid.h" - -/** - * @file git2/sys/repository.h - * @brief Git repository custom implementation routines - * @defgroup git_backend Git custom backend APIs - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Create a new repository with neither backends nor config object - * - * Note that this is only useful if you wish to associate the repository - * with a non-filesystem-backed object database and config store. - * - * Caveats: since this repository has no physical location, some systems - * can fail to function properly: locations under $GIT_DIR, $GIT_COMMON_DIR, - * or $GIT_INFO_DIR are impacted. - * - * @param out The blank repository - * @return 0 on success, or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_repository_new(git_repository **out, git_oid_t oid_type); -#else -GIT_EXTERN(int) git_repository_new(git_repository **out); -#endif - -/** - * Reset all the internal state in a repository. - * - * This will free all the mapped memory and internal objects - * of the repository and leave it in a "blank" state. - * - * There's no need to call this function directly unless you're - * trying to aggressively cleanup the repo before its - * deallocation. `git_repository_free` already performs this operation - * before deallocating the repo. - * - * @param repo The repository to clean up - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_repository__cleanup(git_repository *repo); - -/** - * Update the filesystem config settings for an open repository - * - * When a repository is initialized, config values are set based on the - * properties of the filesystem that the repository is on, such as - * "core.ignorecase", "core.filemode", "core.symlinks", etc. If the - * repository is moved to a new filesystem, these properties may no - * longer be correct and API calls may not behave as expected. This - * call reruns the phase of repository initialization that sets those - * properties to compensate for the current filesystem of the repo. - * - * @param repo A repository object - * @param recurse_submodules Should submodules be updated recursively - * @return 0 on success, < 0 on error - */ -GIT_EXTERN(int) git_repository_reinit_filesystem( - git_repository *repo, - int recurse_submodules); - -/** - * Set the configuration file for this repository - * - * This configuration file will be used for all configuration - * queries involving this repository. - * - * The repository will keep a reference to the config file; - * the user must still free the config after setting it - * to the repository, or it will leak. - * - * @param repo A repository object - * @param config A Config object - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_repository_set_config(git_repository *repo, git_config *config); - -/** - * Set the Object Database for this repository - * - * The ODB will be used for all object-related operations - * involving this repository. - * - * The repository will keep a reference to the ODB; the user - * must still free the ODB object after setting it to the - * repository, or it will leak. - * - * @param repo A repository object - * @param odb An ODB object - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_repository_set_odb(git_repository *repo, git_odb *odb); - -/** - * Set the Reference Database Backend for this repository - * - * The refdb will be used for all reference related operations - * involving this repository. - * - * The repository will keep a reference to the refdb; the user - * must still free the refdb object after setting it to the - * repository, or it will leak. - * - * @param repo A repository object - * @param refdb An refdb object - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_repository_set_refdb(git_repository *repo, git_refdb *refdb); - -/** - * Set the index file for this repository - * - * This index will be used for all index-related operations - * involving this repository. - * - * The repository will keep a reference to the index file; - * the user must still free the index after setting it - * to the repository, or it will leak. - * - * @param repo A repository object - * @param index An index object - * @return 0 on success, or an error code - */ -GIT_EXTERN(int) git_repository_set_index(git_repository *repo, git_index *index); - -/** - * Set a repository to be bare. - * - * Clear the working directory and set core.bare to true. You may also - * want to call `git_repository_set_index(repo, NULL)` since a bare repo - * typically does not have an index, but this function will not do that - * for you. - * - * @param repo Repo to make bare - * @return 0 on success, <0 on failure - */ -GIT_EXTERN(int) git_repository_set_bare(git_repository *repo); - -/** - * Load and cache all submodules. - * - * Because the `.gitmodules` file is unstructured, loading submodules is an - * O(N) operation. Any operation (such as `git_rebase_init`) that requires - * accessing all submodules is O(N^2) in the number of submodules, if it - * has to look each one up individually. This function loads all submodules - * and caches them so that subsequent calls to `git_submodule_lookup` are O(1). - * - * @param repo the repository whose submodules will be cached. - */ -GIT_EXTERN(int) git_repository_submodule_cache_all( - git_repository *repo); - -/** - * Clear the submodule cache. - * - * Clear the submodule cache populated by `git_repository_submodule_cache_all`. - * If there is no cache, do nothing. - * - * The cache incorporates data from the repository's configuration, as well - * as the state of the working tree, the index, and HEAD. So any time any - * of these has changed, the cache might become invalid. - * - * @param repo the repository whose submodule cache will be cleared - */ -GIT_EXTERN(int) git_repository_submodule_cache_clear( - git_repository *repo); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_repository_h__ +#define INCLUDE_sys_git_repository_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" + +/** + * @file git2/sys/repository.h + * @brief Git repository custom implementation routines + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a new repository with neither backends nor config object + * + * Note that this is only useful if you wish to associate the repository + * with a non-filesystem-backed object database and config store. + * + * Caveats: since this repository has no physical location, some systems + * can fail to function properly: locations under $GIT_DIR, $GIT_COMMON_DIR, + * or $GIT_INFO_DIR are impacted. + * + * @param out The blank repository + * @return 0 on success, or an error code + */ +#ifdef GIT_EXPERIMENTAL_SHA256 +GIT_EXTERN(int) git_repository_new(git_repository **out, git_oid_t oid_type); +#else +GIT_EXTERN(int) git_repository_new(git_repository **out); +#endif + +/** + * Reset all the internal state in a repository. + * + * This will free all the mapped memory and internal objects + * of the repository and leave it in a "blank" state. + * + * There's no need to call this function directly unless you're + * trying to aggressively cleanup the repo before its + * deallocation. `git_repository_free` already performs this operation + * before deallocating the repo. + * + * @param repo The repository to clean up + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository__cleanup(git_repository *repo); + +/** + * Update the filesystem config settings for an open repository + * + * When a repository is initialized, config values are set based on the + * properties of the filesystem that the repository is on, such as + * "core.ignorecase", "core.filemode", "core.symlinks", etc. If the + * repository is moved to a new filesystem, these properties may no + * longer be correct and API calls may not behave as expected. This + * call reruns the phase of repository initialization that sets those + * properties to compensate for the current filesystem of the repo. + * + * @param repo A repository object + * @param recurse_submodules Should submodules be updated recursively + * @return 0 on success, < 0 on error + */ +GIT_EXTERN(int) git_repository_reinit_filesystem( + git_repository *repo, + int recurse_submodules); + +/** + * Set the configuration file for this repository + * + * This configuration file will be used for all configuration + * queries involving this repository. + * + * The repository will keep a reference to the config file; + * the user must still free the config after setting it + * to the repository, or it will leak. + * + * @param repo A repository object + * @param config A Config object + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_set_config(git_repository *repo, git_config *config); + +/** + * Set the Object Database for this repository + * + * The ODB will be used for all object-related operations + * involving this repository. + * + * The repository will keep a reference to the ODB; the user + * must still free the ODB object after setting it to the + * repository, or it will leak. + * + * @param repo A repository object + * @param odb An ODB object + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_set_odb(git_repository *repo, git_odb *odb); + +/** + * Set the Reference Database Backend for this repository + * + * The refdb will be used for all reference related operations + * involving this repository. + * + * The repository will keep a reference to the refdb; the user + * must still free the refdb object after setting it to the + * repository, or it will leak. + * + * @param repo A repository object + * @param refdb An refdb object + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_set_refdb(git_repository *repo, git_refdb *refdb); + +/** + * Set the index file for this repository + * + * This index will be used for all index-related operations + * involving this repository. + * + * The repository will keep a reference to the index file; + * the user must still free the index after setting it + * to the repository, or it will leak. + * + * @param repo A repository object + * @param index An index object + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_set_index(git_repository *repo, git_index *index); + +/** + * Set a repository to be bare. + * + * Clear the working directory and set core.bare to true. You may also + * want to call `git_repository_set_index(repo, NULL)` since a bare repo + * typically does not have an index, but this function will not do that + * for you. + * + * @param repo Repo to make bare + * @return 0 on success, <0 on failure + */ +GIT_EXTERN(int) git_repository_set_bare(git_repository *repo); + +/** + * Load and cache all submodules. + * + * Because the `.gitmodules` file is unstructured, loading submodules is an + * O(N) operation. Any operation (such as `git_rebase_init`) that requires + * accessing all submodules is O(N^2) in the number of submodules, if it + * has to look each one up individually. This function loads all submodules + * and caches them so that subsequent calls to `git_submodule_lookup` are O(1). + * + * @param repo the repository whose submodules will be cached. + */ +GIT_EXTERN(int) git_repository_submodule_cache_all( + git_repository *repo); + +/** + * Clear the submodule cache. + * + * Clear the submodule cache populated by `git_repository_submodule_cache_all`. + * If there is no cache, do nothing. + * + * The cache incorporates data from the repository's configuration, as well + * as the state of the working tree, the index, and HEAD. So any time any + * of these has changed, the cache might become invalid. + * + * @param repo the repository whose submodule cache will be cleared + */ +GIT_EXTERN(int) git_repository_submodule_cache_clear( + git_repository *repo); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/sys/stream.h b/3rdparty/libgit2/include/git2/sys/stream.h index 3277088..1c2a3a5 100644 --- a/3rdparty/libgit2/include/git2/sys/stream.h +++ b/3rdparty/libgit2/include/git2/sys/stream.h @@ -1,152 +1,152 @@ -/* - * 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_sys_git_stream_h__ -#define INCLUDE_sys_git_stream_h__ - -#include "git2/common.h" -#include "git2/types.h" -#include "git2/proxy.h" - -GIT_BEGIN_DECL - -#define GIT_STREAM_VERSION 1 - -/** - * Every stream must have this struct as its first element, so the - * API can talk to it. You'd define your stream as - * - * struct my_stream { - * git_stream parent; - * ... - * } - * - * and fill the functions - */ -typedef struct git_stream { - int version; - - unsigned int encrypted : 1, - proxy_support : 1; - - /** - * Timeout for read and write operations; can be set to `0` to - * block indefinitely. - */ - int timeout; - - /** - * Timeout to connect to the remote server; can be set to `0` - * to use the system defaults. This can be shorter than the - * system default - often 75 seconds - but cannot be longer. - */ - int connect_timeout; - - int GIT_CALLBACK(connect)(struct git_stream *); - int GIT_CALLBACK(certificate)(git_cert **, struct git_stream *); - int GIT_CALLBACK(set_proxy)(struct git_stream *, const git_proxy_options *proxy_opts); - ssize_t GIT_CALLBACK(read)(struct git_stream *, void *, size_t); - ssize_t GIT_CALLBACK(write)(struct git_stream *, const char *, size_t, int); - int GIT_CALLBACK(close)(struct git_stream *); - void GIT_CALLBACK(free)(struct git_stream *); -} git_stream; - -typedef struct { - /** The `version` field should be set to `GIT_STREAM_VERSION`. */ - int version; - - /** - * Called to create a new connection to a given host. - * - * @param out The created stream - * @param host The hostname to connect to; may be a hostname or - * IP address - * @param port The port to connect to; may be a port number or - * service name - * @return 0 or an error code - */ - int GIT_CALLBACK(init)(git_stream **out, const char *host, const char *port); - - /** - * Called to create a new connection on top of the given stream. If - * this is a TLS stream, then this function may be used to proxy a - * TLS stream over an HTTP CONNECT session. If this is unset, then - * HTTP CONNECT proxies will not be supported. - * - * @param out The created stream - * @param in An existing stream to add TLS to - * @param host The hostname that the stream is connected to, - * for certificate validation - * @return 0 or an error code - */ - int GIT_CALLBACK(wrap)(git_stream **out, git_stream *in, const char *host); -} git_stream_registration; - -/** - * The type of stream to register. - */ -typedef enum { - /** A standard (non-TLS) socket. */ - GIT_STREAM_STANDARD = 1, - - /** A TLS-encrypted socket. */ - GIT_STREAM_TLS = 2 -} git_stream_t; - -/** - * Register stream constructors for the library to use - * - * If a registration structure is already set, it will be overwritten. - * Pass `NULL` in order to deregister the current constructor and return - * to the system defaults. - * - * The type parameter may be a bitwise AND of types. - * - * @param type the type or types of stream to register - * @param registration the registration data - * @return 0 or an error code - */ -GIT_EXTERN(int) git_stream_register( - git_stream_t type, git_stream_registration *registration); - -#ifndef GIT_DEPRECATE_HARD - -/** @name Deprecated TLS Stream Registration Functions - * - * These functions are retained for backward compatibility. The newer - * versions of these values should be preferred in all new code. - * - * There is no plan to remove these backward compatibility values at - * this time. - */ -/**@{*/ - -/** - * @deprecated Provide a git_stream_registration to git_stream_register - * @see git_stream_registration - */ -typedef int GIT_CALLBACK(git_stream_cb)(git_stream **out, const char *host, const char *port); - -/** - * Register a TLS stream constructor for the library to use. This stream - * will not support HTTP CONNECT proxies. This internally calls - * `git_stream_register` and is preserved for backward compatibility. - * - * This function is deprecated, but there is no plan to remove this - * function at this time. - * - * @deprecated Provide a git_stream_registration to git_stream_register - * @see git_stream_register - */ -GIT_EXTERN(int) git_stream_register_tls(git_stream_cb ctor); - -/**@}*/ - -#endif - -GIT_END_DECL - -#endif +/* + * 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_sys_git_stream_h__ +#define INCLUDE_sys_git_stream_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/proxy.h" + +GIT_BEGIN_DECL + +#define GIT_STREAM_VERSION 1 + +/** + * Every stream must have this struct as its first element, so the + * API can talk to it. You'd define your stream as + * + * struct my_stream { + * git_stream parent; + * ... + * } + * + * and fill the functions + */ +typedef struct git_stream { + int version; + + unsigned int encrypted : 1, + proxy_support : 1; + + /** + * Timeout for read and write operations; can be set to `0` to + * block indefinitely. + */ + int timeout; + + /** + * Timeout to connect to the remote server; can be set to `0` + * to use the system defaults. This can be shorter than the + * system default - often 75 seconds - but cannot be longer. + */ + int connect_timeout; + + int GIT_CALLBACK(connect)(struct git_stream *); + int GIT_CALLBACK(certificate)(git_cert **, struct git_stream *); + int GIT_CALLBACK(set_proxy)(struct git_stream *, const git_proxy_options *proxy_opts); + ssize_t GIT_CALLBACK(read)(struct git_stream *, void *, size_t); + ssize_t GIT_CALLBACK(write)(struct git_stream *, const char *, size_t, int); + int GIT_CALLBACK(close)(struct git_stream *); + void GIT_CALLBACK(free)(struct git_stream *); +} git_stream; + +typedef struct { + /** The `version` field should be set to `GIT_STREAM_VERSION`. */ + int version; + + /** + * Called to create a new connection to a given host. + * + * @param out The created stream + * @param host The hostname to connect to; may be a hostname or + * IP address + * @param port The port to connect to; may be a port number or + * service name + * @return 0 or an error code + */ + int GIT_CALLBACK(init)(git_stream **out, const char *host, const char *port); + + /** + * Called to create a new connection on top of the given stream. If + * this is a TLS stream, then this function may be used to proxy a + * TLS stream over an HTTP CONNECT session. If this is unset, then + * HTTP CONNECT proxies will not be supported. + * + * @param out The created stream + * @param in An existing stream to add TLS to + * @param host The hostname that the stream is connected to, + * for certificate validation + * @return 0 or an error code + */ + int GIT_CALLBACK(wrap)(git_stream **out, git_stream *in, const char *host); +} git_stream_registration; + +/** + * The type of stream to register. + */ +typedef enum { + /** A standard (non-TLS) socket. */ + GIT_STREAM_STANDARD = 1, + + /** A TLS-encrypted socket. */ + GIT_STREAM_TLS = 2 +} git_stream_t; + +/** + * Register stream constructors for the library to use + * + * If a registration structure is already set, it will be overwritten. + * Pass `NULL` in order to deregister the current constructor and return + * to the system defaults. + * + * The type parameter may be a bitwise AND of types. + * + * @param type the type or types of stream to register + * @param registration the registration data + * @return 0 or an error code + */ +GIT_EXTERN(int) git_stream_register( + git_stream_t type, git_stream_registration *registration); + +#ifndef GIT_DEPRECATE_HARD + +/** @name Deprecated TLS Stream Registration Functions + * + * These functions are retained for backward compatibility. The newer + * versions of these values should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** + * @deprecated Provide a git_stream_registration to git_stream_register + * @see git_stream_registration + */ +typedef int GIT_CALLBACK(git_stream_cb)(git_stream **out, const char *host, const char *port); + +/** + * Register a TLS stream constructor for the library to use. This stream + * will not support HTTP CONNECT proxies. This internally calls + * `git_stream_register` and is preserved for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Provide a git_stream_registration to git_stream_register + * @see git_stream_register + */ +GIT_EXTERN(int) git_stream_register_tls(git_stream_cb ctor); + +/**@}*/ + +#endif + +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/sys/transport.h b/3rdparty/libgit2/include/git2/sys/transport.h index 370ca45..b65d8a1 100644 --- a/3rdparty/libgit2/include/git2/sys/transport.h +++ b/3rdparty/libgit2/include/git2/sys/transport.h @@ -1,465 +1,465 @@ -/* - * 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_sys_git_transport_h -#define INCLUDE_sys_git_transport_h - -#include "git2/net.h" -#include "git2/oidarray.h" -#include "git2/proxy.h" -#include "git2/remote.h" -#include "git2/strarray.h" -#include "git2/transport.h" -#include "git2/types.h" - -/** - * @file git2/sys/transport.h - * @brief Git custom transport registration interfaces and functions - * @defgroup git_transport Git custom transport registration - * @ingroup Git - * @{ - */ - -GIT_BEGIN_DECL - -typedef struct { - const git_remote_head * const *refs; - size_t refs_len; - git_oid *shallow_roots; - size_t shallow_roots_len; - int depth; -} git_fetch_negotiation; - -struct git_transport { - unsigned int version; /**< The struct version */ - - /** - * Connect the transport to the remote repository, using the given - * direction. - */ - int GIT_CALLBACK(connect)( - git_transport *transport, - const char *url, - int direction, - const git_remote_connect_options *connect_opts); - - /** - * Resets the connect options for the given transport. This - * is useful for updating settings or callbacks for an already - * connected transport. - */ - int GIT_CALLBACK(set_connect_opts)( - git_transport *transport, - const git_remote_connect_options *connect_opts); - - /** - * Gets the capabilities for this remote repository. - * - * This function may be called after a successful call to - * `connect()`. - */ - int GIT_CALLBACK(capabilities)( - unsigned int *capabilities, - git_transport *transport); - -#ifdef GIT_EXPERIMENTAL_SHA256 - /** - * Gets the object type for the remote repository. - * - * This function may be called after a successful call to - * `connect()`. - */ - int GIT_CALLBACK(oid_type)( - git_oid_t *object_type, - git_transport *transport); -#endif - - /** - * Get the list of available references in the remote repository. - * - * This function may be called after a successful call to - * `connect()`. The array returned is owned by the transport and - * must be kept valid until the next call to one of its functions. - */ - int GIT_CALLBACK(ls)( - const git_remote_head ***out, - size_t *size, - git_transport *transport); - - /** Executes the push whose context is in the git_push object. */ - int GIT_CALLBACK(push)( - git_transport *transport, - git_push *push); - - /** - * Negotiate a fetch with the remote repository. - * - * This function may be called after a successful call to `connect()`, - * when the direction is GIT_DIRECTION_FETCH. The function performs a - * negotiation to calculate the `wants` list for the fetch. - */ - int GIT_CALLBACK(negotiate_fetch)( - git_transport *transport, - git_repository *repo, - const git_fetch_negotiation *fetch_data); - - /** - * Return the shallow roots of the remote. - * - * This function may be called after a successful call to - * `negotiate_fetch`. - */ - int GIT_CALLBACK(shallow_roots)( - git_oidarray *out, - git_transport *transport); - - /** - * Start downloading the packfile from the remote repository. - * - * This function may be called after a successful call to - * negotiate_fetch(), when the direction is GIT_DIRECTION_FETCH. - */ - int GIT_CALLBACK(download_pack)( - git_transport *transport, - git_repository *repo, - git_indexer_progress *stats); - - /** Checks to see if the transport is connected */ - int GIT_CALLBACK(is_connected)(git_transport *transport); - - /** Cancels any outstanding transport operation */ - void GIT_CALLBACK(cancel)(git_transport *transport); - - /** - * Close the connection to the remote repository. - * - * This function is the reverse of connect() -- it terminates the - * connection to the remote end. - */ - int GIT_CALLBACK(close)(git_transport *transport); - - /** Frees/destructs the git_transport object. */ - void GIT_CALLBACK(free)(git_transport *transport); -}; - -#define GIT_TRANSPORT_VERSION 1 -#define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION} - -/** - * Initializes a `git_transport` with default values. Equivalent to - * creating an instance with GIT_TRANSPORT_INIT. - * - * @param opts the `git_transport` struct to initialize - * @param version Version of struct; pass `GIT_TRANSPORT_VERSION` - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_transport_init( - git_transport *opts, - unsigned int version); - -/** - * Function to use to create a transport from a URL. The transport database - * is scanned to find a transport that implements the scheme of the URI (i.e. - * git:// or http://) and a transport object is returned to the caller. - * - * @param out The newly created transport (out) - * @param owner The git_remote which will own this transport - * @param url The URL to connect to - * @return 0 or an error code - */ -GIT_EXTERN(int) git_transport_new(git_transport **out, git_remote *owner, const char *url); - -/** - * Create an ssh transport with custom git command paths - * - * This is a factory function suitable for setting as the transport - * callback in a remote (or for a clone in the options). - * - * The payload argument must be a strarray pointer with the paths for - * the `git-upload-pack` and `git-receive-pack` at index 0 and 1. - * - * @param out the resulting transport - * @param owner the owning remote - * @param payload a strarray with the paths - * @return 0 or an error code - */ -GIT_EXTERN(int) git_transport_ssh_with_paths(git_transport **out, git_remote *owner, void *payload); - -/** - * Add a custom transport definition, to be used in addition to the built-in - * set of transports that come with libgit2. - * - * The caller is responsible for synchronizing calls to git_transport_register - * and git_transport_unregister with other calls to the library that - * instantiate transports. - * - * @param prefix The scheme (ending in "://") to match, i.e. "git://" - * @param cb The callback used to create an instance of the transport - * @param param A fixed parameter to pass to cb at creation time - * @return 0 or an error code - */ -GIT_EXTERN(int) git_transport_register( - const char *prefix, - git_transport_cb cb, - void *param); - -/** - * Unregister a custom transport definition which was previously registered - * with git_transport_register. - * - * The caller is responsible for synchronizing calls to git_transport_register - * and git_transport_unregister with other calls to the library that - * instantiate transports. - * - * @param prefix From the previous call to git_transport_register - * @return 0 or an error code - */ -GIT_EXTERN(int) git_transport_unregister( - const char *prefix); - -/* Transports which come with libgit2 (match git_transport_cb). The expected - * value for "param" is listed in-line below. */ - -/** - * Create an instance of the dummy transport. - * - * @param out The newly created transport (out) - * @param owner The git_remote which will own this transport - * @param payload You must pass NULL for this parameter. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_transport_dummy( - git_transport **out, - git_remote *owner, - /* NULL */ void *payload); - -/** - * Create an instance of the local transport. - * - * @param out The newly created transport (out) - * @param owner The git_remote which will own this transport - * @param payload You must pass NULL for this parameter. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_transport_local( - git_transport **out, - git_remote *owner, - /* NULL */ void *payload); - -/** - * Create an instance of the smart transport. - * - * @param out The newly created transport (out) - * @param owner The git_remote which will own this transport - * @param payload A pointer to a git_smart_subtransport_definition - * @return 0 or an error code - */ -GIT_EXTERN(int) git_transport_smart( - git_transport **out, - git_remote *owner, - /* (git_smart_subtransport_definition *) */ void *payload); - -/** - * Call the certificate check for this transport. - * - * @param transport a smart transport - * @param cert the certificate to pass to the caller - * @param valid whether we believe the certificate is valid - * @param hostname the hostname we connected to - * @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH - * to indicate that there is no callback registered (or the callback - * refused to validate the certificate and callers should behave as - * if no callback was set), or < 0 for an error - */ -GIT_EXTERN(int) git_transport_smart_certificate_check(git_transport *transport, git_cert *cert, int valid, const char *hostname); - -/** - * Call the credentials callback for this transport - * - * @param out the pointer where the creds are to be stored - * @param transport a smart transport - * @param user the user we saw on the url (if any) - * @param methods available methods for authentication - * @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH - * to indicate that there is no callback registered (or the callback - * refused to provide credentials and callers should behave as if no - * callback was set), or < 0 for an error - */ -GIT_EXTERN(int) git_transport_smart_credentials(git_credential **out, git_transport *transport, const char *user, int methods); - -/** - * Get a copy of the remote connect options - * - * All data is copied and must be freed by the caller by calling - * `git_remote_connect_options_dispose`. - * - * @param out options struct to fill - * @param transport the transport to extract the data from. - */ -GIT_EXTERN(int) git_transport_remote_connect_options( - git_remote_connect_options *out, - git_transport *transport); - -/* - *** End of base transport interface *** - *** Begin interface for subtransports for the smart transport *** - */ - -/** Actions that the smart transport can ask a subtransport to perform */ -typedef enum { - GIT_SERVICE_UPLOADPACK_LS = 1, - GIT_SERVICE_UPLOADPACK = 2, - GIT_SERVICE_RECEIVEPACK_LS = 3, - GIT_SERVICE_RECEIVEPACK = 4 -} git_smart_service_t; - -typedef struct git_smart_subtransport git_smart_subtransport; -typedef struct git_smart_subtransport_stream git_smart_subtransport_stream; - -/** - * A stream used by the smart transport to read and write data - * from a subtransport. - * - * This provides a customization point in case you need to - * support some other communication method. - */ -struct git_smart_subtransport_stream { - git_smart_subtransport *subtransport; /**< The owning subtransport */ - - /** - * Read available data from the stream. - * - * The implementation may read less than requested. - */ - int GIT_CALLBACK(read)( - git_smart_subtransport_stream *stream, - char *buffer, - size_t buf_size, - size_t *bytes_read); - - /** - * Write data to the stream - * - * The implementation must write all data or return an error. - */ - int GIT_CALLBACK(write)( - git_smart_subtransport_stream *stream, - const char *buffer, - size_t len); - - /** Free the stream */ - void GIT_CALLBACK(free)( - git_smart_subtransport_stream *stream); -}; - -/** - * An implementation of a subtransport which carries data for the - * smart transport - */ -struct git_smart_subtransport { - /** - * Setup a subtransport stream for the requested action. - */ - int GIT_CALLBACK(action)( - git_smart_subtransport_stream **out, - git_smart_subtransport *transport, - const char *url, - git_smart_service_t action); - - /** - * Close the subtransport. - * - * Subtransports are guaranteed a call to close() between - * calls to action(), except for the following two "natural" progressions - * of actions against a constant URL: - * - * - UPLOADPACK_LS -> UPLOADPACK - * - RECEIVEPACK_LS -> RECEIVEPACK - */ - int GIT_CALLBACK(close)(git_smart_subtransport *transport); - - /** Free the subtransport */ - void GIT_CALLBACK(free)(git_smart_subtransport *transport); -}; - -/** A function which creates a new subtransport for the smart transport */ -typedef int GIT_CALLBACK(git_smart_subtransport_cb)( - git_smart_subtransport **out, - git_transport *owner, - void *param); - -/** - * Definition for a "subtransport" - * - * The smart transport knows how to speak the git protocol, but it has no - * knowledge of how to establish a connection between it and another endpoint, - * or how to move data back and forth. For this, a subtransport interface is - * declared, and the smart transport delegates this work to the subtransports. - * - * Three subtransports are provided by libgit2: ssh, git, http(s). - * - * Subtransports can either be RPC = 0 (persistent connection) or RPC = 1 - * (request/response). The smart transport handles the differences in its own - * logic. The git subtransport is RPC = 0, while http is RPC = 1. - */ -typedef struct git_smart_subtransport_definition { - /** The function to use to create the git_smart_subtransport */ - git_smart_subtransport_cb callback; - - /** - * True if the protocol is stateless; false otherwise. For example, - * http:// is stateless, but git:// is not. - */ - unsigned rpc; - - /** User-specified parameter passed to the callback */ - void *param; -} git_smart_subtransport_definition; - -/* Smart transport subtransports that come with libgit2 */ - -/** - * Create an instance of the http subtransport. - * - * This subtransport also supports https. - * - * @param out The newly created subtransport - * @param owner The smart transport to own this subtransport - * @return 0 or an error code - */ -GIT_EXTERN(int) git_smart_subtransport_http( - git_smart_subtransport **out, - git_transport *owner, - void *param); - -/** - * Create an instance of the git subtransport. - * - * @param out The newly created subtransport - * @param owner The smart transport to own this subtransport - * @return 0 or an error code - */ -GIT_EXTERN(int) git_smart_subtransport_git( - git_smart_subtransport **out, - git_transport *owner, - void *param); - -/** - * Create an instance of the ssh subtransport. - * - * @param out The newly created subtransport - * @param owner The smart transport to own this subtransport - * @return 0 or an error code - */ -GIT_EXTERN(int) git_smart_subtransport_ssh( - git_smart_subtransport **out, - git_transport *owner, - void *param); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_sys_git_transport_h +#define INCLUDE_sys_git_transport_h + +#include "git2/net.h" +#include "git2/oidarray.h" +#include "git2/proxy.h" +#include "git2/remote.h" +#include "git2/strarray.h" +#include "git2/transport.h" +#include "git2/types.h" + +/** + * @file git2/sys/transport.h + * @brief Git custom transport registration interfaces and functions + * @defgroup git_transport Git custom transport registration + * @ingroup Git + * @{ + */ + +GIT_BEGIN_DECL + +typedef struct { + const git_remote_head * const *refs; + size_t refs_len; + git_oid *shallow_roots; + size_t shallow_roots_len; + int depth; +} git_fetch_negotiation; + +struct git_transport { + unsigned int version; /**< The struct version */ + + /** + * Connect the transport to the remote repository, using the given + * direction. + */ + int GIT_CALLBACK(connect)( + git_transport *transport, + const char *url, + int direction, + const git_remote_connect_options *connect_opts); + + /** + * Resets the connect options for the given transport. This + * is useful for updating settings or callbacks for an already + * connected transport. + */ + int GIT_CALLBACK(set_connect_opts)( + git_transport *transport, + const git_remote_connect_options *connect_opts); + + /** + * Gets the capabilities for this remote repository. + * + * This function may be called after a successful call to + * `connect()`. + */ + int GIT_CALLBACK(capabilities)( + unsigned int *capabilities, + git_transport *transport); + +#ifdef GIT_EXPERIMENTAL_SHA256 + /** + * Gets the object type for the remote repository. + * + * This function may be called after a successful call to + * `connect()`. + */ + int GIT_CALLBACK(oid_type)( + git_oid_t *object_type, + git_transport *transport); +#endif + + /** + * Get the list of available references in the remote repository. + * + * This function may be called after a successful call to + * `connect()`. The array returned is owned by the transport and + * must be kept valid until the next call to one of its functions. + */ + int GIT_CALLBACK(ls)( + const git_remote_head ***out, + size_t *size, + git_transport *transport); + + /** Executes the push whose context is in the git_push object. */ + int GIT_CALLBACK(push)( + git_transport *transport, + git_push *push); + + /** + * Negotiate a fetch with the remote repository. + * + * This function may be called after a successful call to `connect()`, + * when the direction is GIT_DIRECTION_FETCH. The function performs a + * negotiation to calculate the `wants` list for the fetch. + */ + int GIT_CALLBACK(negotiate_fetch)( + git_transport *transport, + git_repository *repo, + const git_fetch_negotiation *fetch_data); + + /** + * Return the shallow roots of the remote. + * + * This function may be called after a successful call to + * `negotiate_fetch`. + */ + int GIT_CALLBACK(shallow_roots)( + git_oidarray *out, + git_transport *transport); + + /** + * Start downloading the packfile from the remote repository. + * + * This function may be called after a successful call to + * negotiate_fetch(), when the direction is GIT_DIRECTION_FETCH. + */ + int GIT_CALLBACK(download_pack)( + git_transport *transport, + git_repository *repo, + git_indexer_progress *stats); + + /** Checks to see if the transport is connected */ + int GIT_CALLBACK(is_connected)(git_transport *transport); + + /** Cancels any outstanding transport operation */ + void GIT_CALLBACK(cancel)(git_transport *transport); + + /** + * Close the connection to the remote repository. + * + * This function is the reverse of connect() -- it terminates the + * connection to the remote end. + */ + int GIT_CALLBACK(close)(git_transport *transport); + + /** Frees/destructs the git_transport object. */ + void GIT_CALLBACK(free)(git_transport *transport); +}; + +#define GIT_TRANSPORT_VERSION 1 +#define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION} + +/** + * Initializes a `git_transport` with default values. Equivalent to + * creating an instance with GIT_TRANSPORT_INIT. + * + * @param opts the `git_transport` struct to initialize + * @param version Version of struct; pass `GIT_TRANSPORT_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_transport_init( + git_transport *opts, + unsigned int version); + +/** + * Function to use to create a transport from a URL. The transport database + * is scanned to find a transport that implements the scheme of the URI (i.e. + * git:// or http://) and a transport object is returned to the caller. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param url The URL to connect to + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_new(git_transport **out, git_remote *owner, const char *url); + +/** + * Create an ssh transport with custom git command paths + * + * This is a factory function suitable for setting as the transport + * callback in a remote (or for a clone in the options). + * + * The payload argument must be a strarray pointer with the paths for + * the `git-upload-pack` and `git-receive-pack` at index 0 and 1. + * + * @param out the resulting transport + * @param owner the owning remote + * @param payload a strarray with the paths + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_ssh_with_paths(git_transport **out, git_remote *owner, void *payload); + +/** + * Add a custom transport definition, to be used in addition to the built-in + * set of transports that come with libgit2. + * + * The caller is responsible for synchronizing calls to git_transport_register + * and git_transport_unregister with other calls to the library that + * instantiate transports. + * + * @param prefix The scheme (ending in "://") to match, i.e. "git://" + * @param cb The callback used to create an instance of the transport + * @param param A fixed parameter to pass to cb at creation time + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_register( + const char *prefix, + git_transport_cb cb, + void *param); + +/** + * Unregister a custom transport definition which was previously registered + * with git_transport_register. + * + * The caller is responsible for synchronizing calls to git_transport_register + * and git_transport_unregister with other calls to the library that + * instantiate transports. + * + * @param prefix From the previous call to git_transport_register + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_unregister( + const char *prefix); + +/* Transports which come with libgit2 (match git_transport_cb). The expected + * value for "param" is listed in-line below. */ + +/** + * Create an instance of the dummy transport. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param payload You must pass NULL for this parameter. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_dummy( + git_transport **out, + git_remote *owner, + /* NULL */ void *payload); + +/** + * Create an instance of the local transport. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param payload You must pass NULL for this parameter. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_local( + git_transport **out, + git_remote *owner, + /* NULL */ void *payload); + +/** + * Create an instance of the smart transport. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param payload A pointer to a git_smart_subtransport_definition + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_smart( + git_transport **out, + git_remote *owner, + /* (git_smart_subtransport_definition *) */ void *payload); + +/** + * Call the certificate check for this transport. + * + * @param transport a smart transport + * @param cert the certificate to pass to the caller + * @param valid whether we believe the certificate is valid + * @param hostname the hostname we connected to + * @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH + * to indicate that there is no callback registered (or the callback + * refused to validate the certificate and callers should behave as + * if no callback was set), or < 0 for an error + */ +GIT_EXTERN(int) git_transport_smart_certificate_check(git_transport *transport, git_cert *cert, int valid, const char *hostname); + +/** + * Call the credentials callback for this transport + * + * @param out the pointer where the creds are to be stored + * @param transport a smart transport + * @param user the user we saw on the url (if any) + * @param methods available methods for authentication + * @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH + * to indicate that there is no callback registered (or the callback + * refused to provide credentials and callers should behave as if no + * callback was set), or < 0 for an error + */ +GIT_EXTERN(int) git_transport_smart_credentials(git_credential **out, git_transport *transport, const char *user, int methods); + +/** + * Get a copy of the remote connect options + * + * All data is copied and must be freed by the caller by calling + * `git_remote_connect_options_dispose`. + * + * @param out options struct to fill + * @param transport the transport to extract the data from. + */ +GIT_EXTERN(int) git_transport_remote_connect_options( + git_remote_connect_options *out, + git_transport *transport); + +/* + *** End of base transport interface *** + *** Begin interface for subtransports for the smart transport *** + */ + +/** Actions that the smart transport can ask a subtransport to perform */ +typedef enum { + GIT_SERVICE_UPLOADPACK_LS = 1, + GIT_SERVICE_UPLOADPACK = 2, + GIT_SERVICE_RECEIVEPACK_LS = 3, + GIT_SERVICE_RECEIVEPACK = 4 +} git_smart_service_t; + +typedef struct git_smart_subtransport git_smart_subtransport; +typedef struct git_smart_subtransport_stream git_smart_subtransport_stream; + +/** + * A stream used by the smart transport to read and write data + * from a subtransport. + * + * This provides a customization point in case you need to + * support some other communication method. + */ +struct git_smart_subtransport_stream { + git_smart_subtransport *subtransport; /**< The owning subtransport */ + + /** + * Read available data from the stream. + * + * The implementation may read less than requested. + */ + int GIT_CALLBACK(read)( + git_smart_subtransport_stream *stream, + char *buffer, + size_t buf_size, + size_t *bytes_read); + + /** + * Write data to the stream + * + * The implementation must write all data or return an error. + */ + int GIT_CALLBACK(write)( + git_smart_subtransport_stream *stream, + const char *buffer, + size_t len); + + /** Free the stream */ + void GIT_CALLBACK(free)( + git_smart_subtransport_stream *stream); +}; + +/** + * An implementation of a subtransport which carries data for the + * smart transport + */ +struct git_smart_subtransport { + /** + * Setup a subtransport stream for the requested action. + */ + int GIT_CALLBACK(action)( + git_smart_subtransport_stream **out, + git_smart_subtransport *transport, + const char *url, + git_smart_service_t action); + + /** + * Close the subtransport. + * + * Subtransports are guaranteed a call to close() between + * calls to action(), except for the following two "natural" progressions + * of actions against a constant URL: + * + * - UPLOADPACK_LS -> UPLOADPACK + * - RECEIVEPACK_LS -> RECEIVEPACK + */ + int GIT_CALLBACK(close)(git_smart_subtransport *transport); + + /** Free the subtransport */ + void GIT_CALLBACK(free)(git_smart_subtransport *transport); +}; + +/** A function which creates a new subtransport for the smart transport */ +typedef int GIT_CALLBACK(git_smart_subtransport_cb)( + git_smart_subtransport **out, + git_transport *owner, + void *param); + +/** + * Definition for a "subtransport" + * + * The smart transport knows how to speak the git protocol, but it has no + * knowledge of how to establish a connection between it and another endpoint, + * or how to move data back and forth. For this, a subtransport interface is + * declared, and the smart transport delegates this work to the subtransports. + * + * Three subtransports are provided by libgit2: ssh, git, http(s). + * + * Subtransports can either be RPC = 0 (persistent connection) or RPC = 1 + * (request/response). The smart transport handles the differences in its own + * logic. The git subtransport is RPC = 0, while http is RPC = 1. + */ +typedef struct git_smart_subtransport_definition { + /** The function to use to create the git_smart_subtransport */ + git_smart_subtransport_cb callback; + + /** + * True if the protocol is stateless; false otherwise. For example, + * http:// is stateless, but git:// is not. + */ + unsigned rpc; + + /** User-specified parameter passed to the callback */ + void *param; +} git_smart_subtransport_definition; + +/* Smart transport subtransports that come with libgit2 */ + +/** + * Create an instance of the http subtransport. + * + * This subtransport also supports https. + * + * @param out The newly created subtransport + * @param owner The smart transport to own this subtransport + * @return 0 or an error code + */ +GIT_EXTERN(int) git_smart_subtransport_http( + git_smart_subtransport **out, + git_transport *owner, + void *param); + +/** + * Create an instance of the git subtransport. + * + * @param out The newly created subtransport + * @param owner The smart transport to own this subtransport + * @return 0 or an error code + */ +GIT_EXTERN(int) git_smart_subtransport_git( + git_smart_subtransport **out, + git_transport *owner, + void *param); + +/** + * Create an instance of the ssh subtransport. + * + * @param out The newly created subtransport + * @param owner The smart transport to own this subtransport + * @return 0 or an error code + */ +GIT_EXTERN(int) git_smart_subtransport_ssh( + git_smart_subtransport **out, + git_transport *owner, + void *param); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/tag.h b/3rdparty/libgit2/include/git2/tag.h index 9830536..dce811f 100644 --- a/3rdparty/libgit2/include/git2/tag.h +++ b/3rdparty/libgit2/include/git2/tag.h @@ -1,383 +1,383 @@ -/* - * 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_tag_h__ -#define INCLUDE_git_tag_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "object.h" -#include "strarray.h" - -/** - * @file git2/tag.h - * @brief Git tag parsing routines - * @defgroup git_tag Git tag management - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Lookup a tag object from the repository. - * - * @param out pointer to the looked up tag - * @param repo the repo to use when locating the tag. - * @param id identity of the tag to locate. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tag_lookup( - git_tag **out, git_repository *repo, const git_oid *id); - -/** - * Lookup a tag object from the repository, - * given a prefix of its identifier (short id). - * - * @see git_object_lookup_prefix - * - * @param out pointer to the looked up tag - * @param repo the repo to use when locating the tag. - * @param id identity of the tag to locate. - * @param len the length of the short identifier - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tag_lookup_prefix( - git_tag **out, git_repository *repo, const git_oid *id, size_t len); - -/** - * Close an open tag - * - * You can no longer use the git_tag pointer after this call. - * - * IMPORTANT: You MUST call this method when you are through with a tag to - * release memory. Failure to do so will cause a memory leak. - * - * @param tag the tag to close - */ -GIT_EXTERN(void) git_tag_free(git_tag *tag); - -/** - * Get the id of a tag. - * - * @param tag a previously loaded tag. - * @return object identity for the tag. - */ -GIT_EXTERN(const git_oid *) git_tag_id(const git_tag *tag); - -/** - * Get the repository that contains the tag. - * - * @param tag A previously loaded tag. - * @return Repository that contains this tag. - */ -GIT_EXTERN(git_repository *) git_tag_owner(const git_tag *tag); - -/** - * Get the tagged object of a tag - * - * This method performs a repository lookup for the - * given object and returns it - * - * @param target_out pointer where to store the target - * @param tag a previously loaded tag. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tag_target(git_object **target_out, const git_tag *tag); - -/** - * Get the OID of the tagged object of a tag - * - * @param tag a previously loaded tag. - * @return pointer to the OID - */ -GIT_EXTERN(const git_oid *) git_tag_target_id(const git_tag *tag); - -/** - * Get the type of a tag's tagged object - * - * @param tag a previously loaded tag. - * @return type of the tagged object - */ -GIT_EXTERN(git_object_t) git_tag_target_type(const git_tag *tag); - -/** - * Get the name of a tag - * - * @param tag a previously loaded tag. - * @return name of the tag - */ -GIT_EXTERN(const char *) git_tag_name(const git_tag *tag); - -/** - * Get the tagger (author) of a tag - * - * @param tag a previously loaded tag. - * @return reference to the tag's author or NULL when unspecified - */ -GIT_EXTERN(const git_signature *) git_tag_tagger(const git_tag *tag); - -/** - * Get the message of a tag - * - * @param tag a previously loaded tag. - * @return message of the tag or NULL when unspecified - */ -GIT_EXTERN(const char *) git_tag_message(const git_tag *tag); - - -/** - * Create a new tag in the repository from an object - * - * A new reference will also be created pointing to - * this tag object. If `force` is true and a reference - * already exists with the given name, it'll be replaced. - * - * The message will not be cleaned up. This can be achieved - * through `git_message_prettify()`. - * - * The tag name will be checked for validity. You must avoid - * the characters '~', '^', ':', '\\', '?', '[', and '*', and the - * sequences ".." and "@{" which have special meaning to revparse. - * - * @param oid Pointer where to store the OID of the - * newly created tag. If the tag already exists, this parameter - * will be the oid of the existing tag, and the function will - * return a GIT_EEXISTS error code. - * - * @param repo Repository where to store the tag - * - * @param tag_name Name for the tag; this name is validated - * for consistency. It should also not conflict with an - * already existing tag name - * - * @param target Object to which this tag points. This object - * must belong to the given `repo`. - * - * @param tagger Signature of the tagger for this tag, and - * of the tagging time - * - * @param message Full message for this tag - * - * @param force Overwrite existing references - * - * @return 0 on success, GIT_EINVALIDSPEC or an error code - * A tag object is written to the ODB, and a proper reference - * is written in the /refs/tags folder, pointing to it - */ -GIT_EXTERN(int) git_tag_create( - git_oid *oid, - git_repository *repo, - const char *tag_name, - const git_object *target, - const git_signature *tagger, - const char *message, - int force); - -/** - * Create a new tag in the object database pointing to a git_object - * - * The message will not be cleaned up. This can be achieved - * through `git_message_prettify()`. - * - * @param oid Pointer where to store the OID of the - * newly created tag - * - * @param repo Repository where to store the tag - * - * @param tag_name Name for the tag - * - * @param target Object to which this tag points. This object - * must belong to the given `repo`. - * - * @param tagger Signature of the tagger for this tag, and - * of the tagging time - * - * @param message Full message for this tag - * - * @return 0 on success or an error code - */ -GIT_EXTERN(int) git_tag_annotation_create( - git_oid *oid, - git_repository *repo, - const char *tag_name, - const git_object *target, - const git_signature *tagger, - const char *message); - -/** - * Create a new tag in the repository from a buffer - * - * @param oid Pointer where to store the OID of the newly created tag - * @param repo Repository where to store the tag - * @param buffer Raw tag data - * @param force Overwrite existing tags - * @return 0 on success; error code otherwise - */ -GIT_EXTERN(int) git_tag_create_from_buffer( - git_oid *oid, - git_repository *repo, - const char *buffer, - int force); - -/** - * Create a new lightweight tag pointing at a target object - * - * A new direct reference will be created pointing to - * this target object. If `force` is true and a reference - * already exists with the given name, it'll be replaced. - * - * The tag name will be checked for validity. - * See `git_tag_create()` for rules about valid names. - * - * @param oid Pointer where to store the OID of the provided - * target object. If the tag already exists, this parameter - * will be filled with the oid of the existing pointed object - * and the function will return a GIT_EEXISTS error code. - * - * @param repo Repository where to store the lightweight tag - * - * @param tag_name Name for the tag; this name is validated - * for consistency. It should also not conflict with an - * already existing tag name - * - * @param target Object to which this tag points. This object - * must belong to the given `repo`. - * - * @param force Overwrite existing references - * - * @return 0 on success, GIT_EINVALIDSPEC or an error code - * A proper reference is written in the /refs/tags folder, - * pointing to the provided target object - */ -GIT_EXTERN(int) git_tag_create_lightweight( - git_oid *oid, - git_repository *repo, - const char *tag_name, - const git_object *target, - int force); - -/** - * Delete an existing tag reference. - * - * The tag name will be checked for validity. - * See `git_tag_create()` for rules about valid names. - * - * @param repo Repository where lives the tag - * - * @param tag_name Name of the tag to be deleted; - * this name is validated for consistency. - * - * @return 0 on success, GIT_EINVALIDSPEC or an error code - */ -GIT_EXTERN(int) git_tag_delete( - git_repository *repo, - const char *tag_name); - -/** - * Fill a list with all the tags in the Repository - * - * The string array will be filled with the names of the - * matching tags; these values are owned by the user and - * should be free'd manually when no longer needed, using - * `git_strarray_free`. - * - * @param tag_names Pointer to a git_strarray structure where - * the tag names will be stored - * @param repo Repository where to find the tags - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tag_list( - git_strarray *tag_names, - git_repository *repo); - -/** - * Fill a list with all the tags in the Repository - * which name match a defined pattern - * - * If an empty pattern is provided, all the tags - * will be returned. - * - * The string array will be filled with the names of the - * matching tags; these values are owned by the user and - * should be free'd manually when no longer needed, using - * `git_strarray_free`. - * - * @param tag_names Pointer to a git_strarray structure where - * the tag names will be stored - * @param pattern Standard fnmatch pattern - * @param repo Repository where to find the tags - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tag_list_match( - git_strarray *tag_names, - const char *pattern, - git_repository *repo); - -/** - * Callback used to iterate over tag names - * - * @see git_tag_foreach - * - * @param name The tag name - * @param oid The tag's OID - * @param payload Payload passed to git_tag_foreach - * @return non-zero to terminate the iteration - */ -typedef int GIT_CALLBACK(git_tag_foreach_cb)(const char *name, git_oid *oid, void *payload); - -/** - * Call callback `cb' for each tag in the repository - * - * @param repo Repository - * @param callback Callback function - * @param payload Pointer to callback data (optional) - */ -GIT_EXTERN(int) git_tag_foreach( - git_repository *repo, - git_tag_foreach_cb callback, - void *payload); - - -/** - * Recursively peel a tag until a non tag git_object is found - * - * The retrieved `tag_target` object is owned by the repository - * and should be closed with the `git_object_free` method. - * - * @param tag_target_out Pointer to the peeled git_object - * @param tag The tag to be processed - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tag_peel( - git_object **tag_target_out, - const git_tag *tag); - -/** - * Create an in-memory copy of a tag. The copy must be explicitly - * free'd or it will leak. - * - * @param out Pointer to store the copy of the tag - * @param source Original tag to copy - * @return 0 - */ -GIT_EXTERN(int) git_tag_dup(git_tag **out, git_tag *source); - -/** - * Determine whether a tag name is valid, meaning that (when prefixed - * with `refs/tags/`) that it is a valid reference name, and that any - * additional tag name restrictions are imposed (eg, it cannot start - * with a `-`). - * - * @param valid output pointer to set with validity of given tag name - * @param name a tag name to test - * @return 0 on success or an error code - */ -GIT_EXTERN(int) git_tag_name_is_valid(int *valid, const char *name); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_tag_h__ +#define INCLUDE_git_tag_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "object.h" +#include "strarray.h" + +/** + * @file git2/tag.h + * @brief Git tag parsing routines + * @defgroup git_tag Git tag management + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Lookup a tag object from the repository. + * + * @param out pointer to the looked up tag + * @param repo the repo to use when locating the tag. + * @param id identity of the tag to locate. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tag_lookup( + git_tag **out, git_repository *repo, const git_oid *id); + +/** + * Lookup a tag object from the repository, + * given a prefix of its identifier (short id). + * + * @see git_object_lookup_prefix + * + * @param out pointer to the looked up tag + * @param repo the repo to use when locating the tag. + * @param id identity of the tag to locate. + * @param len the length of the short identifier + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tag_lookup_prefix( + git_tag **out, git_repository *repo, const git_oid *id, size_t len); + +/** + * Close an open tag + * + * You can no longer use the git_tag pointer after this call. + * + * IMPORTANT: You MUST call this method when you are through with a tag to + * release memory. Failure to do so will cause a memory leak. + * + * @param tag the tag to close + */ +GIT_EXTERN(void) git_tag_free(git_tag *tag); + +/** + * Get the id of a tag. + * + * @param tag a previously loaded tag. + * @return object identity for the tag. + */ +GIT_EXTERN(const git_oid *) git_tag_id(const git_tag *tag); + +/** + * Get the repository that contains the tag. + * + * @param tag A previously loaded tag. + * @return Repository that contains this tag. + */ +GIT_EXTERN(git_repository *) git_tag_owner(const git_tag *tag); + +/** + * Get the tagged object of a tag + * + * This method performs a repository lookup for the + * given object and returns it + * + * @param target_out pointer where to store the target + * @param tag a previously loaded tag. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tag_target(git_object **target_out, const git_tag *tag); + +/** + * Get the OID of the tagged object of a tag + * + * @param tag a previously loaded tag. + * @return pointer to the OID + */ +GIT_EXTERN(const git_oid *) git_tag_target_id(const git_tag *tag); + +/** + * Get the type of a tag's tagged object + * + * @param tag a previously loaded tag. + * @return type of the tagged object + */ +GIT_EXTERN(git_object_t) git_tag_target_type(const git_tag *tag); + +/** + * Get the name of a tag + * + * @param tag a previously loaded tag. + * @return name of the tag + */ +GIT_EXTERN(const char *) git_tag_name(const git_tag *tag); + +/** + * Get the tagger (author) of a tag + * + * @param tag a previously loaded tag. + * @return reference to the tag's author or NULL when unspecified + */ +GIT_EXTERN(const git_signature *) git_tag_tagger(const git_tag *tag); + +/** + * Get the message of a tag + * + * @param tag a previously loaded tag. + * @return message of the tag or NULL when unspecified + */ +GIT_EXTERN(const char *) git_tag_message(const git_tag *tag); + + +/** + * Create a new tag in the repository from an object + * + * A new reference will also be created pointing to + * this tag object. If `force` is true and a reference + * already exists with the given name, it'll be replaced. + * + * The message will not be cleaned up. This can be achieved + * through `git_message_prettify()`. + * + * The tag name will be checked for validity. You must avoid + * the characters '~', '^', ':', '\\', '?', '[', and '*', and the + * sequences ".." and "@{" which have special meaning to revparse. + * + * @param oid Pointer where to store the OID of the + * newly created tag. If the tag already exists, this parameter + * will be the oid of the existing tag, and the function will + * return a GIT_EEXISTS error code. + * + * @param repo Repository where to store the tag + * + * @param tag_name Name for the tag; this name is validated + * for consistency. It should also not conflict with an + * already existing tag name + * + * @param target Object to which this tag points. This object + * must belong to the given `repo`. + * + * @param tagger Signature of the tagger for this tag, and + * of the tagging time + * + * @param message Full message for this tag + * + * @param force Overwrite existing references + * + * @return 0 on success, GIT_EINVALIDSPEC or an error code + * A tag object is written to the ODB, and a proper reference + * is written in the /refs/tags folder, pointing to it + */ +GIT_EXTERN(int) git_tag_create( + git_oid *oid, + git_repository *repo, + const char *tag_name, + const git_object *target, + const git_signature *tagger, + const char *message, + int force); + +/** + * Create a new tag in the object database pointing to a git_object + * + * The message will not be cleaned up. This can be achieved + * through `git_message_prettify()`. + * + * @param oid Pointer where to store the OID of the + * newly created tag + * + * @param repo Repository where to store the tag + * + * @param tag_name Name for the tag + * + * @param target Object to which this tag points. This object + * must belong to the given `repo`. + * + * @param tagger Signature of the tagger for this tag, and + * of the tagging time + * + * @param message Full message for this tag + * + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_tag_annotation_create( + git_oid *oid, + git_repository *repo, + const char *tag_name, + const git_object *target, + const git_signature *tagger, + const char *message); + +/** + * Create a new tag in the repository from a buffer + * + * @param oid Pointer where to store the OID of the newly created tag + * @param repo Repository where to store the tag + * @param buffer Raw tag data + * @param force Overwrite existing tags + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_tag_create_from_buffer( + git_oid *oid, + git_repository *repo, + const char *buffer, + int force); + +/** + * Create a new lightweight tag pointing at a target object + * + * A new direct reference will be created pointing to + * this target object. If `force` is true and a reference + * already exists with the given name, it'll be replaced. + * + * The tag name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * + * @param oid Pointer where to store the OID of the provided + * target object. If the tag already exists, this parameter + * will be filled with the oid of the existing pointed object + * and the function will return a GIT_EEXISTS error code. + * + * @param repo Repository where to store the lightweight tag + * + * @param tag_name Name for the tag; this name is validated + * for consistency. It should also not conflict with an + * already existing tag name + * + * @param target Object to which this tag points. This object + * must belong to the given `repo`. + * + * @param force Overwrite existing references + * + * @return 0 on success, GIT_EINVALIDSPEC or an error code + * A proper reference is written in the /refs/tags folder, + * pointing to the provided target object + */ +GIT_EXTERN(int) git_tag_create_lightweight( + git_oid *oid, + git_repository *repo, + const char *tag_name, + const git_object *target, + int force); + +/** + * Delete an existing tag reference. + * + * The tag name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * + * @param repo Repository where lives the tag + * + * @param tag_name Name of the tag to be deleted; + * this name is validated for consistency. + * + * @return 0 on success, GIT_EINVALIDSPEC or an error code + */ +GIT_EXTERN(int) git_tag_delete( + git_repository *repo, + const char *tag_name); + +/** + * Fill a list with all the tags in the Repository + * + * The string array will be filled with the names of the + * matching tags; these values are owned by the user and + * should be free'd manually when no longer needed, using + * `git_strarray_free`. + * + * @param tag_names Pointer to a git_strarray structure where + * the tag names will be stored + * @param repo Repository where to find the tags + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tag_list( + git_strarray *tag_names, + git_repository *repo); + +/** + * Fill a list with all the tags in the Repository + * which name match a defined pattern + * + * If an empty pattern is provided, all the tags + * will be returned. + * + * The string array will be filled with the names of the + * matching tags; these values are owned by the user and + * should be free'd manually when no longer needed, using + * `git_strarray_free`. + * + * @param tag_names Pointer to a git_strarray structure where + * the tag names will be stored + * @param pattern Standard fnmatch pattern + * @param repo Repository where to find the tags + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tag_list_match( + git_strarray *tag_names, + const char *pattern, + git_repository *repo); + +/** + * Callback used to iterate over tag names + * + * @see git_tag_foreach + * + * @param name The tag name + * @param oid The tag's OID + * @param payload Payload passed to git_tag_foreach + * @return non-zero to terminate the iteration + */ +typedef int GIT_CALLBACK(git_tag_foreach_cb)(const char *name, git_oid *oid, void *payload); + +/** + * Call callback `cb' for each tag in the repository + * + * @param repo Repository + * @param callback Callback function + * @param payload Pointer to callback data (optional) + */ +GIT_EXTERN(int) git_tag_foreach( + git_repository *repo, + git_tag_foreach_cb callback, + void *payload); + + +/** + * Recursively peel a tag until a non tag git_object is found + * + * The retrieved `tag_target` object is owned by the repository + * and should be closed with the `git_object_free` method. + * + * @param tag_target_out Pointer to the peeled git_object + * @param tag The tag to be processed + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tag_peel( + git_object **tag_target_out, + const git_tag *tag); + +/** + * Create an in-memory copy of a tag. The copy must be explicitly + * free'd or it will leak. + * + * @param out Pointer to store the copy of the tag + * @param source Original tag to copy + * @return 0 + */ +GIT_EXTERN(int) git_tag_dup(git_tag **out, git_tag *source); + +/** + * Determine whether a tag name is valid, meaning that (when prefixed + * with `refs/tags/`) that it is a valid reference name, and that any + * additional tag name restrictions are imposed (eg, it cannot start + * with a `-`). + * + * @param valid output pointer to set with validity of given tag name + * @param name a tag name to test + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_tag_name_is_valid(int *valid, const char *name); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/trace.h b/3rdparty/libgit2/include/git2/trace.h index 8cee3a9..9f7cbe0 100644 --- a/3rdparty/libgit2/include/git2/trace.h +++ b/3rdparty/libgit2/include/git2/trace.h @@ -1,67 +1,67 @@ -/* - * 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_trace_h__ -#define INCLUDE_git_trace_h__ - -#include "common.h" -#include "types.h" - -/** - * @file git2/trace.h - * @brief Git tracing configuration routines - * @defgroup git_trace Git tracing configuration routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Available tracing levels. When tracing is set to a particular level, - * callers will be provided tracing at the given level and all lower levels. - */ -typedef enum { - /** No tracing will be performed. */ - GIT_TRACE_NONE = 0, - - /** Severe errors that may impact the program's execution */ - GIT_TRACE_FATAL = 1, - - /** Errors that do not impact the program's execution */ - GIT_TRACE_ERROR = 2, - - /** Warnings that suggest abnormal data */ - GIT_TRACE_WARN = 3, - - /** Informational messages about program execution */ - GIT_TRACE_INFO = 4, - - /** Detailed data that allows for debugging */ - GIT_TRACE_DEBUG = 5, - - /** Exceptionally detailed debugging data */ - GIT_TRACE_TRACE = 6 -} git_trace_level_t; - -/** - * An instance for a tracing function - */ -typedef void GIT_CALLBACK(git_trace_cb)(git_trace_level_t level, const char *msg); - -/** - * Sets the system tracing configuration to the specified level with the - * specified callback. When system events occur at a level equal to, or - * lower than, the given level they will be reported to the given callback. - * - * @param level Level to set tracing to - * @param cb Function to call with trace data - * @return 0 or an error code - */ -GIT_EXTERN(int) git_trace_set(git_trace_level_t level, git_trace_cb cb); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_trace_h__ +#define INCLUDE_git_trace_h__ + +#include "common.h" +#include "types.h" + +/** + * @file git2/trace.h + * @brief Git tracing configuration routines + * @defgroup git_trace Git tracing configuration routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Available tracing levels. When tracing is set to a particular level, + * callers will be provided tracing at the given level and all lower levels. + */ +typedef enum { + /** No tracing will be performed. */ + GIT_TRACE_NONE = 0, + + /** Severe errors that may impact the program's execution */ + GIT_TRACE_FATAL = 1, + + /** Errors that do not impact the program's execution */ + GIT_TRACE_ERROR = 2, + + /** Warnings that suggest abnormal data */ + GIT_TRACE_WARN = 3, + + /** Informational messages about program execution */ + GIT_TRACE_INFO = 4, + + /** Detailed data that allows for debugging */ + GIT_TRACE_DEBUG = 5, + + /** Exceptionally detailed debugging data */ + GIT_TRACE_TRACE = 6 +} git_trace_level_t; + +/** + * An instance for a tracing function + */ +typedef void GIT_CALLBACK(git_trace_cb)(git_trace_level_t level, const char *msg); + +/** + * Sets the system tracing configuration to the specified level with the + * specified callback. When system events occur at a level equal to, or + * lower than, the given level they will be reported to the given callback. + * + * @param level Level to set tracing to + * @param cb Function to call with trace data + * @return 0 or an error code + */ +GIT_EXTERN(int) git_trace_set(git_trace_level_t level, git_trace_cb cb); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/transaction.h b/3rdparty/libgit2/include/git2/transaction.h index 4938570..a2dcf2e 100644 --- a/3rdparty/libgit2/include/git2/transaction.h +++ b/3rdparty/libgit2/include/git2/transaction.h @@ -1,121 +1,121 @@ -/* - * 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_transaction_h__ -#define INCLUDE_git_transaction_h__ - -#include "common.h" -#include "types.h" - -/** - * @file git2/transaction.h - * @brief Git transactional reference routines - * @defgroup git_transaction Git transactional reference routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Create a new transaction object - * - * This does not lock anything, but sets up the transaction object to - * know from which repository to lock. - * - * @param out the resulting transaction - * @param repo the repository in which to lock - * @return 0 or an error code - */ -GIT_EXTERN(int) git_transaction_new(git_transaction **out, git_repository *repo); - -/** - * Lock a reference - * - * Lock the specified reference. This is the first step to updating a - * reference. - * - * @param tx the transaction - * @param refname the reference to lock - * @return 0 or an error message - */ -GIT_EXTERN(int) git_transaction_lock_ref(git_transaction *tx, const char *refname); - -/** - * Set the target of a reference - * - * Set the target of the specified reference. This reference must be - * locked. - * - * @param tx the transaction - * @param refname reference to update - * @param target target to set the reference to - * @param sig signature to use in the reflog; pass NULL to read the identity from the config - * @param msg message to use in the reflog - * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code - */ -GIT_EXTERN(int) git_transaction_set_target(git_transaction *tx, const char *refname, const git_oid *target, const git_signature *sig, const char *msg); - -/** - * Set the target of a reference - * - * Set the target of the specified reference. This reference must be - * locked. - * - * @param tx the transaction - * @param refname reference to update - * @param target target to set the reference to - * @param sig signature to use in the reflog; pass NULL to read the identity from the config - * @param msg message to use in the reflog - * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code - */ -GIT_EXTERN(int) git_transaction_set_symbolic_target(git_transaction *tx, const char *refname, const char *target, const git_signature *sig, const char *msg); - -/** - * Set the reflog of a reference - * - * Set the specified reference's reflog. If this is combined with - * setting the target, that update won't be written to the reflog. - * - * @param tx the transaction - * @param refname the reference whose reflog to set - * @param reflog the reflog as it should be written out - * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code - */ -GIT_EXTERN(int) git_transaction_set_reflog(git_transaction *tx, const char *refname, const git_reflog *reflog); - -/** - * Remove a reference - * - * @param tx the transaction - * @param refname the reference to remove - * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code - */ -GIT_EXTERN(int) git_transaction_remove(git_transaction *tx, const char *refname); - -/** - * Commit the changes from the transaction - * - * Perform the changes that have been queued. The updates will be made - * one by one, and the first failure will stop the processing. - * - * @param tx the transaction - * @return 0 or an error code - */ -GIT_EXTERN(int) git_transaction_commit(git_transaction *tx); - -/** - * Free the resources allocated by this transaction - * - * If any references remain locked, they will be unlocked without any - * changes made to them. - * - * @param tx the transaction - */ -GIT_EXTERN(void) git_transaction_free(git_transaction *tx); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_transaction_h__ +#define INCLUDE_git_transaction_h__ + +#include "common.h" +#include "types.h" + +/** + * @file git2/transaction.h + * @brief Git transactional reference routines + * @defgroup git_transaction Git transactional reference routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a new transaction object + * + * This does not lock anything, but sets up the transaction object to + * know from which repository to lock. + * + * @param out the resulting transaction + * @param repo the repository in which to lock + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transaction_new(git_transaction **out, git_repository *repo); + +/** + * Lock a reference + * + * Lock the specified reference. This is the first step to updating a + * reference. + * + * @param tx the transaction + * @param refname the reference to lock + * @return 0 or an error message + */ +GIT_EXTERN(int) git_transaction_lock_ref(git_transaction *tx, const char *refname); + +/** + * Set the target of a reference + * + * Set the target of the specified reference. This reference must be + * locked. + * + * @param tx the transaction + * @param refname reference to update + * @param target target to set the reference to + * @param sig signature to use in the reflog; pass NULL to read the identity from the config + * @param msg message to use in the reflog + * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code + */ +GIT_EXTERN(int) git_transaction_set_target(git_transaction *tx, const char *refname, const git_oid *target, const git_signature *sig, const char *msg); + +/** + * Set the target of a reference + * + * Set the target of the specified reference. This reference must be + * locked. + * + * @param tx the transaction + * @param refname reference to update + * @param target target to set the reference to + * @param sig signature to use in the reflog; pass NULL to read the identity from the config + * @param msg message to use in the reflog + * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code + */ +GIT_EXTERN(int) git_transaction_set_symbolic_target(git_transaction *tx, const char *refname, const char *target, const git_signature *sig, const char *msg); + +/** + * Set the reflog of a reference + * + * Set the specified reference's reflog. If this is combined with + * setting the target, that update won't be written to the reflog. + * + * @param tx the transaction + * @param refname the reference whose reflog to set + * @param reflog the reflog as it should be written out + * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code + */ +GIT_EXTERN(int) git_transaction_set_reflog(git_transaction *tx, const char *refname, const git_reflog *reflog); + +/** + * Remove a reference + * + * @param tx the transaction + * @param refname the reference to remove + * @return 0, GIT_ENOTFOUND if the reference is not among the locked ones, or an error code + */ +GIT_EXTERN(int) git_transaction_remove(git_transaction *tx, const char *refname); + +/** + * Commit the changes from the transaction + * + * Perform the changes that have been queued. The updates will be made + * one by one, and the first failure will stop the processing. + * + * @param tx the transaction + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transaction_commit(git_transaction *tx); + +/** + * Free the resources allocated by this transaction + * + * If any references remain locked, they will be unlocked without any + * changes made to them. + * + * @param tx the transaction + */ +GIT_EXTERN(void) git_transaction_free(git_transaction *tx); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/transport.h b/3rdparty/libgit2/include/git2/transport.h index 5a27de9..6289df5 100644 --- a/3rdparty/libgit2/include/git2/transport.h +++ b/3rdparty/libgit2/include/git2/transport.h @@ -1,42 +1,42 @@ -/* - * 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_transport_h__ -#define INCLUDE_git_transport_h__ - -#include "indexer.h" -#include "net.h" -#include "types.h" -#include "cert.h" -#include "credential.h" - -/** - * @file git2/transport.h - * @brief Git transport interfaces and functions - * @defgroup git_transport interfaces and functions - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Callback for messages received by the transport. - * - * Return a negative value to cancel the network operation. - * - * @param str The message from the transport - * @param len The length of the message - * @param payload Payload provided by the caller - */ -typedef int GIT_CALLBACK(git_transport_message_cb)(const char *str, int len, void *payload); - -/** Signature of a function which creates a transport */ -typedef int GIT_CALLBACK(git_transport_cb)(git_transport **out, git_remote *owner, void *param); - -/** @} */ -GIT_END_DECL - -#endif +/* + * 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_transport_h__ +#define INCLUDE_git_transport_h__ + +#include "indexer.h" +#include "net.h" +#include "types.h" +#include "cert.h" +#include "credential.h" + +/** + * @file git2/transport.h + * @brief Git transport interfaces and functions + * @defgroup git_transport interfaces and functions + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Callback for messages received by the transport. + * + * Return a negative value to cancel the network operation. + * + * @param str The message from the transport + * @param len The length of the message + * @param payload Payload provided by the caller + */ +typedef int GIT_CALLBACK(git_transport_message_cb)(const char *str, int len, void *payload); + +/** Signature of a function which creates a transport */ +typedef int GIT_CALLBACK(git_transport_cb)(git_transport **out, git_remote *owner, void *param); + +/** @} */ +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/tree.h b/3rdparty/libgit2/include/git2/tree.h index ce0a609..8c1958f 100644 --- a/3rdparty/libgit2/include/git2/tree.h +++ b/3rdparty/libgit2/include/git2/tree.h @@ -1,475 +1,475 @@ -/* - * 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_tree_h__ -#define INCLUDE_git_tree_h__ - -#include "common.h" -#include "types.h" -#include "oid.h" -#include "object.h" - -/** - * @file git2/tree.h - * @brief Git tree parsing, loading routines - * @defgroup git_tree Git tree parsing, loading routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Lookup a tree object from the repository. - * - * @param out Pointer to the looked up tree - * @param repo The repo to use when locating the tree. - * @param id Identity of the tree to locate. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tree_lookup( - git_tree **out, git_repository *repo, const git_oid *id); - -/** - * Lookup a tree object from the repository, - * given a prefix of its identifier (short id). - * - * @see git_object_lookup_prefix - * - * @param out pointer to the looked up tree - * @param repo the repo to use when locating the tree. - * @param id identity of the tree to locate. - * @param len the length of the short identifier - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tree_lookup_prefix( - git_tree **out, - git_repository *repo, - const git_oid *id, - size_t len); - -/** - * Close an open tree - * - * You can no longer use the git_tree pointer after this call. - * - * IMPORTANT: You MUST call this method when you stop using a tree to - * release memory. Failure to do so will cause a memory leak. - * - * @param tree The tree to close - */ -GIT_EXTERN(void) git_tree_free(git_tree *tree); - -/** - * Get the id of a tree. - * - * @param tree a previously loaded tree. - * @return object identity for the tree. - */ -GIT_EXTERN(const git_oid *) git_tree_id(const git_tree *tree); - -/** - * Get the repository that contains the tree. - * - * @param tree A previously loaded tree. - * @return Repository that contains this tree. - */ -GIT_EXTERN(git_repository *) git_tree_owner(const git_tree *tree); - -/** - * Get the number of entries listed in a tree - * - * @param tree a previously loaded tree. - * @return the number of entries in the tree - */ -GIT_EXTERN(size_t) git_tree_entrycount(const git_tree *tree); - -/** - * Lookup a tree entry by its filename - * - * This returns a git_tree_entry that is owned by the git_tree. You don't - * have to free it, but you must not use it after the git_tree is released. - * - * @param tree a previously loaded tree. - * @param filename the filename of the desired entry - * @return the tree entry; NULL if not found - */ -GIT_EXTERN(const git_tree_entry *) git_tree_entry_byname( - const git_tree *tree, const char *filename); - -/** - * Lookup a tree entry by its position in the tree - * - * This returns a git_tree_entry that is owned by the git_tree. You don't - * have to free it, but you must not use it after the git_tree is released. - * - * @param tree a previously loaded tree. - * @param idx the position in the entry list - * @return the tree entry; NULL if not found - */ -GIT_EXTERN(const git_tree_entry *) git_tree_entry_byindex( - const git_tree *tree, size_t idx); - -/** - * Lookup a tree entry by SHA value. - * - * This returns a git_tree_entry that is owned by the git_tree. You don't - * have to free it, but you must not use it after the git_tree is released. - * - * Warning: this must examine every entry in the tree, so it is not fast. - * - * @param tree a previously loaded tree. - * @param id the sha being looked for - * @return the tree entry; NULL if not found - */ -GIT_EXTERN(const git_tree_entry *) git_tree_entry_byid( - const git_tree *tree, const git_oid *id); - -/** - * Retrieve a tree entry contained in a tree or in any of its subtrees, - * given its relative path. - * - * Unlike the other lookup functions, the returned tree entry is owned by - * the user and must be freed explicitly with `git_tree_entry_free()`. - * - * @param out Pointer where to store the tree entry - * @param root Previously loaded tree which is the root of the relative path - * @param path Path to the contained entry - * @return 0 on success; GIT_ENOTFOUND if the path does not exist - */ -GIT_EXTERN(int) git_tree_entry_bypath( - git_tree_entry **out, - const git_tree *root, - const char *path); - -/** - * Duplicate a tree entry - * - * Create a copy of a tree entry. The returned copy is owned by the user, - * and must be freed explicitly with `git_tree_entry_free()`. - * - * @param dest pointer where to store the copy - * @param source tree entry to duplicate - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tree_entry_dup(git_tree_entry **dest, const git_tree_entry *source); - -/** - * Free a user-owned tree entry - * - * IMPORTANT: This function is only needed for tree entries owned by the - * user, such as the ones returned by `git_tree_entry_dup()` or - * `git_tree_entry_bypath()`. - * - * @param entry The entry to free - */ -GIT_EXTERN(void) git_tree_entry_free(git_tree_entry *entry); - -/** - * Get the filename of a tree entry - * - * @param entry a tree entry - * @return the name of the file - */ -GIT_EXTERN(const char *) git_tree_entry_name(const git_tree_entry *entry); - -/** - * Get the id of the object pointed by the entry - * - * @param entry a tree entry - * @return the oid of the object - */ -GIT_EXTERN(const git_oid *) git_tree_entry_id(const git_tree_entry *entry); - -/** - * Get the type of the object pointed by the entry - * - * @param entry a tree entry - * @return the type of the pointed object - */ -GIT_EXTERN(git_object_t) git_tree_entry_type(const git_tree_entry *entry); - -/** - * Get the UNIX file attributes of a tree entry - * - * @param entry a tree entry - * @return filemode as an integer - */ -GIT_EXTERN(git_filemode_t) git_tree_entry_filemode(const git_tree_entry *entry); - -/** - * Get the raw UNIX file attributes of a tree entry - * - * This function does not perform any normalization and is only useful - * if you need to be able to recreate the original tree object. - * - * @param entry a tree entry - * @return filemode as an integer - */ - -GIT_EXTERN(git_filemode_t) git_tree_entry_filemode_raw(const git_tree_entry *entry); -/** - * Compare two tree entries - * - * @param e1 first tree entry - * @param e2 second tree entry - * @return <0 if e1 is before e2, 0 if e1 == e2, >0 if e1 is after e2 - */ -GIT_EXTERN(int) git_tree_entry_cmp(const git_tree_entry *e1, const git_tree_entry *e2); - -/** - * Convert a tree entry to the git_object it points to. - * - * You must call `git_object_free()` on the object when you are done with it. - * - * @param object_out pointer to the converted object - * @param repo repository where to lookup the pointed object - * @param entry a tree entry - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tree_entry_to_object( - git_object **object_out, - git_repository *repo, - const git_tree_entry *entry); - -/** - * Create a new tree builder. - * - * The tree builder can be used to create or modify trees in memory and - * write them as tree objects to the database. - * - * If the `source` parameter is not NULL, the tree builder will be - * initialized with the entries of the given tree. - * - * If the `source` parameter is NULL, the tree builder will start with no - * entries and will have to be filled manually. - * - * @param out Pointer where to store the tree builder - * @param repo Repository in which to store the object - * @param source Source tree to initialize the builder (optional) - * @return 0 on success; error code otherwise - */ -GIT_EXTERN(int) git_treebuilder_new( - git_treebuilder **out, git_repository *repo, const git_tree *source); - -/** - * Clear all the entries in the builder - * - * @param bld Builder to clear - * @return 0 on success; error code otherwise - */ -GIT_EXTERN(int) git_treebuilder_clear(git_treebuilder *bld); - -/** - * Get the number of entries listed in a treebuilder - * - * @param bld a previously loaded treebuilder. - * @return the number of entries in the treebuilder - */ -GIT_EXTERN(size_t) git_treebuilder_entrycount(git_treebuilder *bld); - -/** - * Free a tree builder - * - * This will clear all the entries and free to builder. - * Failing to free the builder after you're done using it - * will result in a memory leak - * - * @param bld Builder to free - */ -GIT_EXTERN(void) git_treebuilder_free(git_treebuilder *bld); - -/** - * Get an entry from the builder from its filename - * - * The returned entry is owned by the builder and should - * not be freed manually. - * - * @param bld Tree builder - * @param filename Name of the entry - * @return pointer to the entry; NULL if not found - */ -GIT_EXTERN(const git_tree_entry *) git_treebuilder_get( - git_treebuilder *bld, const char *filename); - -/** - * Add or update an entry to the builder - * - * Insert a new entry for `filename` in the builder with the - * given attributes. - * - * If an entry named `filename` already exists, its attributes - * will be updated with the given ones. - * - * The optional pointer `out` can be used to retrieve a pointer to the - * newly created/updated entry. Pass NULL if you do not need it. The - * pointer may not be valid past the next operation in this - * builder. Duplicate the entry if you want to keep it. - * - * By default the entry that you are inserting will be checked for - * validity; that it exists in the object database and is of the - * correct type. If you do not want this behavior, set the - * `GIT_OPT_ENABLE_STRICT_OBJECT_CREATION` library option to false. - * - * @param out Pointer to store the entry (optional) - * @param bld Tree builder - * @param filename Filename of the entry - * @param id SHA1 oid of the entry - * @param filemode Folder attributes of the entry. This parameter must - * be valued with one of the following entries: 0040000, 0100644, - * 0100755, 0120000 or 0160000. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_treebuilder_insert( - const git_tree_entry **out, - git_treebuilder *bld, - const char *filename, - const git_oid *id, - git_filemode_t filemode); - -/** - * Remove an entry from the builder by its filename - * - * @param bld Tree builder - * @param filename Filename of the entry to remove - * @return 0 or an error code - */ -GIT_EXTERN(int) git_treebuilder_remove( - git_treebuilder *bld, const char *filename); - -/** - * Callback for git_treebuilder_filter - * - * The return value is treated as a boolean, with zero indicating that the - * entry should be left alone and any non-zero value meaning that the - * entry should be removed from the treebuilder list (i.e. filtered out). - */ -typedef int GIT_CALLBACK(git_treebuilder_filter_cb)( - const git_tree_entry *entry, void *payload); - -/** - * Selectively remove entries in the tree - * - * The `filter` callback will be called for each entry in the tree with a - * pointer to the entry and the provided `payload`; if the callback returns - * non-zero, the entry will be filtered (removed from the builder). - * - * @param bld Tree builder - * @param filter Callback to filter entries - * @param payload Extra data to pass to filter callback - * @return 0 on success, non-zero callback return value, or error code - */ -GIT_EXTERN(int) git_treebuilder_filter( - git_treebuilder *bld, - git_treebuilder_filter_cb filter, - void *payload); - -/** - * Write the contents of the tree builder as a tree object - * - * The tree builder will be written to the given `repo`, and its - * identifying SHA1 hash will be stored in the `id` pointer. - * - * @param id Pointer to store the OID of the newly written tree - * @param bld Tree builder to write - * @return 0 or an error code - */ -GIT_EXTERN(int) git_treebuilder_write( - git_oid *id, git_treebuilder *bld); - -/** Callback for the tree traversal method */ -typedef int GIT_CALLBACK(git_treewalk_cb)( - const char *root, const git_tree_entry *entry, void *payload); - -/** Tree traversal modes */ -typedef enum { - GIT_TREEWALK_PRE = 0, /* Pre-order */ - GIT_TREEWALK_POST = 1 /* Post-order */ -} git_treewalk_mode; - -/** - * Traverse the entries in a tree and its subtrees in post or pre order. - * - * The entries will be traversed in the specified order, children subtrees - * will be automatically loaded as required, and the `callback` will be - * called once per entry with the current (relative) root for the entry and - * the entry data itself. - * - * If the callback returns a positive value, the passed entry will be - * skipped on the traversal (in pre mode). A negative value stops the walk. - * - * @param tree The tree to walk - * @param mode Traversal mode (pre or post-order) - * @param callback Function to call on each tree entry - * @param payload Opaque pointer to be passed on each callback - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tree_walk( - const git_tree *tree, - git_treewalk_mode mode, - git_treewalk_cb callback, - void *payload); - -/** - * Create an in-memory copy of a tree. The copy must be explicitly - * free'd or it will leak. - * - * @param out Pointer to store the copy of the tree - * @param source Original tree to copy - * @return 0 - */ -GIT_EXTERN(int) git_tree_dup(git_tree **out, git_tree *source); - -/** - * The kind of update to perform - */ -typedef enum { - /** Update or insert an entry at the specified path */ - GIT_TREE_UPDATE_UPSERT, - /** Remove an entry from the specified path */ - GIT_TREE_UPDATE_REMOVE -} git_tree_update_t; - -/** - * An action to perform during the update of a tree - */ -typedef struct { - /** Update action. If it's an removal, only the path is looked at */ - git_tree_update_t action; - /** The entry's id */ - git_oid id; - /** The filemode/kind of object */ - git_filemode_t filemode; - /** The full path from the root tree */ - const char *path; -} git_tree_update; - -/** - * Create a tree based on another one with the specified modifications - * - * Given the `baseline` perform the changes described in the list of - * `updates` and create a new tree. - * - * This function is optimized for common file/directory addition, removal and - * replacement in trees. It is much more efficient than reading the tree into a - * `git_index` and modifying that, but in exchange it is not as flexible. - * - * Deleting and adding the same entry is undefined behaviour, changing - * a tree to a blob or viceversa is not supported. - * - * @param out id of the new tree - * @param repo the repository in which to create the tree, must be the - * same as for `baseline` - * @param baseline the tree to base these changes on - * @param nupdates the number of elements in the update list - * @param updates the list of updates to perform - * @return 0 or an error code - */ -GIT_EXTERN(int) git_tree_create_updated(git_oid *out, git_repository *repo, git_tree *baseline, size_t nupdates, const git_tree_update *updates); - -/** @} */ - -GIT_END_DECL -#endif +/* + * 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_tree_h__ +#define INCLUDE_git_tree_h__ + +#include "common.h" +#include "types.h" +#include "oid.h" +#include "object.h" + +/** + * @file git2/tree.h + * @brief Git tree parsing, loading routines + * @defgroup git_tree Git tree parsing, loading routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Lookup a tree object from the repository. + * + * @param out Pointer to the looked up tree + * @param repo The repo to use when locating the tree. + * @param id Identity of the tree to locate. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tree_lookup( + git_tree **out, git_repository *repo, const git_oid *id); + +/** + * Lookup a tree object from the repository, + * given a prefix of its identifier (short id). + * + * @see git_object_lookup_prefix + * + * @param out pointer to the looked up tree + * @param repo the repo to use when locating the tree. + * @param id identity of the tree to locate. + * @param len the length of the short identifier + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tree_lookup_prefix( + git_tree **out, + git_repository *repo, + const git_oid *id, + size_t len); + +/** + * Close an open tree + * + * You can no longer use the git_tree pointer after this call. + * + * IMPORTANT: You MUST call this method when you stop using a tree to + * release memory. Failure to do so will cause a memory leak. + * + * @param tree The tree to close + */ +GIT_EXTERN(void) git_tree_free(git_tree *tree); + +/** + * Get the id of a tree. + * + * @param tree a previously loaded tree. + * @return object identity for the tree. + */ +GIT_EXTERN(const git_oid *) git_tree_id(const git_tree *tree); + +/** + * Get the repository that contains the tree. + * + * @param tree A previously loaded tree. + * @return Repository that contains this tree. + */ +GIT_EXTERN(git_repository *) git_tree_owner(const git_tree *tree); + +/** + * Get the number of entries listed in a tree + * + * @param tree a previously loaded tree. + * @return the number of entries in the tree + */ +GIT_EXTERN(size_t) git_tree_entrycount(const git_tree *tree); + +/** + * Lookup a tree entry by its filename + * + * This returns a git_tree_entry that is owned by the git_tree. You don't + * have to free it, but you must not use it after the git_tree is released. + * + * @param tree a previously loaded tree. + * @param filename the filename of the desired entry + * @return the tree entry; NULL if not found + */ +GIT_EXTERN(const git_tree_entry *) git_tree_entry_byname( + const git_tree *tree, const char *filename); + +/** + * Lookup a tree entry by its position in the tree + * + * This returns a git_tree_entry that is owned by the git_tree. You don't + * have to free it, but you must not use it after the git_tree is released. + * + * @param tree a previously loaded tree. + * @param idx the position in the entry list + * @return the tree entry; NULL if not found + */ +GIT_EXTERN(const git_tree_entry *) git_tree_entry_byindex( + const git_tree *tree, size_t idx); + +/** + * Lookup a tree entry by SHA value. + * + * This returns a git_tree_entry that is owned by the git_tree. You don't + * have to free it, but you must not use it after the git_tree is released. + * + * Warning: this must examine every entry in the tree, so it is not fast. + * + * @param tree a previously loaded tree. + * @param id the sha being looked for + * @return the tree entry; NULL if not found + */ +GIT_EXTERN(const git_tree_entry *) git_tree_entry_byid( + const git_tree *tree, const git_oid *id); + +/** + * Retrieve a tree entry contained in a tree or in any of its subtrees, + * given its relative path. + * + * Unlike the other lookup functions, the returned tree entry is owned by + * the user and must be freed explicitly with `git_tree_entry_free()`. + * + * @param out Pointer where to store the tree entry + * @param root Previously loaded tree which is the root of the relative path + * @param path Path to the contained entry + * @return 0 on success; GIT_ENOTFOUND if the path does not exist + */ +GIT_EXTERN(int) git_tree_entry_bypath( + git_tree_entry **out, + const git_tree *root, + const char *path); + +/** + * Duplicate a tree entry + * + * Create a copy of a tree entry. The returned copy is owned by the user, + * and must be freed explicitly with `git_tree_entry_free()`. + * + * @param dest pointer where to store the copy + * @param source tree entry to duplicate + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tree_entry_dup(git_tree_entry **dest, const git_tree_entry *source); + +/** + * Free a user-owned tree entry + * + * IMPORTANT: This function is only needed for tree entries owned by the + * user, such as the ones returned by `git_tree_entry_dup()` or + * `git_tree_entry_bypath()`. + * + * @param entry The entry to free + */ +GIT_EXTERN(void) git_tree_entry_free(git_tree_entry *entry); + +/** + * Get the filename of a tree entry + * + * @param entry a tree entry + * @return the name of the file + */ +GIT_EXTERN(const char *) git_tree_entry_name(const git_tree_entry *entry); + +/** + * Get the id of the object pointed by the entry + * + * @param entry a tree entry + * @return the oid of the object + */ +GIT_EXTERN(const git_oid *) git_tree_entry_id(const git_tree_entry *entry); + +/** + * Get the type of the object pointed by the entry + * + * @param entry a tree entry + * @return the type of the pointed object + */ +GIT_EXTERN(git_object_t) git_tree_entry_type(const git_tree_entry *entry); + +/** + * Get the UNIX file attributes of a tree entry + * + * @param entry a tree entry + * @return filemode as an integer + */ +GIT_EXTERN(git_filemode_t) git_tree_entry_filemode(const git_tree_entry *entry); + +/** + * Get the raw UNIX file attributes of a tree entry + * + * This function does not perform any normalization and is only useful + * if you need to be able to recreate the original tree object. + * + * @param entry a tree entry + * @return filemode as an integer + */ + +GIT_EXTERN(git_filemode_t) git_tree_entry_filemode_raw(const git_tree_entry *entry); +/** + * Compare two tree entries + * + * @param e1 first tree entry + * @param e2 second tree entry + * @return <0 if e1 is before e2, 0 if e1 == e2, >0 if e1 is after e2 + */ +GIT_EXTERN(int) git_tree_entry_cmp(const git_tree_entry *e1, const git_tree_entry *e2); + +/** + * Convert a tree entry to the git_object it points to. + * + * You must call `git_object_free()` on the object when you are done with it. + * + * @param object_out pointer to the converted object + * @param repo repository where to lookup the pointed object + * @param entry a tree entry + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tree_entry_to_object( + git_object **object_out, + git_repository *repo, + const git_tree_entry *entry); + +/** + * Create a new tree builder. + * + * The tree builder can be used to create or modify trees in memory and + * write them as tree objects to the database. + * + * If the `source` parameter is not NULL, the tree builder will be + * initialized with the entries of the given tree. + * + * If the `source` parameter is NULL, the tree builder will start with no + * entries and will have to be filled manually. + * + * @param out Pointer where to store the tree builder + * @param repo Repository in which to store the object + * @param source Source tree to initialize the builder (optional) + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_treebuilder_new( + git_treebuilder **out, git_repository *repo, const git_tree *source); + +/** + * Clear all the entries in the builder + * + * @param bld Builder to clear + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_treebuilder_clear(git_treebuilder *bld); + +/** + * Get the number of entries listed in a treebuilder + * + * @param bld a previously loaded treebuilder. + * @return the number of entries in the treebuilder + */ +GIT_EXTERN(size_t) git_treebuilder_entrycount(git_treebuilder *bld); + +/** + * Free a tree builder + * + * This will clear all the entries and free to builder. + * Failing to free the builder after you're done using it + * will result in a memory leak + * + * @param bld Builder to free + */ +GIT_EXTERN(void) git_treebuilder_free(git_treebuilder *bld); + +/** + * Get an entry from the builder from its filename + * + * The returned entry is owned by the builder and should + * not be freed manually. + * + * @param bld Tree builder + * @param filename Name of the entry + * @return pointer to the entry; NULL if not found + */ +GIT_EXTERN(const git_tree_entry *) git_treebuilder_get( + git_treebuilder *bld, const char *filename); + +/** + * Add or update an entry to the builder + * + * Insert a new entry for `filename` in the builder with the + * given attributes. + * + * If an entry named `filename` already exists, its attributes + * will be updated with the given ones. + * + * The optional pointer `out` can be used to retrieve a pointer to the + * newly created/updated entry. Pass NULL if you do not need it. The + * pointer may not be valid past the next operation in this + * builder. Duplicate the entry if you want to keep it. + * + * By default the entry that you are inserting will be checked for + * validity; that it exists in the object database and is of the + * correct type. If you do not want this behavior, set the + * `GIT_OPT_ENABLE_STRICT_OBJECT_CREATION` library option to false. + * + * @param out Pointer to store the entry (optional) + * @param bld Tree builder + * @param filename Filename of the entry + * @param id SHA1 oid of the entry + * @param filemode Folder attributes of the entry. This parameter must + * be valued with one of the following entries: 0040000, 0100644, + * 0100755, 0120000 or 0160000. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_treebuilder_insert( + const git_tree_entry **out, + git_treebuilder *bld, + const char *filename, + const git_oid *id, + git_filemode_t filemode); + +/** + * Remove an entry from the builder by its filename + * + * @param bld Tree builder + * @param filename Filename of the entry to remove + * @return 0 or an error code + */ +GIT_EXTERN(int) git_treebuilder_remove( + git_treebuilder *bld, const char *filename); + +/** + * Callback for git_treebuilder_filter + * + * The return value is treated as a boolean, with zero indicating that the + * entry should be left alone and any non-zero value meaning that the + * entry should be removed from the treebuilder list (i.e. filtered out). + */ +typedef int GIT_CALLBACK(git_treebuilder_filter_cb)( + const git_tree_entry *entry, void *payload); + +/** + * Selectively remove entries in the tree + * + * The `filter` callback will be called for each entry in the tree with a + * pointer to the entry and the provided `payload`; if the callback returns + * non-zero, the entry will be filtered (removed from the builder). + * + * @param bld Tree builder + * @param filter Callback to filter entries + * @param payload Extra data to pass to filter callback + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_treebuilder_filter( + git_treebuilder *bld, + git_treebuilder_filter_cb filter, + void *payload); + +/** + * Write the contents of the tree builder as a tree object + * + * The tree builder will be written to the given `repo`, and its + * identifying SHA1 hash will be stored in the `id` pointer. + * + * @param id Pointer to store the OID of the newly written tree + * @param bld Tree builder to write + * @return 0 or an error code + */ +GIT_EXTERN(int) git_treebuilder_write( + git_oid *id, git_treebuilder *bld); + +/** Callback for the tree traversal method */ +typedef int GIT_CALLBACK(git_treewalk_cb)( + const char *root, const git_tree_entry *entry, void *payload); + +/** Tree traversal modes */ +typedef enum { + GIT_TREEWALK_PRE = 0, /* Pre-order */ + GIT_TREEWALK_POST = 1 /* Post-order */ +} git_treewalk_mode; + +/** + * Traverse the entries in a tree and its subtrees in post or pre order. + * + * The entries will be traversed in the specified order, children subtrees + * will be automatically loaded as required, and the `callback` will be + * called once per entry with the current (relative) root for the entry and + * the entry data itself. + * + * If the callback returns a positive value, the passed entry will be + * skipped on the traversal (in pre mode). A negative value stops the walk. + * + * @param tree The tree to walk + * @param mode Traversal mode (pre or post-order) + * @param callback Function to call on each tree entry + * @param payload Opaque pointer to be passed on each callback + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tree_walk( + const git_tree *tree, + git_treewalk_mode mode, + git_treewalk_cb callback, + void *payload); + +/** + * Create an in-memory copy of a tree. The copy must be explicitly + * free'd or it will leak. + * + * @param out Pointer to store the copy of the tree + * @param source Original tree to copy + * @return 0 + */ +GIT_EXTERN(int) git_tree_dup(git_tree **out, git_tree *source); + +/** + * The kind of update to perform + */ +typedef enum { + /** Update or insert an entry at the specified path */ + GIT_TREE_UPDATE_UPSERT, + /** Remove an entry from the specified path */ + GIT_TREE_UPDATE_REMOVE +} git_tree_update_t; + +/** + * An action to perform during the update of a tree + */ +typedef struct { + /** Update action. If it's an removal, only the path is looked at */ + git_tree_update_t action; + /** The entry's id */ + git_oid id; + /** The filemode/kind of object */ + git_filemode_t filemode; + /** The full path from the root tree */ + const char *path; +} git_tree_update; + +/** + * Create a tree based on another one with the specified modifications + * + * Given the `baseline` perform the changes described in the list of + * `updates` and create a new tree. + * + * This function is optimized for common file/directory addition, removal and + * replacement in trees. It is much more efficient than reading the tree into a + * `git_index` and modifying that, but in exchange it is not as flexible. + * + * Deleting and adding the same entry is undefined behaviour, changing + * a tree to a blob or viceversa is not supported. + * + * @param out id of the new tree + * @param repo the repository in which to create the tree, must be the + * same as for `baseline` + * @param baseline the tree to base these changes on + * @param nupdates the number of elements in the update list + * @param updates the list of updates to perform + * @return 0 or an error code + */ +GIT_EXTERN(int) git_tree_create_updated(git_oid *out, git_repository *repo, git_tree *baseline, size_t nupdates, const git_tree_update *updates); + +/** @} */ + +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/include/git2/types.h b/3rdparty/libgit2/include/git2/types.h index d4b033d..95da7b9 100644 --- a/3rdparty/libgit2/include/git2/types.h +++ b/3rdparty/libgit2/include/git2/types.h @@ -1,371 +1,371 @@ -/* - * 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_types_h__ -#define INCLUDE_git_types_h__ - -#include "common.h" - -/** - * @file git2/types.h - * @brief libgit2 base & compatibility types - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Cross-platform compatibility types for off_t / time_t - * - * NOTE: This needs to be in a public header so that both the library - * implementation and client applications both agree on the same types. - * Otherwise we get undefined behavior. - * - * Use the "best" types that each platform provides. Currently we truncate - * these intermediate representations for compatibility with the git ABI, but - * if and when it changes to support 64 bit types, our code will naturally - * adapt. - * NOTE: These types should match those that are returned by our internal - * stat() functions, for all platforms. - */ -#include -#ifdef __amigaos4__ -#include -#endif - -#if defined(_MSC_VER) - -typedef __int64 git_off_t; -typedef __time64_t git_time_t; - -#elif defined(__MINGW32__) - -typedef off64_t git_off_t; -typedef __time64_t git_time_t; - -#elif defined(__HAIKU__) - -typedef __haiku_std_int64 git_off_t; -typedef __haiku_std_int64 git_time_t; - -#else /* POSIX */ - -/* - * Note: Can't use off_t since if a client program includes - * before us (directly or indirectly), they'll get 32 bit off_t in their client - * app, even though /we/ define _FILE_OFFSET_BITS=64. - */ -typedef int64_t git_off_t; -typedef int64_t git_time_t; /**< time in seconds from epoch */ - -#endif - -/** The maximum size of an object */ -typedef uint64_t git_object_size_t; - -#include "buffer.h" -#include "oid.h" - -/** Basic type (loose or packed) of any Git object. */ -typedef enum { - GIT_OBJECT_ANY = -2, /**< Object can be any of the following */ - GIT_OBJECT_INVALID = -1, /**< Object is invalid. */ - GIT_OBJECT_COMMIT = 1, /**< A commit object. */ - GIT_OBJECT_TREE = 2, /**< A tree (directory listing) object. */ - GIT_OBJECT_BLOB = 3, /**< A file revision object. */ - GIT_OBJECT_TAG = 4, /**< An annotated tag object. */ - GIT_OBJECT_OFS_DELTA = 6, /**< A delta, base is given by an offset. */ - GIT_OBJECT_REF_DELTA = 7 /**< A delta, base is given by object id. */ -} git_object_t; - -/** An open object database handle. */ -typedef struct git_odb git_odb; - -/** A custom backend in an ODB */ -typedef struct git_odb_backend git_odb_backend; - -/** An object read from the ODB */ -typedef struct git_odb_object git_odb_object; - -/** A stream to read/write from the ODB */ -typedef struct git_odb_stream git_odb_stream; - -/** A stream to write a packfile to the ODB */ -typedef struct git_odb_writepack git_odb_writepack; - -/** a writer for multi-pack-index files. */ -typedef struct git_midx_writer git_midx_writer; - -/** An open refs database handle. */ -typedef struct git_refdb git_refdb; - -/** A custom backend for refs */ -typedef struct git_refdb_backend git_refdb_backend; - -/** A git commit-graph */ -typedef struct git_commit_graph git_commit_graph; - -/** a writer for commit-graph files. */ -typedef struct git_commit_graph_writer git_commit_graph_writer; - -/** - * Representation of an existing git repository, - * including all its object contents - */ -typedef struct git_repository git_repository; - -/** Representation of a working tree */ -typedef struct git_worktree git_worktree; - -/** Representation of a generic object in a repository */ -typedef struct git_object git_object; - -/** Representation of an in-progress walk through the commits in a repo */ -typedef struct git_revwalk git_revwalk; - -/** Parsed representation of a tag object. */ -typedef struct git_tag git_tag; - -/** In-memory representation of a blob object. */ -typedef struct git_blob git_blob; - -/** Parsed representation of a commit object. */ -typedef struct git_commit git_commit; - -/** Representation of each one of the entries in a tree object. */ -typedef struct git_tree_entry git_tree_entry; - -/** Representation of a tree object. */ -typedef struct git_tree git_tree; - -/** Constructor for in-memory trees */ -typedef struct git_treebuilder git_treebuilder; - -/** Memory representation of an index file. */ -typedef struct git_index git_index; - -/** An iterator for entries in the index. */ -typedef struct git_index_iterator git_index_iterator; - -/** An iterator for conflicts in the index. */ -typedef struct git_index_conflict_iterator git_index_conflict_iterator; - -/** Memory representation of a set of config files */ -typedef struct git_config git_config; - -/** Interface to access a configuration file */ -typedef struct git_config_backend git_config_backend; - -/** Representation of a reference log entry */ -typedef struct git_reflog_entry git_reflog_entry; - -/** Representation of a reference log */ -typedef struct git_reflog git_reflog; - -/** Representation of a git note */ -typedef struct git_note git_note; - -/** Representation of a git packbuilder */ -typedef struct git_packbuilder git_packbuilder; - -/** Time in a signature */ -typedef struct git_time { - git_time_t time; /**< time in seconds from epoch */ - int offset; /**< timezone offset, in minutes */ - char sign; /**< indicator for questionable '-0000' offsets in signature */ -} git_time; - -/** An action signature (e.g. for committers, taggers, etc) */ -typedef struct git_signature { - char *name; /**< full name of the author */ - char *email; /**< email of the author */ - git_time when; /**< time when the action happened */ -} git_signature; - -/** In-memory representation of a reference. */ -typedef struct git_reference git_reference; - -/** Iterator for references */ -typedef struct git_reference_iterator git_reference_iterator; - -/** Transactional interface to references */ -typedef struct git_transaction git_transaction; - -/** Annotated commits, the input to merge and rebase. */ -typedef struct git_annotated_commit git_annotated_commit; - -/** Representation of a status collection */ -typedef struct git_status_list git_status_list; - -/** Representation of a rebase */ -typedef struct git_rebase git_rebase; - -/** Basic type of any Git reference. */ -typedef enum { - GIT_REFERENCE_INVALID = 0, /**< Invalid reference */ - GIT_REFERENCE_DIRECT = 1, /**< A reference that points at an object id */ - GIT_REFERENCE_SYMBOLIC = 2, /**< A reference that points at another reference */ - GIT_REFERENCE_ALL = GIT_REFERENCE_DIRECT | GIT_REFERENCE_SYMBOLIC -} git_reference_t; - -/** Basic type of any Git branch. */ -typedef enum { - GIT_BRANCH_LOCAL = 1, - GIT_BRANCH_REMOTE = 2, - GIT_BRANCH_ALL = GIT_BRANCH_LOCAL|GIT_BRANCH_REMOTE -} git_branch_t; - -/** Valid modes for index and tree entries. */ -typedef enum { - GIT_FILEMODE_UNREADABLE = 0000000, - GIT_FILEMODE_TREE = 0040000, - GIT_FILEMODE_BLOB = 0100644, - GIT_FILEMODE_BLOB_EXECUTABLE = 0100755, - GIT_FILEMODE_LINK = 0120000, - GIT_FILEMODE_COMMIT = 0160000 -} git_filemode_t; - -/** - * A refspec specifies the mapping between remote and local reference - * names when fetch or pushing. - */ -typedef struct git_refspec git_refspec; - -/** - * Git's idea of a remote repository. A remote can be anonymous (in - * which case it does not have backing configuration entries). - */ -typedef struct git_remote git_remote; - -/** - * Interface which represents a transport to communicate with a - * remote. - */ -typedef struct git_transport git_transport; - -/** - * Preparation for a push operation. Can be used to configure what to - * push and the level of parallelism of the packfile builder. - */ -typedef struct git_push git_push; - -/* documentation in the definition */ -typedef struct git_remote_head git_remote_head; -typedef struct git_remote_callbacks git_remote_callbacks; - -/** - * Parent type for `git_cert_hostkey` and `git_cert_x509`. - */ -typedef struct git_cert git_cert; - -/** - * Opaque structure representing a submodule. - */ -typedef struct git_submodule git_submodule; - -/** - * Submodule update values - * - * These values represent settings for the `submodule.$name.update` - * configuration value which says how to handle `git submodule update` for - * this submodule. The value is usually set in the ".gitmodules" file and - * copied to ".git/config" when the submodule is initialized. - * - * You can override this setting on a per-submodule basis with - * `git_submodule_set_update()` and write the changed value to disk using - * `git_submodule_save()`. If you have overwritten the value, you can - * revert it by passing `GIT_SUBMODULE_UPDATE_RESET` to the set function. - * - * The values are: - * - * - GIT_SUBMODULE_UPDATE_CHECKOUT: the default; when a submodule is - * updated, checkout the new detached HEAD to the submodule directory. - * - GIT_SUBMODULE_UPDATE_REBASE: update by rebasing the current checked - * out branch onto the commit from the superproject. - * - GIT_SUBMODULE_UPDATE_MERGE: update by merging the commit in the - * superproject into the current checkout out branch of the submodule. - * - GIT_SUBMODULE_UPDATE_NONE: do not update this submodule even when - * the commit in the superproject is updated. - * - GIT_SUBMODULE_UPDATE_DEFAULT: not used except as static initializer - * when we don't want any particular update rule to be specified. - */ -typedef enum { - GIT_SUBMODULE_UPDATE_CHECKOUT = 1, - GIT_SUBMODULE_UPDATE_REBASE = 2, - GIT_SUBMODULE_UPDATE_MERGE = 3, - GIT_SUBMODULE_UPDATE_NONE = 4, - - GIT_SUBMODULE_UPDATE_DEFAULT = 0 -} git_submodule_update_t; - -/** - * Submodule ignore values - * - * These values represent settings for the `submodule.$name.ignore` - * configuration value which says how deeply to look at the working - * directory when getting submodule status. - * - * You can override this value in memory on a per-submodule basis with - * `git_submodule_set_ignore()` and can write the changed value to disk - * with `git_submodule_save()`. If you have overwritten the value, you - * can revert to the on disk value by using `GIT_SUBMODULE_IGNORE_RESET`. - * - * The values are: - * - * - GIT_SUBMODULE_IGNORE_UNSPECIFIED: use the submodule's configuration - * - GIT_SUBMODULE_IGNORE_NONE: don't ignore any change - i.e. even an - * untracked file, will mark the submodule as dirty. Ignored files are - * still ignored, of course. - * - GIT_SUBMODULE_IGNORE_UNTRACKED: ignore untracked files; only changes - * to tracked files, or the index or the HEAD commit will matter. - * - GIT_SUBMODULE_IGNORE_DIRTY: ignore changes in the working directory, - * only considering changes if the HEAD of submodule has moved from the - * value in the superproject. - * - GIT_SUBMODULE_IGNORE_ALL: never check if the submodule is dirty - * - GIT_SUBMODULE_IGNORE_DEFAULT: not used except as static initializer - * when we don't want any particular ignore rule to be specified. - */ -typedef enum { - GIT_SUBMODULE_IGNORE_UNSPECIFIED = -1, /**< use the submodule's configuration */ - - GIT_SUBMODULE_IGNORE_NONE = 1, /**< any change or untracked == dirty */ - GIT_SUBMODULE_IGNORE_UNTRACKED = 2, /**< dirty if tracked files change */ - GIT_SUBMODULE_IGNORE_DIRTY = 3, /**< only dirty if HEAD moved */ - GIT_SUBMODULE_IGNORE_ALL = 4 /**< never dirty */ -} git_submodule_ignore_t; - -/** - * Options for submodule recurse. - * - * Represent the value of `submodule.$name.fetchRecurseSubmodules` - * - * * GIT_SUBMODULE_RECURSE_NO - do no recurse into submodules - * * GIT_SUBMODULE_RECURSE_YES - recurse into submodules - * * GIT_SUBMODULE_RECURSE_ONDEMAND - recurse into submodules only when - * commit not already in local clone - */ -typedef enum { - GIT_SUBMODULE_RECURSE_NO = 0, - GIT_SUBMODULE_RECURSE_YES = 1, - GIT_SUBMODULE_RECURSE_ONDEMAND = 2 -} git_submodule_recurse_t; - -typedef struct git_writestream git_writestream; - -/** A type to write in a streaming fashion, for example, for filters. */ -struct git_writestream { - int GIT_CALLBACK(write)(git_writestream *stream, const char *buffer, size_t len); - int GIT_CALLBACK(close)(git_writestream *stream); - void GIT_CALLBACK(free)(git_writestream *stream); -}; - -/** Representation of .mailmap file state. */ -typedef struct git_mailmap git_mailmap; - -/** @} */ -GIT_END_DECL - -#endif +/* + * 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_types_h__ +#define INCLUDE_git_types_h__ + +#include "common.h" + +/** + * @file git2/types.h + * @brief libgit2 base & compatibility types + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Cross-platform compatibility types for off_t / time_t + * + * NOTE: This needs to be in a public header so that both the library + * implementation and client applications both agree on the same types. + * Otherwise we get undefined behavior. + * + * Use the "best" types that each platform provides. Currently we truncate + * these intermediate representations for compatibility with the git ABI, but + * if and when it changes to support 64 bit types, our code will naturally + * adapt. + * NOTE: These types should match those that are returned by our internal + * stat() functions, for all platforms. + */ +#include +#ifdef __amigaos4__ +#include +#endif + +#if defined(_MSC_VER) + +typedef __int64 git_off_t; +typedef __time64_t git_time_t; + +#elif defined(__MINGW32__) + +typedef off64_t git_off_t; +typedef __time64_t git_time_t; + +#elif defined(__HAIKU__) + +typedef __haiku_std_int64 git_off_t; +typedef __haiku_std_int64 git_time_t; + +#else /* POSIX */ + +/* + * Note: Can't use off_t since if a client program includes + * before us (directly or indirectly), they'll get 32 bit off_t in their client + * app, even though /we/ define _FILE_OFFSET_BITS=64. + */ +typedef int64_t git_off_t; +typedef int64_t git_time_t; /**< time in seconds from epoch */ + +#endif + +/** The maximum size of an object */ +typedef uint64_t git_object_size_t; + +#include "buffer.h" +#include "oid.h" + +/** Basic type (loose or packed) of any Git object. */ +typedef enum { + GIT_OBJECT_ANY = -2, /**< Object can be any of the following */ + GIT_OBJECT_INVALID = -1, /**< Object is invalid. */ + GIT_OBJECT_COMMIT = 1, /**< A commit object. */ + GIT_OBJECT_TREE = 2, /**< A tree (directory listing) object. */ + GIT_OBJECT_BLOB = 3, /**< A file revision object. */ + GIT_OBJECT_TAG = 4, /**< An annotated tag object. */ + GIT_OBJECT_OFS_DELTA = 6, /**< A delta, base is given by an offset. */ + GIT_OBJECT_REF_DELTA = 7 /**< A delta, base is given by object id. */ +} git_object_t; + +/** An open object database handle. */ +typedef struct git_odb git_odb; + +/** A custom backend in an ODB */ +typedef struct git_odb_backend git_odb_backend; + +/** An object read from the ODB */ +typedef struct git_odb_object git_odb_object; + +/** A stream to read/write from the ODB */ +typedef struct git_odb_stream git_odb_stream; + +/** A stream to write a packfile to the ODB */ +typedef struct git_odb_writepack git_odb_writepack; + +/** a writer for multi-pack-index files. */ +typedef struct git_midx_writer git_midx_writer; + +/** An open refs database handle. */ +typedef struct git_refdb git_refdb; + +/** A custom backend for refs */ +typedef struct git_refdb_backend git_refdb_backend; + +/** A git commit-graph */ +typedef struct git_commit_graph git_commit_graph; + +/** a writer for commit-graph files. */ +typedef struct git_commit_graph_writer git_commit_graph_writer; + +/** + * Representation of an existing git repository, + * including all its object contents + */ +typedef struct git_repository git_repository; + +/** Representation of a working tree */ +typedef struct git_worktree git_worktree; + +/** Representation of a generic object in a repository */ +typedef struct git_object git_object; + +/** Representation of an in-progress walk through the commits in a repo */ +typedef struct git_revwalk git_revwalk; + +/** Parsed representation of a tag object. */ +typedef struct git_tag git_tag; + +/** In-memory representation of a blob object. */ +typedef struct git_blob git_blob; + +/** Parsed representation of a commit object. */ +typedef struct git_commit git_commit; + +/** Representation of each one of the entries in a tree object. */ +typedef struct git_tree_entry git_tree_entry; + +/** Representation of a tree object. */ +typedef struct git_tree git_tree; + +/** Constructor for in-memory trees */ +typedef struct git_treebuilder git_treebuilder; + +/** Memory representation of an index file. */ +typedef struct git_index git_index; + +/** An iterator for entries in the index. */ +typedef struct git_index_iterator git_index_iterator; + +/** An iterator for conflicts in the index. */ +typedef struct git_index_conflict_iterator git_index_conflict_iterator; + +/** Memory representation of a set of config files */ +typedef struct git_config git_config; + +/** Interface to access a configuration file */ +typedef struct git_config_backend git_config_backend; + +/** Representation of a reference log entry */ +typedef struct git_reflog_entry git_reflog_entry; + +/** Representation of a reference log */ +typedef struct git_reflog git_reflog; + +/** Representation of a git note */ +typedef struct git_note git_note; + +/** Representation of a git packbuilder */ +typedef struct git_packbuilder git_packbuilder; + +/** Time in a signature */ +typedef struct git_time { + git_time_t time; /**< time in seconds from epoch */ + int offset; /**< timezone offset, in minutes */ + char sign; /**< indicator for questionable '-0000' offsets in signature */ +} git_time; + +/** An action signature (e.g. for committers, taggers, etc) */ +typedef struct git_signature { + char *name; /**< full name of the author */ + char *email; /**< email of the author */ + git_time when; /**< time when the action happened */ +} git_signature; + +/** In-memory representation of a reference. */ +typedef struct git_reference git_reference; + +/** Iterator for references */ +typedef struct git_reference_iterator git_reference_iterator; + +/** Transactional interface to references */ +typedef struct git_transaction git_transaction; + +/** Annotated commits, the input to merge and rebase. */ +typedef struct git_annotated_commit git_annotated_commit; + +/** Representation of a status collection */ +typedef struct git_status_list git_status_list; + +/** Representation of a rebase */ +typedef struct git_rebase git_rebase; + +/** Basic type of any Git reference. */ +typedef enum { + GIT_REFERENCE_INVALID = 0, /**< Invalid reference */ + GIT_REFERENCE_DIRECT = 1, /**< A reference that points at an object id */ + GIT_REFERENCE_SYMBOLIC = 2, /**< A reference that points at another reference */ + GIT_REFERENCE_ALL = GIT_REFERENCE_DIRECT | GIT_REFERENCE_SYMBOLIC +} git_reference_t; + +/** Basic type of any Git branch. */ +typedef enum { + GIT_BRANCH_LOCAL = 1, + GIT_BRANCH_REMOTE = 2, + GIT_BRANCH_ALL = GIT_BRANCH_LOCAL|GIT_BRANCH_REMOTE +} git_branch_t; + +/** Valid modes for index and tree entries. */ +typedef enum { + GIT_FILEMODE_UNREADABLE = 0000000, + GIT_FILEMODE_TREE = 0040000, + GIT_FILEMODE_BLOB = 0100644, + GIT_FILEMODE_BLOB_EXECUTABLE = 0100755, + GIT_FILEMODE_LINK = 0120000, + GIT_FILEMODE_COMMIT = 0160000 +} git_filemode_t; + +/** + * A refspec specifies the mapping between remote and local reference + * names when fetch or pushing. + */ +typedef struct git_refspec git_refspec; + +/** + * Git's idea of a remote repository. A remote can be anonymous (in + * which case it does not have backing configuration entries). + */ +typedef struct git_remote git_remote; + +/** + * Interface which represents a transport to communicate with a + * remote. + */ +typedef struct git_transport git_transport; + +/** + * Preparation for a push operation. Can be used to configure what to + * push and the level of parallelism of the packfile builder. + */ +typedef struct git_push git_push; + +/* documentation in the definition */ +typedef struct git_remote_head git_remote_head; +typedef struct git_remote_callbacks git_remote_callbacks; + +/** + * Parent type for `git_cert_hostkey` and `git_cert_x509`. + */ +typedef struct git_cert git_cert; + +/** + * Opaque structure representing a submodule. + */ +typedef struct git_submodule git_submodule; + +/** + * Submodule update values + * + * These values represent settings for the `submodule.$name.update` + * configuration value which says how to handle `git submodule update` for + * this submodule. The value is usually set in the ".gitmodules" file and + * copied to ".git/config" when the submodule is initialized. + * + * You can override this setting on a per-submodule basis with + * `git_submodule_set_update()` and write the changed value to disk using + * `git_submodule_save()`. If you have overwritten the value, you can + * revert it by passing `GIT_SUBMODULE_UPDATE_RESET` to the set function. + * + * The values are: + * + * - GIT_SUBMODULE_UPDATE_CHECKOUT: the default; when a submodule is + * updated, checkout the new detached HEAD to the submodule directory. + * - GIT_SUBMODULE_UPDATE_REBASE: update by rebasing the current checked + * out branch onto the commit from the superproject. + * - GIT_SUBMODULE_UPDATE_MERGE: update by merging the commit in the + * superproject into the current checkout out branch of the submodule. + * - GIT_SUBMODULE_UPDATE_NONE: do not update this submodule even when + * the commit in the superproject is updated. + * - GIT_SUBMODULE_UPDATE_DEFAULT: not used except as static initializer + * when we don't want any particular update rule to be specified. + */ +typedef enum { + GIT_SUBMODULE_UPDATE_CHECKOUT = 1, + GIT_SUBMODULE_UPDATE_REBASE = 2, + GIT_SUBMODULE_UPDATE_MERGE = 3, + GIT_SUBMODULE_UPDATE_NONE = 4, + + GIT_SUBMODULE_UPDATE_DEFAULT = 0 +} git_submodule_update_t; + +/** + * Submodule ignore values + * + * These values represent settings for the `submodule.$name.ignore` + * configuration value which says how deeply to look at the working + * directory when getting submodule status. + * + * You can override this value in memory on a per-submodule basis with + * `git_submodule_set_ignore()` and can write the changed value to disk + * with `git_submodule_save()`. If you have overwritten the value, you + * can revert to the on disk value by using `GIT_SUBMODULE_IGNORE_RESET`. + * + * The values are: + * + * - GIT_SUBMODULE_IGNORE_UNSPECIFIED: use the submodule's configuration + * - GIT_SUBMODULE_IGNORE_NONE: don't ignore any change - i.e. even an + * untracked file, will mark the submodule as dirty. Ignored files are + * still ignored, of course. + * - GIT_SUBMODULE_IGNORE_UNTRACKED: ignore untracked files; only changes + * to tracked files, or the index or the HEAD commit will matter. + * - GIT_SUBMODULE_IGNORE_DIRTY: ignore changes in the working directory, + * only considering changes if the HEAD of submodule has moved from the + * value in the superproject. + * - GIT_SUBMODULE_IGNORE_ALL: never check if the submodule is dirty + * - GIT_SUBMODULE_IGNORE_DEFAULT: not used except as static initializer + * when we don't want any particular ignore rule to be specified. + */ +typedef enum { + GIT_SUBMODULE_IGNORE_UNSPECIFIED = -1, /**< use the submodule's configuration */ + + GIT_SUBMODULE_IGNORE_NONE = 1, /**< any change or untracked == dirty */ + GIT_SUBMODULE_IGNORE_UNTRACKED = 2, /**< dirty if tracked files change */ + GIT_SUBMODULE_IGNORE_DIRTY = 3, /**< only dirty if HEAD moved */ + GIT_SUBMODULE_IGNORE_ALL = 4 /**< never dirty */ +} git_submodule_ignore_t; + +/** + * Options for submodule recurse. + * + * Represent the value of `submodule.$name.fetchRecurseSubmodules` + * + * * GIT_SUBMODULE_RECURSE_NO - do no recurse into submodules + * * GIT_SUBMODULE_RECURSE_YES - recurse into submodules + * * GIT_SUBMODULE_RECURSE_ONDEMAND - recurse into submodules only when + * commit not already in local clone + */ +typedef enum { + GIT_SUBMODULE_RECURSE_NO = 0, + GIT_SUBMODULE_RECURSE_YES = 1, + GIT_SUBMODULE_RECURSE_ONDEMAND = 2 +} git_submodule_recurse_t; + +typedef struct git_writestream git_writestream; + +/** A type to write in a streaming fashion, for example, for filters. */ +struct git_writestream { + int GIT_CALLBACK(write)(git_writestream *stream, const char *buffer, size_t len); + int GIT_CALLBACK(close)(git_writestream *stream); + void GIT_CALLBACK(free)(git_writestream *stream); +}; + +/** Representation of .mailmap file state. */ +typedef struct git_mailmap git_mailmap; + +/** @} */ +GIT_END_DECL + +#endif diff --git a/3rdparty/libgit2/include/git2/version.h b/3rdparty/libgit2/include/git2/version.h index 010d4a2..684ca70 100644 --- a/3rdparty/libgit2/include/git2/version.h +++ b/3rdparty/libgit2/include/git2/version.h @@ -1,43 +1,43 @@ -/* - * 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_version_h__ -#define INCLUDE_git_version_h__ - -/** - * The version string for libgit2. This string follows semantic - * versioning (v2) guidelines. - */ -#define LIBGIT2_VERSION "1.8.0" - -/** The major version number for this version of libgit2. */ -#define LIBGIT2_VER_MAJOR 1 - -/** The minor version number for this version of libgit2. */ -#define LIBGIT2_VER_MINOR 8 - -/** The revision ("teeny") version number for this version of libgit2. */ -#define LIBGIT2_VER_REVISION 0 - -/** The Windows DLL patch number for this version of libgit2. */ -#define LIBGIT2_VER_PATCH 0 - -/** - * The prerelease string for this version of libgit2. For development - * (nightly) builds, this will be "alpha". For prereleases, this will be - * a prerelease name like "beta" or "rc1". For final releases, this will - * be `NULL`. - */ -#define LIBGIT2_VER_PRERELEASE NULL - -/** - * The library ABI soversion for this version of libgit2. This should - * only be changed when the library has a breaking ABI change, and so - * may trail the library's version number. - */ -#define LIBGIT2_SOVERSION "1.8" - -#endif +/* + * 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_version_h__ +#define INCLUDE_git_version_h__ + +/** + * The version string for libgit2. This string follows semantic + * versioning (v2) guidelines. + */ +#define LIBGIT2_VERSION "1.8.0" + +/** The major version number for this version of libgit2. */ +#define LIBGIT2_VER_MAJOR 1 + +/** The minor version number for this version of libgit2. */ +#define LIBGIT2_VER_MINOR 8 + +/** The revision ("teeny") version number for this version of libgit2. */ +#define LIBGIT2_VER_REVISION 0 + +/** The Windows DLL patch number for this version of libgit2. */ +#define LIBGIT2_VER_PATCH 0 + +/** + * The prerelease string for this version of libgit2. For development + * (nightly) builds, this will be "alpha". For prereleases, this will be + * a prerelease name like "beta" or "rc1". For final releases, this will + * be `NULL`. + */ +#define LIBGIT2_VER_PRERELEASE NULL + +/** + * The library ABI soversion for this version of libgit2. This should + * only be changed when the library has a breaking ABI change, and so + * may trail the library's version number. + */ +#define LIBGIT2_SOVERSION "1.8" + +#endif diff --git a/3rdparty/libgit2/include/git2/worktree.h b/3rdparty/libgit2/include/git2/worktree.h index 1af4c03..c333e56 100644 --- a/3rdparty/libgit2/include/git2/worktree.h +++ b/3rdparty/libgit2/include/git2/worktree.h @@ -1,270 +1,270 @@ -/* - * 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_worktree_h__ -#define INCLUDE_git_worktree_h__ - -#include "common.h" -#include "buffer.h" -#include "types.h" -#include "strarray.h" - -/** - * @file git2/worktrees.h - * @brief Git worktree related functions - * @defgroup git_commit Git worktree related functions - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * List names of linked working trees - * - * The returned list should be released with `git_strarray_free` - * when no longer needed. - * - * @param out pointer to the array of working tree names - * @param repo the repo to use when listing working trees - * @return 0 or an error code - */ -GIT_EXTERN(int) git_worktree_list(git_strarray *out, git_repository *repo); - -/** - * Lookup a working tree by its name for a given repository - * - * @param out Output pointer to looked up worktree or `NULL` - * @param repo The repository containing worktrees - * @param name Name of the working tree to look up - * @return 0 or an error code - */ -GIT_EXTERN(int) git_worktree_lookup(git_worktree **out, git_repository *repo, const char *name); - -/** - * Open a worktree of a given repository - * - * If a repository is not the main tree but a worktree, this - * function will look up the worktree inside the parent - * repository and create a new `git_worktree` structure. - * - * @param out Out-pointer for the newly allocated worktree - * @param repo Repository to look up worktree for - * @return 0 or an error code - */ -GIT_EXTERN(int) git_worktree_open_from_repository(git_worktree **out, git_repository *repo); - -/** - * Free a previously allocated worktree - * - * @param wt worktree handle to close. If NULL nothing occurs. - */ -GIT_EXTERN(void) git_worktree_free(git_worktree *wt); - -/** - * Check if worktree is valid - * - * A valid worktree requires both the git data structures inside - * the linked parent repository and the linked working copy to be - * present. - * - * @param wt Worktree to check - * @return 0 when worktree is valid, error-code otherwise - */ -GIT_EXTERN(int) git_worktree_validate(const git_worktree *wt); - -/** - * Worktree add options structure - * - * Initialize with `GIT_WORKTREE_ADD_OPTIONS_INIT`. Alternatively, you can - * use `git_worktree_add_options_init`. - * - */ -typedef struct git_worktree_add_options { - unsigned int version; - - int lock; /**< lock newly created worktree */ - int checkout_existing; /**< allow checkout of existing branch matching worktree name */ - git_reference *ref; /**< reference to use for the new worktree HEAD */ - - /** - * Options for the checkout. - */ - git_checkout_options checkout_options; -} git_worktree_add_options; - -#define GIT_WORKTREE_ADD_OPTIONS_VERSION 1 -#define GIT_WORKTREE_ADD_OPTIONS_INIT { GIT_WORKTREE_ADD_OPTIONS_VERSION, \ - 0, 0, NULL, GIT_CHECKOUT_OPTIONS_INIT } - -/** - * Initialize git_worktree_add_options structure - * - * Initializes a `git_worktree_add_options` with default values. Equivalent to - * creating an instance with `GIT_WORKTREE_ADD_OPTIONS_INIT`. - * - * @param opts The `git_worktree_add_options` struct to initialize. - * @param version The struct version; pass `GIT_WORKTREE_ADD_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_worktree_add_options_init(git_worktree_add_options *opts, - unsigned int version); - -/** - * Add a new working tree - * - * Add a new working tree for the repository, that is create the - * required data structures inside the repository and check out - * the current HEAD at `path` - * - * @param out Output pointer containing new working tree - * @param repo Repository to create working tree for - * @param name Name of the working tree - * @param path Path to create working tree at - * @param opts Options to modify default behavior. May be NULL - * @return 0 or an error code - */ -GIT_EXTERN(int) git_worktree_add(git_worktree **out, git_repository *repo, - const char *name, const char *path, - const git_worktree_add_options *opts); - -/** - * Lock worktree if not already locked - * - * Lock a worktree, optionally specifying a reason why the linked - * working tree is being locked. - * - * @param wt Worktree to lock - * @param reason Reason why the working tree is being locked - * @return 0 on success, non-zero otherwise - */ -GIT_EXTERN(int) git_worktree_lock(git_worktree *wt, const char *reason); - -/** - * Unlock a locked worktree - * - * @param wt Worktree to unlock - * @return 0 on success, 1 if worktree was not locked, error-code - * otherwise - */ -GIT_EXTERN(int) git_worktree_unlock(git_worktree *wt); - -/** - * Check if worktree is locked - * - * A worktree may be locked if the linked working tree is stored - * on a portable device which is not available. - * - * @param reason Buffer to store reason in. If NULL no reason is stored. - * @param wt Worktree to check - * @return 0 when the working tree not locked, a value greater - * than zero if it is locked, less than zero if there was an - * error - */ -GIT_EXTERN(int) git_worktree_is_locked(git_buf *reason, const git_worktree *wt); - -/** - * Retrieve the name of the worktree - * - * @param wt Worktree to get the name for - * @return The worktree's name. The pointer returned is valid for the - * lifetime of the git_worktree - */ -GIT_EXTERN(const char *) git_worktree_name(const git_worktree *wt); - -/** - * Retrieve the filesystem path for the worktree - * - * @param wt Worktree to get the path for - * @return The worktree's filesystem path. The pointer returned - * is valid for the lifetime of the git_worktree. - */ -GIT_EXTERN(const char *) git_worktree_path(const git_worktree *wt); - -/** - * Flags which can be passed to git_worktree_prune to alter its - * behavior. - */ -typedef enum { - /* Prune working tree even if working tree is valid */ - GIT_WORKTREE_PRUNE_VALID = 1u << 0, - /* Prune working tree even if it is locked */ - GIT_WORKTREE_PRUNE_LOCKED = 1u << 1, - /* Prune checked out working tree */ - GIT_WORKTREE_PRUNE_WORKING_TREE = 1u << 2 -} git_worktree_prune_t; - -/** - * Worktree prune options structure - * - * Initialize with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`. Alternatively, you can - * use `git_worktree_prune_options_init`. - * - */ -typedef struct git_worktree_prune_options { - unsigned int version; - - /** A combination of `git_worktree_prune_t` */ - uint32_t flags; -} git_worktree_prune_options; - -#define GIT_WORKTREE_PRUNE_OPTIONS_VERSION 1 -#define GIT_WORKTREE_PRUNE_OPTIONS_INIT {GIT_WORKTREE_PRUNE_OPTIONS_VERSION,0} - -/** - * Initialize git_worktree_prune_options structure - * - * Initializes a `git_worktree_prune_options` with default values. Equivalent to - * creating an instance with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`. - * - * @param opts The `git_worktree_prune_options` struct to initialize. - * @param version The struct version; pass `GIT_WORKTREE_PRUNE_OPTIONS_VERSION`. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_worktree_prune_options_init( - git_worktree_prune_options *opts, - unsigned int version); - -/** - * Is the worktree prunable with the given options? - * - * A worktree is not prunable in the following scenarios: - * - * - the worktree is linking to a valid on-disk worktree. The - * `valid` member will cause this check to be ignored. - * - the worktree is locked. The `locked` flag will cause this - * check to be ignored. - * - * If the worktree is not valid and not locked or if the above - * flags have been passed in, this function will return a - * positive value. If the worktree is not prunable, an error - * message will be set (visible in `giterr_last`) with details about - * why. - * - * @param wt Worktree to check. - * @param opts The prunable options. - * @return 1 if the worktree is prunable, 0 otherwise, or an error code. - */ -GIT_EXTERN(int) git_worktree_is_prunable(git_worktree *wt, - git_worktree_prune_options *opts); - -/** - * Prune working tree - * - * Prune the working tree, that is remove the git data - * structures on disk. The repository will only be pruned of - * `git_worktree_is_prunable` succeeds. - * - * @param wt Worktree to prune - * @param opts Specifies which checks to override. See - * `git_worktree_is_prunable`. May be NULL - * @return 0 or an error code - */ -GIT_EXTERN(int) git_worktree_prune(git_worktree *wt, - git_worktree_prune_options *opts); - -/** @} */ -GIT_END_DECL -#endif +/* + * 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_worktree_h__ +#define INCLUDE_git_worktree_h__ + +#include "common.h" +#include "buffer.h" +#include "types.h" +#include "strarray.h" + +/** + * @file git2/worktrees.h + * @brief Git worktree related functions + * @defgroup git_commit Git worktree related functions + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * List names of linked working trees + * + * The returned list should be released with `git_strarray_free` + * when no longer needed. + * + * @param out pointer to the array of working tree names + * @param repo the repo to use when listing working trees + * @return 0 or an error code + */ +GIT_EXTERN(int) git_worktree_list(git_strarray *out, git_repository *repo); + +/** + * Lookup a working tree by its name for a given repository + * + * @param out Output pointer to looked up worktree or `NULL` + * @param repo The repository containing worktrees + * @param name Name of the working tree to look up + * @return 0 or an error code + */ +GIT_EXTERN(int) git_worktree_lookup(git_worktree **out, git_repository *repo, const char *name); + +/** + * Open a worktree of a given repository + * + * If a repository is not the main tree but a worktree, this + * function will look up the worktree inside the parent + * repository and create a new `git_worktree` structure. + * + * @param out Out-pointer for the newly allocated worktree + * @param repo Repository to look up worktree for + * @return 0 or an error code + */ +GIT_EXTERN(int) git_worktree_open_from_repository(git_worktree **out, git_repository *repo); + +/** + * Free a previously allocated worktree + * + * @param wt worktree handle to close. If NULL nothing occurs. + */ +GIT_EXTERN(void) git_worktree_free(git_worktree *wt); + +/** + * Check if worktree is valid + * + * A valid worktree requires both the git data structures inside + * the linked parent repository and the linked working copy to be + * present. + * + * @param wt Worktree to check + * @return 0 when worktree is valid, error-code otherwise + */ +GIT_EXTERN(int) git_worktree_validate(const git_worktree *wt); + +/** + * Worktree add options structure + * + * Initialize with `GIT_WORKTREE_ADD_OPTIONS_INIT`. Alternatively, you can + * use `git_worktree_add_options_init`. + * + */ +typedef struct git_worktree_add_options { + unsigned int version; + + int lock; /**< lock newly created worktree */ + int checkout_existing; /**< allow checkout of existing branch matching worktree name */ + git_reference *ref; /**< reference to use for the new worktree HEAD */ + + /** + * Options for the checkout. + */ + git_checkout_options checkout_options; +} git_worktree_add_options; + +#define GIT_WORKTREE_ADD_OPTIONS_VERSION 1 +#define GIT_WORKTREE_ADD_OPTIONS_INIT { GIT_WORKTREE_ADD_OPTIONS_VERSION, \ + 0, 0, NULL, GIT_CHECKOUT_OPTIONS_INIT } + +/** + * Initialize git_worktree_add_options structure + * + * Initializes a `git_worktree_add_options` with default values. Equivalent to + * creating an instance with `GIT_WORKTREE_ADD_OPTIONS_INIT`. + * + * @param opts The `git_worktree_add_options` struct to initialize. + * @param version The struct version; pass `GIT_WORKTREE_ADD_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_worktree_add_options_init(git_worktree_add_options *opts, + unsigned int version); + +/** + * Add a new working tree + * + * Add a new working tree for the repository, that is create the + * required data structures inside the repository and check out + * the current HEAD at `path` + * + * @param out Output pointer containing new working tree + * @param repo Repository to create working tree for + * @param name Name of the working tree + * @param path Path to create working tree at + * @param opts Options to modify default behavior. May be NULL + * @return 0 or an error code + */ +GIT_EXTERN(int) git_worktree_add(git_worktree **out, git_repository *repo, + const char *name, const char *path, + const git_worktree_add_options *opts); + +/** + * Lock worktree if not already locked + * + * Lock a worktree, optionally specifying a reason why the linked + * working tree is being locked. + * + * @param wt Worktree to lock + * @param reason Reason why the working tree is being locked + * @return 0 on success, non-zero otherwise + */ +GIT_EXTERN(int) git_worktree_lock(git_worktree *wt, const char *reason); + +/** + * Unlock a locked worktree + * + * @param wt Worktree to unlock + * @return 0 on success, 1 if worktree was not locked, error-code + * otherwise + */ +GIT_EXTERN(int) git_worktree_unlock(git_worktree *wt); + +/** + * Check if worktree is locked + * + * A worktree may be locked if the linked working tree is stored + * on a portable device which is not available. + * + * @param reason Buffer to store reason in. If NULL no reason is stored. + * @param wt Worktree to check + * @return 0 when the working tree not locked, a value greater + * than zero if it is locked, less than zero if there was an + * error + */ +GIT_EXTERN(int) git_worktree_is_locked(git_buf *reason, const git_worktree *wt); + +/** + * Retrieve the name of the worktree + * + * @param wt Worktree to get the name for + * @return The worktree's name. The pointer returned is valid for the + * lifetime of the git_worktree + */ +GIT_EXTERN(const char *) git_worktree_name(const git_worktree *wt); + +/** + * Retrieve the filesystem path for the worktree + * + * @param wt Worktree to get the path for + * @return The worktree's filesystem path. The pointer returned + * is valid for the lifetime of the git_worktree. + */ +GIT_EXTERN(const char *) git_worktree_path(const git_worktree *wt); + +/** + * Flags which can be passed to git_worktree_prune to alter its + * behavior. + */ +typedef enum { + /* Prune working tree even if working tree is valid */ + GIT_WORKTREE_PRUNE_VALID = 1u << 0, + /* Prune working tree even if it is locked */ + GIT_WORKTREE_PRUNE_LOCKED = 1u << 1, + /* Prune checked out working tree */ + GIT_WORKTREE_PRUNE_WORKING_TREE = 1u << 2 +} git_worktree_prune_t; + +/** + * Worktree prune options structure + * + * Initialize with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`. Alternatively, you can + * use `git_worktree_prune_options_init`. + * + */ +typedef struct git_worktree_prune_options { + unsigned int version; + + /** A combination of `git_worktree_prune_t` */ + uint32_t flags; +} git_worktree_prune_options; + +#define GIT_WORKTREE_PRUNE_OPTIONS_VERSION 1 +#define GIT_WORKTREE_PRUNE_OPTIONS_INIT {GIT_WORKTREE_PRUNE_OPTIONS_VERSION,0} + +/** + * Initialize git_worktree_prune_options structure + * + * Initializes a `git_worktree_prune_options` with default values. Equivalent to + * creating an instance with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`. + * + * @param opts The `git_worktree_prune_options` struct to initialize. + * @param version The struct version; pass `GIT_WORKTREE_PRUNE_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_worktree_prune_options_init( + git_worktree_prune_options *opts, + unsigned int version); + +/** + * Is the worktree prunable with the given options? + * + * A worktree is not prunable in the following scenarios: + * + * - the worktree is linking to a valid on-disk worktree. The + * `valid` member will cause this check to be ignored. + * - the worktree is locked. The `locked` flag will cause this + * check to be ignored. + * + * If the worktree is not valid and not locked or if the above + * flags have been passed in, this function will return a + * positive value. If the worktree is not prunable, an error + * message will be set (visible in `giterr_last`) with details about + * why. + * + * @param wt Worktree to check. + * @param opts The prunable options. + * @return 1 if the worktree is prunable, 0 otherwise, or an error code. + */ +GIT_EXTERN(int) git_worktree_is_prunable(git_worktree *wt, + git_worktree_prune_options *opts); + +/** + * Prune working tree + * + * Prune the working tree, that is remove the git data + * structures on disk. The repository will only be pruned of + * `git_worktree_is_prunable` succeeds. + * + * @param wt Worktree to prune + * @param opts Specifies which checks to override. See + * `git_worktree_is_prunable`. May be NULL + * @return 0 or an error code + */ +GIT_EXTERN(int) git_worktree_prune(git_worktree *wt, + git_worktree_prune_options *opts); + +/** @} */ +GIT_END_DECL +#endif diff --git a/3rdparty/libgit2/lib/libgit2.a b/3rdparty/libgit2/lib/libgit2.a index 920c7eb..ca561f9 100644 Binary files a/3rdparty/libgit2/lib/libgit2.a and b/3rdparty/libgit2/lib/libgit2.a differ diff --git a/3rdparty/libgit2/lib/pkgconfig/libgit2.pc b/3rdparty/libgit2/lib/pkgconfig/libgit2.pc index bb26689..c992525 100644 --- a/3rdparty/libgit2/lib/pkgconfig/libgit2.pc +++ b/3rdparty/libgit2/lib/pkgconfig/libgit2.pc @@ -1,11 +1,11 @@ -prefix="F:/SourceCode/libgit2/build/libgit2" -libdir="F:/SourceCode/libgit2/build/libgit2/lib" -includedir="F:/SourceCode/libgit2/build/libgit2/include" - -Name: libgit2 -Description: The git library, take 2 -Version: 1.8.2 -Libs: -L${libdir} -lgit2 -Libs.private: -lrpcrt4 -lcrypt32 -lole32 -lws2_32 -lsecur32 -Requires.private: libpcre zlib -Cflags: -I${includedir} +prefix="F:/SourceCode/XSteam/3rdparty/libgit2" +libdir="F:/SourceCode/XSteam/3rdparty/libgit2/lib" +includedir="F:/SourceCode/XSteam/3rdparty/libgit2/include" + +Name: libgit2 +Description: The git library, take 2 +Version: 1.8.2 +Libs: -L${libdir} -lgit2 +Libs.private: -lrpcrt4 -lcrypt32 -lole32 -lws2_32 -lsecur32 +Requires.private: libpcre2-8 zlib +Cflags: -I${includedir} diff --git a/CMakeLists.txt b/CMakeLists.txt index eab1000..b8c6082 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -98,23 +98,6 @@ else() message(STATUS "CURL_FOUND=NOT") endif() -#增加LIBLUA库 -find_package(PkgConfig REQUIRED) -pkg_check_modules(LIBLUA REQUIRED IMPORTED_TARGET Lua5.3) -if(LIBLUA_FOUND) - include_directories(${LIBLUA_INCLUDE_DIRS}) - link_directories(${LIBLUA_LIBRARY_DIRS}) - message(STATUS "------------LIBLUA INFO----------------------") - message(STATUS "LIBLUA_FOUND=Yes") - message(STATUS "LIBLUA_INCLUDE_DIR_PATH=${LIBLUA_INCLUDE_DIRS}") - message(STATUS "LIBLUA Found:->LIBLUA_Version:${LIBLUA_VERSION}") - message(STATUS "LIBLUA Found:->LIBLUA_LIBRARIES:${LIBLUA_LIBRARIES}") - message(STATUS "LIBLUA Found:->LIBLUA_LINK_LIBRARIES:${LIBLUA_LINK_LIBRARIES}") - message(STATUS "LIBLUA Found:->LIBLUA_STATIC_LIBRARIES:${LIBLUA_STATIC_LIBRARIES}") - message(STATUS "------------MSG INFO END---------------------") -else() - message(STATUS "LIBLUA_FOUND=NOT") -endif() #JSON库 include_directories(${JSON}/include) @@ -171,6 +154,6 @@ target_link_options(${PROJECT_NAME} PUBLIC -Wl,--allow-multiple-definition) target_link_libraries( ${PROJECT_NAME} PRIVATE Qt6::Core Qt6::Gui Qt6::Widgets Qt6::Network - ${LIBGIT2_STATIC_LIBRARIES} -lpcre.dll -lz -lrpcrt4 -lwinhttp + ${LIBGIT2_STATIC_LIBRARIES} -lpcre2-8.dll -lz -lrpcrt4 -lwinhttp ${CURL_LINK_LIBRARIES} )