|_|_|_.__/ \___|\__,_|_| |_|
- 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);
--- /dev/null
+.\" 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!
projects / thirdparty / curl.git / commitdiff
