libcurl v7 adjustments

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!