[Hiper-related work] Added a function called curl_multi_assign() that will

                                  Changelog

Daniel (27 July 2006)

- [Hiper-related work] Added a function called curl_multi_assign() that will

  set a private pointer added to the internal libcurl hash table for the

  particular socket passed in to this function:

  CURLMcode curl_multi_assign(CURLM *multi_handle,

                              curl_socket_t sockfd,

                              void *sockp);

  'sockp' being a custom pointer set by the application to be associated with

  this socket. The socket has to be already existing and in-use by libcurl,

  like having already called the callback telling about its existance.

  The set hashp pointer will then be passed on to the callback in upcoming

  calls when this same socket is used (in the brand new 'socketp' argument).

Daniel (26 July 2006)

- Dan Nelson added the CURLOPT_FTP_ALTERNATIVE_TO_USER libcurl option and curl

  tool option named --ftp-alternative-to-user. It provides a mean to send a

 curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3	 \

 libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3		 \

 curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3		 \

 curl_multi_timeout.3 curl_formget.3

 curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3

HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html		  \

 curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html	  \

 curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \

 curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html	  \

 curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html	  \

 curl_formget.html

 curl_formget.html curl_multi_assign.html

PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \

 curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf	  \

 curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf	  \

 curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf	  \

 curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf	  \

 curl_formget.pdf

 curl_formget.pdf curl_multi_assign.pdf

CLEANFILES = $(HTMLPAGES) $(PDFPAGES)

.BI "CURLcode curl_global_init(long " flags ");"

.ad

.SH DESCRIPTION

This function sets up the program environment that libcurl needs.  Think

of it as an extension of the library loader.

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.

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.  Don't use any other

value unless you are familiar with and mean to control internal operations

of libcurl.

value unless you are familiar with and mean to control internal operations of

libcurl.

\fBThis function is not thread safe.\fP  You must not call it when any

other thread in the program (i.e. a thread sharing the same memory) is

running.  This doesn't just mean no other thread that is using

libcurl.  Because \fIcurl_global_init()\fP calls functions of other

libraries that are similarly thread unsafe, it could conflict with any

other thread that uses these other libraries.

\fBThis function is not thread safe.\fP You must not call it when any other

thread in the program (i.e. a thread sharing the same memory) is running.

This doesn't just mean no other thread that is using libcurl.  Because

\fIcurl_global_init()\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 \fBlibcurl\fP(3) of global environment

requirements for details of how to use this function.

See the description in \fBlibcurl\fP(3) of global environment requirements for

details of how to use this function.

.SH FLAGS

.TP 5

.\" $Id$

.\"

.TH curl_multi_assign 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual"

.SH NAME

curl_multi_assign \- set data to associated with an internal socket

.SH SYNOPSIS

#include <curl/curl.h>

CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd,

                            void *sockptr);

.SH DESCRIPTION

This function assigns an association in the multi handle between the given

socket and a private pointer of the application. This is (only) useful for

\fIcurl_multi_socket(3)\fP uses.

When set, the \fIsockptr\fP pointer will be passed to all future socket

callbacks for the specific \fIsockfd\fP socket.

If the given \fIsockfd\fP isn't already in use by libcurl, this function will

return an error.

libcurl only keeps one single pointer associated with a socket, so calling

this function several times for the same socket will make 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 will need and

then libcurl can just as well do it since it already has an internal hash

table lookup for this.

.SH "RETURN VALUE"

The standard CURLMcode for multi interface error codes.

.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(3)\fP approach.

When our socket-callback get 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 don't have to find the struct associated with this socket by ourselves.

.SH AVAILABILITY

This function was added in libcurl 7.15.5, although not deemed stable yet.

.SH "SEE ALSO"

.BR curl_multi_setopt "(3), " curl_multi_socket "(3) "

the curl_socket_callback given in the \fBparam\fP argument. They update the

status with changes since the previous time a \fIcurl_multi_socket(3)\fP

function was called. If the given callback pointer is NULL, no callback will

be called. Set the callback's fourth argument with \fICURLMOPT_SOCKETDATA\fP.

See \fIcurl_multi_socket(3)\fP for more callback details.

be called. Set the callback's \fBuserp\fP argument with

\fICURLMOPT_SOCKETDATA\fP.  See \fIcurl_multi_socket(3)\fP for more callback

details.

.IP CURLMOPT_SOCKETDATA

Pass a pointer to whatever you want passed to the curl_socket_callback's forth

argument, the userp pointer. This is not used by libcurl but only passed-thru