diff options
| -rw-r--r-- | docs/README.libcurl | 143 | ||||
| -rw-r--r-- | docs/curl_easy_cleanup.3 | 25 | ||||
| -rw-r--r-- | docs/curl_easy_init.3 | 25 | ||||
| -rw-r--r-- | docs/curl_easy_setopt.3 | 75 |
4 files changed, 167 insertions, 101 deletions
diff --git a/docs/README.libcurl b/docs/README.libcurl index ccec76150..9d6da3d60 100644 --- a/docs/README.libcurl +++ b/docs/README.libcurl @@ -5,104 +5,45 @@ |_|_|_.__/ \___|\__,_|_| |_| - How To Use Libcurl In Your Program: - (by Ralph Beckmann <rabe@uni-paderborn.de>) - -NOTE: If you plan to use libcurl.a in Threads under Linux, do not use the old -gcc-2.7.x because the function 'gethostbyname' seems not to be thread-safe, -that is to say an unavoidable SEGMENTATION FAULT might occur. - - -1. a) In a C-Program: - #include "curl.h" - - b) In a C++-Program: - extern "C" { - #include "curl.h" - } - -2. char *url="http://www.domain.com"; - curl_urlget (URGTAG_URL, url, - URGTAG_FLAGS, CONF_NOPROGRESS, - URGTAG_ERRORBUFFER, errorBuffer, - URGTAG_WRITEFUNCTION, (size_t (*)(void *, int, int, FILE -*))handle_data, - URGTAG_TIMEOUT, 30, /* or anything You want */ - ... - URGTAG_DONE); - -3. size_t handle_data (const void *ptr, size_t size, size_t nitems, - FILE *stream) - { - (void)stream; /* stop complaining using g++ -Wall */ - if ((int)nitems <= 0) { - return (size_t)0; - } - fprintf(stdout, (char *)ptr); /* or do anything else with it */ - return nitems; - } - -4. Compile Your Program with -I$(CURL_DIR)/include - -5. Link Your Program together with $(CURL_DIR)/lib/libcurl.a - - Small Example of How To Use libcurl - ----------------------------------------------------------------------- -/* Full example that uses libcurl.a to fetch web pages. */ -/* curlthreads.c */ -/* - Test-Program by Ralph Beckmann for using curl in POSIX-Threads */ -/* Change *url1 and *url2 to textual long and slow non-FRAMESET websites! */ -/* - 1. Compile with gcc or g++ as $(CC): - $(CC) -c -Wall -pedantic curlthreads.c -I$(CURL_DIR)/include - - 2. Link with: - - Linux: - $(CC) -o curlthreads curlthreads.o $(CURL_DIR)/lib/libcurl.a -lpthread --lm - - Solaris: - $(CC) -o curlthreads curlthreads.o $(CURL_DIR)/lib/libcurl.a -lpthread --lm -lsocket -lnsl -*/ - -#include <pthread.h> -#include <stdio.h> -#ifdef __cplusplus -extern "C" { -#include "curl.h" -} -#else -#include "curl.h" -#endif - -size_t storedata (const void *ptr, size_t size, size_t nitems, FILE *stream) { - (void)ptr; (void)stream; /* just to stop g++ -Wall complaining */ - fprintf(stdout, "Thread #%i reads %i Bytes.\n", - (int)pthread_self(), (int)(nitems*size)); - return (nitems); -} - -void *urlfetcher(void *url) { - curl_urlget (URGTAG_URL, url, - URGTAG_FLAGS, CONF_NOPROGRESS | CONF_FAILONERROR, - URGTAG_WRITEFUNCTION, (size_t (*)(void *, int, int, FILE -*))storedata, - URGTAG_DONE); - return NULL; -} - -int main(void) { - char *url1="www.sun.com"; - char *url2="www.microsoft.com"; - - pthread_t thread_id1, thread_id2; - pthread_create(&thread_id1, NULL, urlfetcher, (void *)url1); - pthread_create(&thread_id2, NULL, urlfetcher, (void *)url2); - pthread_join(thread_id1, NULL); - pthread_join(thread_id2, NULL); - - fprintf(stdout, "Ready.\n"); - - return 0; -} + How To Use Libcurl In Your Program + +Interfaces + + libcurl currently offers two different interfaces to the URL transfer + engine. They can be seen as one low-level and one high-level, in the sense + that the low-level one will allow you to deal with a lot more details but on + the other hand not offer as many fancy features (such as Location: + following). The high-level interface is supposed to be a built-in + implementation of the low-level interface. You will not be able to mix + function calls from the different layers. + + As we currently ONLY support the high-level interface, the so called easy + interface, I will not attempt to describe any low-level functions at this + point. + +Function descriptions + + The interface is meant to be very simple for very simple + implementations. Thus, we have minimized the number of entries. + +Main Operations + + You INIT the lib + + You SET OPTIONS you want the lib to use. + + You tell the lib to PERFORM the transfer. + + You CLEAN UP the lib + + done. + + See the separate man pages for the libcurl functions for details. + + + CURLcode curl_easy_setopt(CURL *curl, CURLoption option, ...); + + + +CURLcode curl_easy_perform(CURL *curl); +void curl_easy_cleanup(CURL *curl); diff --git a/docs/curl_easy_cleanup.3 b/docs/curl_easy_cleanup.3 new file mode 100644 index 000000000..c0e950139 --- /dev/null +++ b/docs/curl_easy_cleanup.3 @@ -0,0 +1,25 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" Written by Daniel.Stenberg@haxx.nu +.\" +.TH curl_easy_cleanup 3 "22 May 2000" "Curl 7.0" "libcurl Manual" +.SH NAME +curl_easy_cleanup - End a libcurl "easy" session +.SH SYNOPSIS +.B #include <curl/easy.h> +.sp +.BI "curl_easy_cleanup(CURL *" handle "); +.ad +.SH DESCRIPTION +This function must be the last function to call for a curl session. It is the +opposite of the +.I curl_easy_init +function and must be called with the same +.I handle +as input as the curl_easy_init call returned. +.SH RETURN VALUE +None +.SH "SEE ALSO" +.BR curl_easy_init "(3), " +.SH BUGS +Surely there are some, you tell me! diff --git a/docs/curl_easy_init.3 b/docs/curl_easy_init.3 new file mode 100644 index 000000000..5f7bc00bd --- /dev/null +++ b/docs/curl_easy_init.3 @@ -0,0 +1,25 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" Written by Daniel.Stenberg@haxx.nu +.\" +.TH curl_easy_init 3 "22 May 2000" "Curl 7.0" "libcurl Manual" +.SH NAME +curl_easy_init - Start a libcurl "easy" session +.SH SYNOPSIS +.B #include <curl/easy.h> +.sp +.BI "CURL *curl_easy_init( );" +.ad +.SH DESCRIPTION +This function must be the first function to call, and it returns a CURL handle +that you shall use as input to the other easy-functions. The init calls +intializes curl and this call MUST have a corresponding call to +.I curl_easy_cleanup +when the operation is complete. +.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), " +.SH BUGS +Surely there are some, you tell me! diff --git a/docs/curl_easy_setopt.3 b/docs/curl_easy_setopt.3 new file mode 100644 index 000000000..ad2244b87 --- /dev/null +++ b/docs/curl_easy_setopt.3 @@ -0,0 +1,75 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" Written by Daniel.Stenberg@haxx.nu +.\" +.TH curl_easy_setopt 3 "22 May 2000" "Curl 7.0" "libcurl Manual" +.SH NAME +curl_easy_setopt - Set curl easy-session options +.SH SYNOPSIS +.B #include <curl/easy.h> +.sp +.BI "CURLcode curl_easy_setopt(CURL *" handle ", CURLoption "option ", ...); +.ad +.SH DESCRIPTION +curl_easy_setopt() is called to tell libcurl how to behave in a number of +ways. Most operations in libcurl have default actions, and by using the +appropriate options you can make them behave differently (as documented). All +options are set with the +.I option +followed by a parameter. That parameter can be a long, a function pointer or +an object pointer, all depending on what the option in question expects. Read +this manual carefully as bad input values may cause libcurl to behave badly! + +The +.I "handle" +is the return code from the +.I "curl_easy_init" +call. +.SH OPTIONS +.TP 0.8i +.B CURLOPT_FILE +Data pointer to pass instead of FILE * to the file write function. Note that +if you specify the +.I CURLOPT_WRITEFUNCTION +, this is the pointer you'll get as input. +.TP +.B CURLOPT_WRITEFUNCTION +Function pointer that should use match the following prototype: +.BI "size_t function( void *ptr, size_t size, size_t nmemb, FILE *stream);" +This function gets called by libcurl as soon as there is received data that +needs to be written down. The size of the data pointed to by +.I ptr +is +.I size +multiplied with +.I nmemb. +Return the number of bytes actually written or return -1 to signal error to the library (it will cause it to abort the transfer). +.TP +.B CURLOPT_INFILE +Data pointer to pass instead of FILE * to the file read function. Note that if +you specify the +.I CURLOPT_READFUNCTION +, this is the pointer you'll get as input. +.TP +.B CURLOPT_READFUNCTION +Function pointer that should use match the following prototype: +.BI "size_t function( void *ptr, size_t size, size_t nmemb, FILE *stream);" +This function gets called by libcurl as soon as it needs to read data in order +to send it to the peer. The data area pointed at by the pointer +.I ptr +may be filled with at most +.I size +multiplied with +.I nmemb +number of bytes. Your function must return the actual number of bytes that you +stored in that memory area. Returning -1 will signal an error to the library +and cause it to abort the current transfer immediately. +.PP +.SH RETURN VALUE +0 means the option was set properly, non-zero means an error as +.I <curl/curl.h> +defines +.SH "SEE ALSO" +.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " +.SH BUGS +Surely there are some, you tell me! |