diff options
| -rw-r--r-- | net/libfetch/files/fetch.cat3 | 660 |
1 files changed, 484 insertions, 176 deletions
diff --git a/net/libfetch/files/fetch.cat3 b/net/libfetch/files/fetch.cat3 index 90556f69839..0e10929d612 100644 --- a/net/libfetch/files/fetch.cat3 +++ b/net/libfetch/files/fetch.cat3 @@ -1,198 +1,506 @@ -These functions implement a high-level library for retrieving and -uploading files using Uniform Resource Locators (URLs). takes a -URL in the form of a null-terminated string and splits it into -its components function according to the Common Internet Scheme -Syntax detailed in RFC 1738. A regular expression which produces -this syntax is: scheme:(//(user(:pwd)?@)?host(:port)?)?/(docu- -ment)? If the URL does not seem to begin with a scheme name, it -is assumed to be a local path. Only absolute path names are ac- -cepted. Note that some components of the URL are not necessarily -relevant to all URL schemes. For instance, the file scheme only -needs the and components. quotes any unsafe character in the URL -automatically. This is not done by copies an existing structure. -and return a pointer to a structure, which is defined as follows -in #define URL_SCHEMELEN 16 #define URL_USERLEN 256 #define -URL_PWDLEN 256 #define URL_HOSTLEN 255 - -struct url { - char scheme[URL_SCHEMELEN + 1]; - char user[URL_USERLEN + 1]; - char pwd[URL_PWDLEN + 1]; - char host[URL_HOSTLEN + 1]; - int port; - char *doc; - off_t offset; - size_t length; - time_t last_modified; }; The pointer returned by and -should be freed using The size of is not part of the ABI. and -constitute the recommended interface to the library. They exam- -ine the URL passed to them to determine the transfer method, and -call the appropriate lower-level functions to perform the actual -transfer. also returns the remote document's metadata in the -structure pointed to by the argument. The argument is a string -of characters which specify transfer options. The meaning of the -individual flags is scheme-dependent, and is detailed in the ap- -propriate section below. attempts to obtain the requested docu- -ment's metadata and fill in the structure pointed to by its sec- -ond argument. The structure is defined as follows in struct -url_stat { - off_t size; - time_t atime; - time_t mtime; }; If the size could not be obtained from -the server, the field is set to -1. If the modification time -could not be obtained from the server, the field is set to the -epoch. If the access time could not be obtained from the server, -the field is set to the modification time. attempts to list the -contents of the directory pointed to by the URL provided. The -pattern can be a simple glob-like expression as hint. Callers -should not depend on the server to filter names. If successful, -it appends the list of entries to the structure. The structure -is defined as follows in struct url_list { - size_t length; - size_t alloc_size; - struct url *urls; }; The list should be initialized by call- -ing and the entries be freed by calling returns the URL as -string. returns the path name part of the URL with any quoting -undone. Query arguments and fragment identifiers are not includ- -ed. returns the last component of the path name as returned by -and return a string that should be deallocated with after use. -and are similar to and except that they expect a pre-parsed URL -in the form of a pointer to a rather than a string. All of the -and functions return a pointer to a stream which can be used to -read or write data from or to the requested document, respective- -ly. Note that although the implementation details of the indi- -vidual access methods vary, it can generally be assumed that a -stream returned by one of the or functions is read-only, and that -a stream returned by one of the functions is write-only. If the -(if-modified-since) flag is specified, the library will try to -fetch the content only if it is newer than For HTTP an HTTP head- -er is sent. For FTP a command is sent first and compared local- -ly. For FILE the source file is compared. and provide access to -documents which are files in a locally mounted file system. Only -the component of the URL is used. and do not accept any flags. -accepts the (append to file) flag. If that flag is specified, -the data written to the stream returned by will be appended to -the previous contents of the file, instead of replacing them. -and implement the FTP protocol as described in RFC 959. By de- -fault will attempt to use passive mode first and only fallback to -active mode if the server reports a syntax error. If the (ac- -tive) flag is specified, a passive connection is not tried and -active mode is used directly. If the (low) flag is specified, -data sockets will be allocated in the low (or default) port range -instead of the high port range (see If the (direct) flag is spec- -ified, and will use a direct connection even if a proxy server is -defined. If no user name or password is given, the library will -attempt an anonymous login, with user name "anonymous" and pass- -word "anonymous@hostname". The and functions implement the -HTTP/1.1 protocol. With a little luck, there is even a chance -that they comply with RFC 2616 and RFC 2617. If the (direct) -flag is specified, and will use a direct connection even if a -proxy server is defined. Since there seems to be no good way of -implementing the HTTP PUT method in a manner consistent with the -rest of the library, is currently unimplemented. Apart from set- -ting the appropriate environment variables and specifying the us- -er name and password in the URL or the the calling program has -the option of defining an authentication function with the fol- -lowing prototype: The callback function should fill in the and -fields in the provided and return 0 on success, or any other val- -ue to indicate failure. To register the authentication callback, -simply set to point at it. The callback will be used whenever a -site requires authentication and the appropriate environment -variables are not set. This interface is experimental and may be -subject to change. returns a pointer to a containing the indi- -vidual components of the URL. If it is unable to allocate memo- -ry, or the URL is syntactically incorrect, returns a pointer. -The functions return 0 on success and -1 on failure. All other -functions return a stream pointer which may be used to access the -requested document, or if an error occurred. The following error -codes are defined in Operation aborted Authentication failed Ser- -vice unavailable File exists File system full Informational re- -sponse Insufficient memory File has moved Network error No error -Protocol error Resolver error Server error Temporary error Opera- -tion timed out File is not available Unknown error Invalid URL -The accompanying error message includes a protocol-specific error -code and message, e.g. "File is not available (404 Not Found)" -Specifies a host name or IP address to which sockets used for -outgoing connections will be bound. Default FTP login if none -was provided in the URL. If set to anything but forces the FTP -code to use passive mode. Default FTP password if the remote -server requests one and none was provided in the URL. URL of the -proxy to use for FTP requests. The document part is ignored. -FTP and HTTP proxies are supported; if no scheme is specified, -FTP is assumed. If the proxy is an FTP proxy, will send as user -name to the proxy, where is the real user name, and is the name -of the FTP server. If this variable is set to an empty string, -no proxy will be used for FTP requests, even if the variable is -set. Same as for compatibility. Specifies HTTP authorization -parameters as a colon-separated list of items. The first and -second item are the authorization scheme and realm respectively; -further items are scheme-dependent. Currently, only basic autho- -rization is supported. Basic authorization requires two parame- -ters: the user name and password, in that order. This variable -is only used if the server requires authorization and no user -name or password was specified in the URL. URL of the proxy to -use for HTTP requests. The document part is ignored. Only HTTP -proxies are supported for HTTP requests. If no port number is -specified, the default is 3128. Note that this proxy will also -be used for FTP documents, unless the variable is set. Same as -for compatibility. Specifies authorization parameters for the -HTTP proxy in the same format as the variable. This variable is -used if and only if connected to an HTTP proxy, and is ignored if -a user and/or a password were specified in the proxy URL. Speci- -fies the referrer URL to use for HTTP requests. If set to the -document URL will be used as referrer URL. Specifies the User- -Agent string to use for HTTP requests. This can be useful when -working with HTTP origin or proxy servers that differentiate be- -tween user agents. Specifies a file to use instead of to look up -login names and passwords for FTP sites. See for a description -of the file format. This feature is experimental. Either a sin- -gle asterisk, which disables the use of proxies altogether, or a -comma- or whitespace-separated list of hosts for which proxies -should not be used. Same as for compatibility. To access a -proxy server on port 8080, set the environment variable in a man- -ner similar to this: If the proxy server requires authentication, -there are two options available for passing the authentication -data. The first method is by using the proxy URL: The second -method is by using the environment variable: -HTTP_PROXY=http://proxy.example.com:8080 HTTP_PROXY_AUTH=ba- -sic:*:user:pwd To disable the use of a proxy for an HTTP server -running on the local host, define as follows: NO_PROXY=local- -host,127.0.0.1 The library first appeared in The library was -mostly written by with numerous suggestions from and other devel- -opers. It replaces the older library written by and This manual -page was written by Some parts of the library are not yet imple- -mented. The most notable examples of this are and FTP proxy sup- -port. There is no way to select a proxy at run-time other than -setting the or environment variables as appropriate. does not -understand or obey 305 (Use Proxy) replies. Error numbers are -unique only within a certain context; the error codes used for -FTP and HTTP overlap, as do those used for resolver and system -errors. For instance, error code 202 means "Command not imple- -mented, superfluous at this site" in an FTP context and "Accept- -ed" in an HTTP context. does not check that the result of an -MDTM command is a valid date. The man page is incomplete, poorly -written and produces badly formatted text. The error reporting -mechanism is unsatisfactory. Some parts of the code are not ful- -ly reentrant. +FETCH(3) NetBSD Library Functions Manual FETCH(3) +NNAAMMEE + ffeettcchhMMaakkeeUURRLL, ffeettcchhPPaarrsseeUURRLL, ffeettcchhCCooppyyUURRLL, ffeettcchhFFrreeeeUURRLL, ffeettcchhXXGGeettUURRLL, + ffeettcchhGGeettUURRLL, ffeettcchhPPuuttUURRLL, ffeettcchhSSttaattUURRLL, ffeettcchhLLiissttUURRLL, ffeettcchhXXGGeett, + ffeettcchhGGeett, ffeettcchhPPuutt, ffeettcchhSSttaatt, ffeettcchhLLiisstt, ffeettcchhXXGGeettFFiillee, ffeettcchhGGeettFFiillee, + ffeettcchhPPuuttFFiillee, ffeettcchhSSttaattFFiillee, ffeettcchhLLiissttFFiillee, ffeettcchhXXGGeettHHTTTTPP, ffeettcchhGGeettHHTTTTPP, + ffeettcchhPPuuttHHTTTTPP, ffeettcchhSSttaattHHTTTTPP, ffeettcchhLLiissttHHTTTTPP, ffeettcchhXXGGeettFFTTPP, ffeettcchhGGeettFFTTPP, + ffeettcchhPPuuttFFTTPP, ffeettcchhSSttaattFFTTPP, ffeettcchhLLiissttFFTTPP ffeettcchhIInniittUURRLLLLiisstt, + ffeettcchhFFrreeeeUURRLLLLiisstt, ffeettcchhUUnnqquuootteePPaatthh, ffeettcchhUUnnqquuootteeFFiilleennaammee, + ffeettcchhSSttrriinnggiiffyyUURRLL, ffeettcchh -- file transfer functions +LLIIBBRRAARRYY + File Transfer Library for URLs (libfetch, -lfetch) +SSYYNNOOPPSSIISS + ##iinncclluuddee <<ssttddiioo..hh>> + ##iinncclluuddee <<ffeettcchh..hh>> + _s_t_r_u_c_t _u_r_l _* + ffeettcchhMMaakkeeUURRLL(_c_o_n_s_t _c_h_a_r _*_s_c_h_e_m_e, _c_o_n_s_t _c_h_a_r _*_h_o_s_t, _i_n_t _p_o_r_t, + _c_o_n_s_t _c_h_a_r _*_d_o_c, _c_o_n_s_t _c_h_a_r _*_u_s_e_r, _c_o_n_s_t _c_h_a_r _*_p_w_d); + _s_t_r_u_c_t _u_r_l _* + ffeettcchhPPaarrsseeUURRLL(_c_o_n_s_t _c_h_a_r _*_U_R_L); + _s_t_r_u_c_t _u_r_l _* + ffeettcchhCCooppyyUURRLL(_c_o_n_s_t _s_t_r_u_c_t _u_r_l _*_u); + _v_o_i_d + ffeettcchhFFrreeeeUURRLL(_s_t_r_u_c_t _u_r_l _*_u); + _f_e_t_c_h_I_O _* + ffeettcchhXXGGeettUURRLL(_c_o_n_s_t _c_h_a_r _*_U_R_L, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _f_e_t_c_h_I_O _* + ffeettcchhGGeettUURRLL(_c_o_n_s_t _c_h_a_r _*_U_R_L, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _f_e_t_c_h_I_O _* + ffeettcchhPPuuttUURRLL(_c_o_n_s_t _c_h_a_r _*_U_R_L, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _i_n_t + ffeettcchhSSttaattUURRLL(_c_o_n_s_t _c_h_a_r _*_U_R_L, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _i_n_t + ffeettcchhLLiissttUURRLL(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_l_i_s_t, _c_o_n_s_t _c_h_a_r _*_U_R_L, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _f_e_t_c_h_I_O _* + ffeettcchhXXGGeett(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _f_e_t_c_h_I_O _* + ffeettcchhGGeett(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _f_e_t_c_h_I_O _* + ffeettcchhPPuutt(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _i_n_t + ffeettcchhSSttaatt(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _i_n_t + ffeettcchhLLiisstt(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_l_i_s_t, _s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _f_e_t_c_h_I_O _* + ffeettcchhXXGGeettFFiillee(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _f_e_t_c_h_I_O _* + ffeettcchhGGeettFFiillee(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _f_e_t_c_h_I_O _* + ffeettcchhPPuuttFFiillee(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _i_n_t + ffeettcchhSSttaattFFiillee(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + _i_n_t + ffeettcchhLLiissttFFiillee(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_l_i_s_t, _s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + + _f_e_t_c_h_I_O _* + ffeettcchhXXGGeettHHTTTTPP(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + + _f_e_t_c_h_I_O _* + ffeettcchhGGeettHHTTTTPP(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + + _f_e_t_c_h_I_O _* + ffeettcchhPPuuttHHTTTTPP(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + + _i_n_t + ffeettcchhSSttaattHHTTTTPP(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + + _i_n_t + ffeettcchhLLiissttHHTTTTPP(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_l_i_s_t, _s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + + _f_e_t_c_h_I_O _* + ffeettcchhXXGGeettFFTTPP(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + + _f_e_t_c_h_I_O _* + ffeettcchhGGeettFFTTPP(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + + _f_e_t_c_h_I_O _* + ffeettcchhPPuuttFFTTPP(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + + _i_n_t + ffeettcchhSSttaattFFTTPP(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + + _i_n_t + ffeettcchhLLiissttFFTTPP(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_l_i_s_t, _s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s); + + _v_o_i_d + ffeettcchhIInniittUURRLLLLiisstt(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_u_l); + + _v_o_i_d + ffeettcchhFFrreeeeUURRLLLLiisstt(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_u_l); + + _c_h_a_r _* + ffeettcchhUUnnqquuootteePPaatthh(_s_t_r_u_c_t _u_r_l _*_u); + + _c_h_a_r _* + ffeettcchhUUnnqquuootteeFFiilleennaammee(_s_t_r_u_c_t _u_r_l _*_u); + + _c_h_a_r _* + ffeettcchhSSttrriinnggiiffyyUURRLL(_c_o_n_s_t _s_t_r_u_c_t _u_r_l _*_u); + +DDEESSCCRRIIPPTTIIOONN + These functions implement a high-level library for retrieving and upload- + ing files using Uniform Resource Locators (URLs). + + ffeettcchhPPaarrsseeUURRLL() takes a URL in the form of a null-terminated string and + splits it into its components function according to the Common Internet + Scheme Syntax detailed in RFC 1738. A regular expression which produces + this syntax is: + + <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)? + + If the URL does not seem to begin with a scheme name, it is assumed to be + a local path. Only absolute path names are accepted. + + Note that some components of the URL are not necessarily relevant to all + URL schemes. For instance, the file scheme only needs the <scheme> and + <document> components. ffeettcchhPPaarrsseeUURRLL() quotes any unsafe character in + the URL automatically. This is not done by ffeettcchhMMaakkeeUURRLL(). + ffeettcchhCCooppyyUURRLL() copies an existing _u_r_l structure. + + ffeettcchhMMaakkeeUURRLL(), ffeettcchhPPaarrsseeUURRLL(), and ffeettcchhCCooppyyUURRLL() return a pointer to a + _u_r_l structure, which is defined as follows in <_f_e_t_c_h_._h>: + + #define URL_SCHEMELEN 16 + #define URL_USERLEN 256 + #define URL_PWDLEN 256 + #define URL_HOSTLEN 255 + + struct url { + char scheme[URL_SCHEMELEN + 1]; + char user[URL_USERLEN + 1]; + char pwd[URL_PWDLEN + 1]; + char host[URL_HOSTLEN + 1]; + int port; + char *doc; + off_t offset; + size_t length; + time_t last_modified; + }; + + The pointer returned by ffeettcchhMMaakkeeUURRLL(), ffeettcchhCCooppyyUURRLL(), and + ffeettcchhPPaarrsseeUURRLL() should be freed using ffeettcchhFFrreeeeUURRLL(). The size of _s_t_r_u_c_t + _U_R_L is not part of the ABI. + + ffeettcchhXXGGeettUURRLL(), ffeettcchhGGeettUURRLL(), and ffeettcchhPPuuttUURRLL() constitute the recom- + mended interface to the ffeettcchh library. They examine the URL passed to + them to determine the transfer method, and call the appropriate lower- + level functions to perform the actual transfer. ffeettcchhXXGGeettUURRLL() also + returns the remote document's metadata in the _u_r_l___s_t_a_t structure pointed + to by the _u_s argument. + + The _f_l_a_g_s argument is a string of characters which specify transfer + options. The meaning of the individual flags is scheme-dependent, and is + detailed in the appropriate section below. + + ffeettcchhSSttaattUURRLL() attempts to obtain the requested document's metadata and + fill in the structure pointed to by its second argument. The _u_r_l___s_t_a_t + structure is defined as follows in <_f_e_t_c_h_._h>: + + struct url_stat { + off_t size; + time_t atime; + time_t mtime; + }; + + If the size could not be obtained from the server, the _s_i_z_e field is set + to -1. If the modification time could not be obtained from the server, + the _m_t_i_m_e field is set to the epoch. If the access time could not be + obtained from the server, the _a_t_i_m_e field is set to the modification + time. + + ffeettcchhLLiissttUURRLL() attempts to list the contents of the directory pointed to + by the URL provided. The pattern can be a simple glob-like expression as + hint. Callers should not depend on the server to filter names. If suc- + cessful, it appends the list of entries to the _u_r_l___l_i_s_t structure. The + _u_r_l___l_i_s_t structure is defined as follows in <_f_e_t_c_h_._h>: + + struct url_list { + size_t length; + size_t alloc_size; + struct url *urls; + }; + + The list should be initialized by calling ffeettcchhIInniittUURRLLLLiisstt() and the + entries be freed by calling ffeettcchhFFrreeeeUURRLLLLiisstt(). + + ffeettcchhSSttrriinnggiiffyyUURRLL() returns the URL as string. ffeettcchhUUnnqquuootteePPaatthh() + returns the path name part of the URL with any quoting undone. Query + arguments and fragment identifiers are not included. + ffeettcchhUUnnqquuootteeFFiilleennaammee() returns the last component of the path name as + returned by ffeettcchhUUnnqquuootteePPaatthh(). ffeettcchhSSttrriinnggiiffyyUURRLL(), ffeettcchhUUnnqquuootteePPaatthh(), + and ffeettcchhUUnnqquuootteeFFiilleennaammee() return a string that should be deallocated + with ffrreeee() after use. + + ffeettcchhXXGGeett(), ffeettcchhGGeett(), ffeettcchhPPuutt(), and ffeettcchhSSttaatt() are similar to + ffeettcchhXXGGeettUURRLL(), ffeettcchhGGeettUURRLL(), ffeettcchhPPuuttUURRLL(), and ffeettcchhSSttaattUURRLL(), except + that they expect a pre-parsed URL in the form of a pointer to a _s_t_r_u_c_t + _u_r_l rather than a string. + + All of the ffeettcchhXXGGeettXXXXXX(), ffeettcchhGGeettXXXXXX(), and ffeettcchhPPuuttXXXXXX() functions + return a pointer to a stream which can be used to read or write data from + or to the requested document, respectively. Note that although the + implementation details of the individual access methods vary, it can gen- + erally be assumed that a stream returned by one of the ffeettcchhXXGGeettXXXXXX() or + ffeettcchhGGeettXXXXXX() functions is read-only, and that a stream returned by one + of the ffeettcchhPPuuttXXXXXX() functions is write-only. + +PPRROOTTOOCCOOLL IINNDDEEPPEENNDDEENNTT FFLLAAGGSS + If the `i' (if-modified-since) flag is specified, the library will try to + fetch the content only if it is newer than _l_a_s_t___m_o_d_i_f_i_e_d. For HTTP an + If-Modified-Since HTTP header is sent. For FTP a MTDM command is sent + first and compared locally. For FILE the source file is compared. + +FFIILLEE SSCCHHEEMMEE + ffeettcchhXXGGeettFFiillee(), ffeettcchhGGeettFFiillee(), and ffeettcchhPPuuttFFiillee() provide access to + documents which are files in a locally mounted file system. Only the + <document> component of the URL is used. + + ffeettcchhXXGGeettFFiillee() and ffeettcchhGGeettFFiillee() do not accept any flags. + + ffeettcchhPPuuttFFiillee() accepts the `a' (append to file) flag. If that flag is + specified, the data written to the stream returned by ffeettcchhPPuuttFFiillee() will + be appended to the previous contents of the file, instead of replacing + them. + +FFTTPP SSCCHHEEMMEE + ffeettcchhXXGGeettFFTTPP(), ffeettcchhGGeettFFTTPP(), and ffeettcchhPPuuttFFTTPP() implement the FTP proto- + col as described in RFC 959. + + By default lliibbffeettcchh will attempt to use passive mode first and only fall- + back to active mode if the server reports a syntax error. If the `a' + (active) flag is specified, a passive connection is not tried and active + mode is used directly. + + If the `l' (low) flag is specified, data sockets will be allocated in the + low (or default) port range instead of the high port range (see ip(4)). + + If the `d' (direct) flag is specified, ffeettcchhXXGGeettFFTTPP(), ffeettcchhGGeettFFTTPP(), and + ffeettcchhPPuuttFFTTPP() will use a direct connection even if a proxy server is + defined. + + If no user name or password is given, the ffeettcchh library will attempt an + anonymous login, with user name "anonymous" and password "anony- + mous@<hostname>". + +HHTTTTPP SSCCHHEEMMEE + The ffeettcchhXXGGeettHHTTTTPP(), ffeettcchhGGeettHHTTTTPP(), and ffeettcchhPPuuttHHTTTTPP() functions imple- + ment the HTTP/1.1 protocol. With a little luck, there is even a chance + that they comply with RFC 2616 and RFC 2617. + + If the `d' (direct) flag is specified, ffeettcchhXXGGeettHHTTTTPP(), ffeettcchhGGeettHHTTTTPP(), + and ffeettcchhPPuuttHHTTTTPP() will use a direct connection even if a proxy server is + defined. + + Since there seems to be no good way of implementing the HTTP PUT method + in a manner consistent with the rest of the ffeettcchh library, ffeettcchhPPuuttHHTTTTPP() + is currently unimplemented. + +AAUUTTHHEENNTTIICCAATTIIOONN + Apart from setting the appropriate environment variables and specifying + the user name and password in the URL or the _s_t_r_u_c_t _u_r_l, the calling pro- + gram has the option of defining an authentication function with the fol- + lowing prototype: + + _i_n_t mmyyAAuutthhMMeetthhoodd(_s_t_r_u_c_t _u_r_l _*_u) + + The callback function should fill in the _u_s_e_r and _p_w_d fields in the pro- + vided _s_t_r_u_c_t _u_r_l and return 0 on success, or any other value to indicate + failure. + + To register the authentication callback, simply set _f_e_t_c_h_A_u_t_h_M_e_t_h_o_d to + point at it. The callback will be used whenever a site requires authen- + tication and the appropriate environment variables are not set. + + This interface is experimental and may be subject to change. + +RREETTUURRNN VVAALLUUEESS + ffeettcchhPPaarrsseeUURRLL() returns a pointer to a _s_t_r_u_c_t _u_r_l containing the individ- + ual components of the URL. If it is unable to allocate memory, or the + URL is syntactically incorrect, ffeettcchhPPaarrsseeUURRLL() returns a NULL pointer. + + The ffeettcchhSSttaatt() functions return 0 on success and -1 on failure. + + All other functions return a stream pointer which may be used to access + the requested document, or NULL if an error occurred. + + The following error codes are defined in <_f_e_t_c_h_._h>: + + [FETCH_ABORT] Operation aborted + + [FETCH_AUTH] Authentication failed + + [FETCH_DOWN] Service unavailable + + [FETCH_EXISTS] File exists + + [FETCH_FULL] File system full + + [FETCH_INFO] Informational response + + [FETCH_MEMORY] Insufficient memory + + [FETCH_MOVED] File has moved + + [FETCH_NETWORK] Network error + + [FETCH_OK] No error + + [FETCH_PROTO] Protocol error + + [FETCH_RESOLV] Resolver error + + [FETCH_SERVER] Server error + + [FETCH_TEMP] Temporary error + + [FETCH_TIMEOUT] Operation timed out + + [FETCH_UNAVAIL] File is not available + + [FETCH_UNKNOWN] Unknown error + + [FETCH_URL] Invalid URL + + The accompanying error message includes a protocol-specific error code + and message, e.g. "File is not available (404 Not Found)" + +EENNVVIIRROONNMMEENNTT + FETCH_BIND_ADDRESS Specifies a host name or IP address to which sockets + used for outgoing connections will be bound. + + FTP_LOGIN Default FTP login if none was provided in the URL. + + FTP_PASSIVE_MODE If set to anything but `no', forces the FTP code to + use passive mode. + + FTP_PASSWORD Default FTP password if the remote server requests + one and none was provided in the URL. + + FTP_PROXY URL of the proxy to use for FTP requests. The docu- + ment part is ignored. FTP and HTTP proxies are sup- + ported; if no scheme is specified, FTP is assumed. + If the proxy is an FTP proxy, lliibbffeettcchh will send + `user@host' as user name to the proxy, where `user' + is the real user name, and `host' is the name of the + FTP server. + + If this variable is set to an empty string, no proxy + will be used for FTP requests, even if the HTTP_PROXY + variable is set. + + ftp_proxy Same as FTP_PROXY, for compatibility. + + HTTP_AUTH Specifies HTTP authorization parameters as a colon- + separated list of items. The first and second item + are the authorization scheme and realm respectively; + further items are scheme-dependent. Currently, only + basic authorization is supported. + + Basic authorization requires two parameters: the user + name and password, in that order. + + This variable is only used if the server requires + authorization and no user name or password was speci- + fied in the URL. + + HTTP_PROXY URL of the proxy to use for HTTP requests. The docu- + ment part is ignored. Only HTTP proxies are sup- + ported for HTTP requests. If no port number is spec- + ified, the default is 3128. + + Note that this proxy will also be used for FTP docu- + ments, unless the FTP_PROXY variable is set. + + http_proxy Same as HTTP_PROXY, for compatibility. + + HTTP_PROXY_AUTH Specifies authorization parameters for the HTTP proxy + in the same format as the HTTP_AUTH variable. + + This variable is used if and only if connected to an + HTTP proxy, and is ignored if a user and/or a pass- + word were specified in the proxy URL. + + HTTP_REFERER Specifies the referrer URL to use for HTTP requests. + If set to ``auto'', the document URL will be used as + referrer URL. + + HTTP_USER_AGENT Specifies the User-Agent string to use for HTTP + requests. This can be useful when working with HTTP + origin or proxy servers that differentiate between + user agents. + + NETRC Specifies a file to use instead of _~_/_._n_e_t_r_c to look + up login names and passwords for FTP sites. See + ftp(1) for a description of the file format. This + feature is experimental. + + NO_PROXY Either a single asterisk, which disables the use of + proxies altogether, or a comma- or whitespace-sepa- + rated list of hosts for which proxies should not be + used. + + no_proxy Same as NO_PROXY, for compatibility. + +EEXXAAMMPPLLEESS + To access a proxy server on _p_r_o_x_y_._e_x_a_m_p_l_e_._c_o_m port 8080, set the + HTTP_PROXY environment variable in a manner similar to this: + + HTTP_PROXY=http://proxy.example.com:8080 + + If the proxy server requires authentication, there are two options avail- + able for passing the authentication data. The first method is by using + the proxy URL: + + HTTP_PROXY=http://<user>:<pwd>@proxy.example.com:8080 + + The second method is by using the HTTP_PROXY_AUTH environment variable: + + HTTP_PROXY=http://proxy.example.com:8080 + HTTP_PROXY_AUTH=basic:*:<user>:<pwd> + + To disable the use of a proxy for an HTTP server running on the local + host, define NO_PROXY as follows: + + NO_PROXY=localhost,127.0.0.1 + +SSEEEE AALLSSOO + ftp(1), ip(4) + + J. Postel and J. K. Reynolds, _F_i_l_e _T_r_a_n_s_f_e_r _P_r_o_t_o_c_o_l, October 1985, RFC + 959. + + P. Deutsch, A. Emtage, and A. Marine, _H_o_w _t_o _U_s_e _A_n_o_n_y_m_o_u_s _F_T_P, May 1994, + RFC 1635. + + T. Berners-Lee, L. Masinter, and M. McCahill, _U_n_i_f_o_r_m _R_e_s_o_u_r_c_e _L_o_c_a_t_o_r_s + _(_U_R_L_), December 1994, RFC 1738. + + R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, and + T. Berners-Lee, _H_y_p_e_r_t_e_x_t _T_r_a_n_s_f_e_r _P_r_o_t_o_c_o_l _-_- _H_T_T_P_/_1_._1, January 1999, + RFC 2616. + + J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. + Luotonen, and L. Stewart, _H_T_T_P _A_u_t_h_e_n_t_i_c_a_t_i_o_n_: _B_a_s_i_c _a_n_d _D_i_g_e_s_t _A_c_c_e_s_s + _A_u_t_h_e_n_t_i_c_a_t_i_o_n, June 1999, RFC 2617. + +HHIISSTTOORRYY + The ffeettcchh library first appeared in FreeBSD 3.0. + +AAUUTTHHOORRSS + The ffeettcchh library was mostly written by Dag-Erling Smørgrav + <des@FreeBSD.org> with numerous suggestions from Jordan K. Hubbard + <jkh@FreeBSD.org>, Eugene Skepner <eu@qub.com> and other FreeBSD develop- + ers. It replaces the older ffttppiioo library written by Poul-Henning Kamp + <phk@FreeBSD.org> and Jordan K. Hubbard <jkh@FreeBSD.org>. + + This manual page was written by Dag-Erling Smørgrav <des@FreeBSD.org>. + +BBUUGGSS + Some parts of the library are not yet implemented. The most notable + examples of this are ffeettcchhPPuuttHHTTTTPP() and FTP proxy support. + + There is no way to select a proxy at run-time other than setting the + HTTP_PROXY or FTP_PROXY environment variables as appropriate. + + lliibbffeettcchh does not understand or obey 305 (Use Proxy) replies. + + Error numbers are unique only within a certain context; the error codes + used for FTP and HTTP overlap, as do those used for resolver and system + errors. For instance, error code 202 means "Command not implemented, + superfluous at this site" in an FTP context and "Accepted" in an HTTP + context. + + ffeettcchhSSttaattFFTTPP() does not check that the result of an MDTM command is a + valid date. + + The man page is incomplete, poorly written and produces badly formatted + text. + + The error reporting mechanism is unsatisfactory. + + Some parts of the code are not fully reentrant. + +NetBSD 5.0 February 4, 2009 NetBSD 5.0 |