Annotation of embedaddon/curl/docs/libcurl/libcurl.3, revision 1.1
1.1 ! misho 1: .\" **************************************************************************
! 2: .\" * _ _ ____ _
! 3: .\" * Project ___| | | | _ \| |
! 4: .\" * / __| | | | |_) | |
! 5: .\" * | (__| |_| | _ <| |___
! 6: .\" * \___|\___/|_| \_\_____|
! 7: .\" *
! 8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
! 9: .\" *
! 10: .\" * This software is licensed as described in the file COPYING, which
! 11: .\" * you should have received as part of this distribution. The terms
! 12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
! 13: .\" *
! 14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
! 15: .\" * copies of the Software, and permit persons to whom the Software is
! 16: .\" * furnished to do so, under the terms of the COPYING file.
! 17: .\" *
! 18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
! 19: .\" * KIND, either express or implied.
! 20: .\" *
! 21: .\" **************************************************************************
! 22: .TH libcurl 3 "March 23, 2020" "libcurl 7.70.0" "libcurl overview"
! 23:
! 24: .SH NAME
! 25: libcurl \- client-side URL transfers
! 26: .SH DESCRIPTION
! 27: This is a short overview on how to use libcurl in your C programs. There are
! 28: specific man pages for each function mentioned in here. There are also the
! 29: \fIlibcurl-easy(3)\fP man page, the \fIlibcurl-multi(3)\fP man page, the
! 30: \fIlibcurl-share(3)\fP man page and the \fIlibcurl-tutorial(3)\fP man page for
! 31: in-depth understanding on how to program with libcurl.
! 32:
! 33: There are many bindings available that bring libcurl access to your favourite
! 34: language. Look elsewhere for documentation on those.
! 35:
! 36: libcurl has a global constant environment that you must set up and maintain
! 37: while using libcurl. This essentially means you call
! 38: \fIcurl_global_init(3)\fP at the start of your program and
! 39: \fIcurl_global_cleanup(3)\fP at the end. See \fBGLOBAL CONSTANTS\fP below for
! 40: details.
! 41:
! 42: If libcurl was compiled with support for multiple SSL backends, the function
! 43: \fIcurl_global_sslset(3)\fP can be called before \fIcurl_global_init(3)\fP
! 44: to select the active SSL backend.
! 45:
! 46: To transfer files, you create an "easy handle" using \fIcurl_easy_init(3)\fP
! 47: for a single individual transfer (in either direction). You then set your
! 48: desired set of options in that handle with \fIcurl_easy_setopt(3)\fP. Options
! 49: you set with \fIcurl_easy_setopt(3)\fP stick. They will be used on every
! 50: repeated use of this handle until you either change the option, or you reset
! 51: them all with \fIcurl_easy_reset(3)\fP.
! 52:
! 53: To actually transfer data you have the option of using the "easy" interface,
! 54: or the "multi" interface.
! 55:
! 56: The easy interface is a synchronous interface with which you call
! 57: \fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is
! 58: completed, the function returns and you can continue. More details are found in
! 59: the \fIlibcurl-easy(3)\fP man page.
! 60:
! 61: The multi interface on the other hand is an asynchronous interface, that you
! 62: call and that performs only a little piece of the transfer on each invoke. It
! 63: is perfect if you want to do things while the transfer is in progress, or
! 64: similar. The multi interface allows you to select() on libcurl action, and
! 65: even to easily download multiple files simultaneously using a single
! 66: thread. See further details in the \fIlibcurl-multi(3)\fP man page.
! 67:
! 68: You can have multiple easy handles share certain data, even if they are used
! 69: in different threads. This magic is setup using the share interface, as
! 70: described in the \fIlibcurl-share(3)\fP man page.
! 71:
! 72: There is also a series of other helpful functions to use, including these:
! 73: .RS
! 74: .IP curl_version_info()
! 75: gets detailed libcurl (and other used libraries) version info
! 76: .IP curl_getdate()
! 77: converts a date string to time_t
! 78: .IP curl_easy_getinfo()
! 79: get information about a performed transfer
! 80: .IP curl_formadd()
! 81: helps building an HTTP form POST
! 82: .IP curl_formfree()
! 83: free a list built with \fIcurl_formadd(3)\fP
! 84: .IP curl_slist_append()
! 85: builds a linked list
! 86: .IP curl_slist_free_all()
! 87: frees a whole curl_slist
! 88: .RE
! 89:
! 90: .SH "LINKING WITH LIBCURL"
! 91: On unix-like machines, there's a tool named curl-config that gets installed
! 92: with the rest of the curl stuff when 'make install' is performed.
! 93:
! 94: curl-config is added to make it easier for applications to link with libcurl
! 95: and developers to learn about libcurl and how to use it.
! 96:
! 97: Run 'curl-config --libs' to get the (additional) linker options you need to
! 98: link with the particular version of libcurl you've installed. See the
! 99: \fIcurl-config(1)\fP man page for further details.
! 100:
! 101: Unix-like operating system that ship libcurl as part of their distributions
! 102: often don't provide the curl-config tool, but simply install the library and
! 103: headers in the common path for this purpose.
! 104:
! 105: Many Linux and similar systems use pkg-config to provide build and link
! 106: options about libraries and libcurl supports that as well.
! 107: .SH "LIBCURL SYMBOL NAMES"
! 108: All public functions in the libcurl interface are prefixed with 'curl_' (with
! 109: a lowercase c). You can find other functions in the library source code, but
! 110: other prefixes indicate that the functions are private and may change without
! 111: further notice in the next release.
! 112:
! 113: Only use documented functions and functionality!
! 114: .SH "PORTABILITY"
! 115: libcurl works
! 116: .B exactly
! 117: the same, on any of the platforms it compiles and builds on.
! 118: .SH "THREADS"
! 119: libcurl is thread safe but there are a few exceptions. Refer to
! 120: \fIlibcurl-thread(3)\fP for more information.
! 121:
! 122: .SH "PERSISTENT CONNECTIONS"
! 123: Persistent connections means that libcurl can re-use the same connection for
! 124: several transfers, if the conditions are right.
! 125:
! 126: libcurl will \fBalways\fP attempt to use persistent connections. Whenever you
! 127: use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl
! 128: will attempt to use an existing connection to do the transfer, and if none
! 129: exists it'll open a new one that will be subject for re-use on a possible
! 130: following call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP.
! 131:
! 132: To allow libcurl to take full advantage of persistent connections, you should
! 133: do as many of your file transfers as possible using the same handle.
! 134:
! 135: If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all
! 136: the possibly open connections held by libcurl will be closed and forgotten.
! 137:
! 138: When you've created a multi handle and are using the multi interface, the
! 139: connection pool is instead kept in the multi handle so closing and creating
! 140: new easy handles to do transfers will not affect them. Instead all added easy
! 141: handles can take advantage of the single shared pool.
! 142: .SH "GLOBAL CONSTANTS"
! 143: There are a variety of constants that libcurl uses, mainly through its
! 144: internal use of other libraries, which are too complicated for the
! 145: library loader to set up. Therefore, a program must call a library
! 146: function after the program is loaded and running to finish setting up
! 147: the library code. For example, when libcurl is built for SSL
! 148: capability via the GNU TLS library, there is an elaborate tree inside
! 149: that library that describes the SSL protocol.
! 150:
! 151: \fIcurl_global_init(3)\fP is the function that you must call. This may
! 152: allocate resources (e.g. the memory for the GNU TLS tree mentioned above), so
! 153: the companion function \fIcurl_global_cleanup(3)\fP releases them.
! 154:
! 155: The basic rule for constructing a program that uses libcurl is this: Call
! 156: \fIcurl_global_init(3)\fP, with a \fICURL_GLOBAL_ALL\fP argument, immediately
! 157: after the program starts, while it is still only one thread and before it uses
! 158: libcurl at all. Call \fIcurl_global_cleanup(3)\fP immediately before the
! 159: program exits, when the program is again only one thread and after its last
! 160: use of libcurl.
! 161:
! 162: You can call both of these multiple times, as long as all calls meet
! 163: these requirements and the number of calls to each is the same.
! 164:
! 165: It isn't actually required that the functions be called at the beginning
! 166: and end of the program -- that's just usually the easiest way to do it.
! 167: It \fIis\fP required that the functions be called when no other thread
! 168: in the program is running.
! 169:
! 170: These global constant functions are \fInot thread safe\fP, so you must
! 171: not call them when any other thread in the program is running. It
! 172: isn't good enough that no other thread is using libcurl at the time,
! 173: because these functions internally call similar functions of other
! 174: libraries, and those functions are similarly thread-unsafe. You can't
! 175: generally know what these libraries are, or whether other threads are
! 176: using them.
! 177:
! 178: The global constant situation merits special consideration when the
! 179: code you are writing to use libcurl is not the main program, but rather
! 180: a modular piece of a program, e.g. another library. As a module,
! 181: your code doesn't know about other parts of the program -- it doesn't
! 182: know whether they use libcurl or not. And its code doesn't necessarily
! 183: run at the start and end of the whole program.
! 184:
! 185: A module like this must have global constant functions of its own, just like
! 186: \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus
! 187: has control at the beginning and end of the program and has a place to call
! 188: the libcurl functions. Note that if multiple modules in the program use
! 189: libcurl, they all will separately call the libcurl functions, and that's OK
! 190: because only the first \fIcurl_global_init(3)\fP and the last
! 191: \fIcurl_global_cleanup(3)\fP in a program change anything. (libcurl uses a
! 192: reference count in static memory).
! 193:
! 194: In a C++ module, it is common to deal with the global constant situation by
! 195: defining a special class that represents the global constant environment of
! 196: the module. A program always has exactly one object of the class, in static
! 197: storage. That way, the program automatically calls the constructor of the
! 198: object as the program starts up and the destructor as it terminates. As the
! 199: author of this libcurl-using module, you can make the constructor call
! 200: \fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP
! 201: and satisfy libcurl's requirements without your user having to think about it.
! 202: (Caveat: If you are initializing libcurl from a Windows DLL you should not
! 203: initialize it from DllMain or a static initializer because Windows holds the
! 204: loader lock during that time and it could cause a deadlock.)
! 205:
! 206: \fIcurl_global_init(3)\fP has an argument that tells what particular parts of
! 207: the global constant environment to set up. In order to successfully use any
! 208: value except \fICURL_GLOBAL_ALL\fP (which says to set up the whole thing), you
! 209: must have specific knowledge of internal workings of libcurl and all other
! 210: parts of the program of which it is part.
! 211:
! 212: A special part of the global constant environment is the identity of the
! 213: memory allocator. \fIcurl_global_init(3)\fP selects the system default memory
! 214: allocator, but you can use \fIcurl_global_init_mem(3)\fP to supply one of your
! 215: own. However, there is no way to use \fIcurl_global_init_mem(3)\fP in a
! 216: modular program -- all modules in the program that might use libcurl would
! 217: have to agree on one allocator.
! 218:
! 219: There is a failsafe in libcurl that makes it usable in simple situations
! 220: without you having to worry about the global constant environment at all:
! 221: \fIcurl_easy_init(3)\fP sets up the environment itself if it hasn't been done
! 222: yet. The resources it acquires to do so get released by the operating system
! 223: automatically when the program exits.
! 224:
! 225: This failsafe feature exists mainly for backward compatibility because
! 226: there was a time when the global functions didn't exist. Because it
! 227: is sufficient only in the simplest of programs, it is not recommended
! 228: for any program to rely on it.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to libcurl.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl