lib/libfetch/fetch.3

   1 .\" Copyright (c) 1998 Dag-Erling Coïdan Smørgrav
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd July 1, 1998
  28 .Dt FETCH 3
  29 .Os
  30 .Sh NAME
  31 .Nm fetchParseURL ,
  32 .Nm fetchFreeURL ,
  33 .Nm fetchGetURL ,
  34 .Nm fetchPutURL ,
  35 .Nm fetchStatURL ,
  36 .Nm fetchListURL ,
  37 .Nm fetchGet ,
  38 .Nm fetchPut ,
  39 .Nm fetchStat ,
  40 .Nm fetchList ,
  41 .Nm fetchGetFile ,
  42 .Nm fetchPutFile ,
  43 .Nm fetchStatFile ,
  44 .Nm fetchListFile ,
  45 .Nm fetchGetHTTP ,
  46 .Nm fetchPutHTTP ,
  47 .Nm fetchStatHTTP ,
  48 .Nm fetchListHTTP ,
  49 .Nm fetchGetFTP ,
  50 .Nm fetchPutFTP ,
  51 .Nm fetchStatFTP ,
  52 .Nm fetchListFTP
  53 .Nd file transfer functions
  54 .Sh LIBRARY
  55 .Lb libfetch
  56 .Sh SYNOPSIS
  57 .Fd #include <sys/param.h>
  58 .Fd #include <stdio.h>
  59 .Fd #include <fetch.h>
  60 .Ft struct url *
  61 .Fn fetchParseURL "char *URL"
  62 .Ft void
  63 .Fn fetchFreeURL "struct url *URL"
  64 .Ft FILE *
  65 .Fn fetchGetURL "char *URL" "char *flags"
  66 .Ft FILE *
  67 .Fn fetchPutURL "char *URL" "char *flags"
  68 .Ft int
  69 .Fn fetchStatURL "char *URL" "struct url_stat *us" "char *flags"
  70 .Ft struct url_ent *
  71 .Fn fetchListURL "char *URL" "char *flags"
  72 .Ft FILE *
  73 .Fn fetchGet "struct url *URL" "char *flags"
  74 .Ft FILE *
  75 .Fn fetchPut "struct url *URL" "char *flags"
  76 .Ft int
  77 .Fn fetchStat "struct url *URL" "struct url_stat *us" "char *flags"
  78 .Ft struct url_ent *
  79 .Fn fetchList "struct url *" "char *flags"
  80 .Ft FILE *
  81 .Fn fetchGetFile "struct url *u" "char *flags"
  82 .Ft FILE *
  83 .Fn fetchPutFile "struct url *u" "char *flags"
  84 .Ft int
  85 .Fn fetchStatFile "struct url *URL" "struct url_stat *us" "char *flags"
  86 .Ft struct url_ent *
  87 .Fn fetchListFile "struct url *" "char *flags"
  88 .Ft FILE *
  89 .Fn fetchGetHTTP "struct url *u" "char *flags"
  90 .Ft FILE *
  91 .Fn fetchPutHTTP "struct url *u" "char *flags"
  92 .Ft int
  93 .Fn fetchStatHTTP "struct url *URL" "struct url_stat *us" "char *flags"
  94 .Ft struct url_ent *
  95 .Fn fetchListHTTP "struct url *" "char *flags"
  96 .Ft FILE *
  97 .Fn fetchGetFTP "struct url *u" "char *flags"
  98 .Ft FILE *
  99 .Fn fetchPutFTP "struct url *u" "char *flags"
 100 .Ft int
 101 .Fn fetchStatFTP "struct url *URL" "struct url_stat *us" "char *flags"
 102 .Ft struct url_ent *
 103 .Fn fetchListFTP "struct url *" "char *flags"
 104 .Sh DESCRIPTION
 105 .Pp
 106 These functions implement a high-level library for retrieving and
 107 uploading files using Uniform Resource Locators (URLs).
 108 .Pp
 109 .Fn fetchParseURL
 110 takes a URL in the form of a null-terminated string and splits it into
 111 its components function according to the Common Internet Scheme Syntax
 112 detailed in RFC1738.
 113 A regular expression which produces this syntax is:
 114 .Bd -literal
 115     <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?
 116 .Ed
 117 .Pp
 118 Note that some components of the URL are not necessarily relevant to
 119 all URL schemes.
 120 For instance, the file scheme only needs the <scheme>
 121 and <document> components.
 122 .Pp
 123 The pointer returned by
 124 .Fn fetchParseURL
 125 should be freed using
 126 .Fn fetchFreeURL .
 127 .Pp
 128 .Fn fetchGetURL
 129 and
 130 .Fn fetchPutURL
 131 constitute the recommended interface to the
 132 .Nm fetch
 133 library.
 134 They examine the URL passed to them to determine the transfer
 135 method, and call the appropriate lower-level functions to perform the
 136 actual transfer.
 137 The
 138 .Fa flags
 139 argument is a string of characters which specify transfer options.
 140 The
 141 meaning of the individual flags is scheme-dependent, and is detailed
 142 in the appropriate section below.
 143 .Pp
 144 .Fn fetchStatURL
 145 attempts to obtain the requested document's metadata and fill in the
 146 structure pointed to by it's second argument.
 147 The
 148 .Fa url_stat
 149 structure is defined as follows in
 150 .Aq Pa fetch.h :
 151 .Bd -literal
 152 struct url_stat {
 153     off_t        size;
 154     time_t       atime;
 155     time_t       mtime;
 156 };
 157 .Ed
 158 .Pp
 159 .Fn fetchListURL
 160 attempts to list the contents of the directory pointed to by the URL
 161 provided.
 162 If successful, it returns a malloced array of
 163 .Fa url_ent
 164 structures.
 165 The
 166 .Fa url_ent
 167 structure is defined as follows in
 168 .Aq Pa fetch.h :
 169 .Bd -literal
 170 struct url_ent {
 171     char         name[MAXPATHLEN];
 172     struct url_stat stat;
 173 };
 174 .Ed
 175 .Pp
 176 The list is terminated by an entry with an empty name.
 177 .Pp
 178 The pointer returned by
 179 .Fn fetchListURL
 180 should be freed using
 181 .Fn free .
 182 .Pp
 183 .Fn fetchGet ,
 184 .Fn fetchPut
 185 and
 186 .Fn fetchStat
 187 are similar to
 188 .Fn fetchGetURL ,
 189 .Fn fetchPutURL
 190 and
 191 .Fn fetchStatURL ,
 192 except that they expect a pre-parsed URL in the form of a pointer to
 193 a
 194 .Fa struct url
 195 rather than a string.
 196 .Pp
 197 All of the
 198 .Fn fetchGetXXX
 199 and
 200 .Fn fetchPutXXX
 201 functions return a pointer to a stream which can be used to read or
 202 write data from or to the requested document, respectively.
 203 Note that
 204 although the implementation details of the individual access methods
 205 vary, it can generally be assumed that a stream returned by one of the
 206 .Fn fetchGetXXX
 207 functions is read-only, and that a stream returned by one of the
 208 .Fn fetchPutXXX
 209 functions is write-only.
 210 .Sh FILE SCHEME
 211 .Fn fetchGetFile
 212 and
 213 .Fn fetchPutFile
 214 provide access to documents which are files in a locally mounted file
 215 system.
 216 Only the <document> component of the URL is used.
 217 .Pp
 218 .Fn fetchGetFile
 219 does not accept any flags.
 220 .Pp
 221 .Fn fetchPutFile
 222 accepts the
 223 .Fa a
 224 (append to file) flag.
 225 If that flag is specified, the data written to
 226 the stream returned by
 227 .Fn fetchPutFile
 228 will be appended to the previous contents of the file, instead of
 229 replacing them.
 230 .Sh FTP SCHEME
 231 .Fn fetchGetFTP
 232 and
 233 .Fn fetchPutFTP
 234 implement the FTP protocol as described in RFC959.
 235 .Pp
 236 If the
 237 .Fa p
 238 (passive) flag is specified, a passive (rather than active) connection
 239 will be attempted.
 240 .Pp
 241 If the
 242 .Fa h
 243 (high) flag is specified, data sockets will be allocated in the high
 244 port range (see
 245 .Xr ip 4 ).
 246 .Pp
 247 If the
 248 .Fa d
 249 (direct) flag is specified,
 250 .Fn fetchGetFTP
 251 and
 252 .Fn fetchPutFTP
 253 will use a direct connection even if a proxy server is defined.
 254 .Pp
 255 If no user name or password is given, the
 256 .Nm fetch
 257 library will attempt an anonymous login, with user name "ftp" and
 258 password "ftp".
 259 .Sh HTTP SCHEME
 260 The
 261 .Fn fetchGetHTTP
 262 and
 263 .Fn fetchPutHTTP
 264 functions implement the HTTP/1.1 protocol.
 265 With a little luck, there's
 266 even a chance that they comply with RFC2068.
 267 .Pp
 268 If the
 269 .Fa d
 270 (direct) flag is specified,
 271 .Fn fetchGetHTTP
 272 and
 273 .Fn fetchPutHTTP
 274 will use a direct connection even if a proxy server is defined.
 275 .Pp
 276 Since there seems to be no good way of implementing the HTTP PUT
 277 method in a manner consistent with the rest of the
 278 .Nm fetch
 279 library,
 280 .Fn fetchPutHTTP
 281 is currently unimplemented.
 282 .Sh RETURN VALUES
 283 .Fn fetchParseURL
 284 returns a pointer to a
 285 .Fa struct url
 286 containing the individual components of the URL.
 287 If it is
 288 unable to allocate memory, or the URL is syntactically incorrect,
 289 .Fn fetchParseURL
 290 returns a NULL pointer.
 291 .Pp
 292 The
 293 .Fn fetchStat
 294 functions return 0 on success and -1 on failure.
 295 .Pp
 296 All other functions return a stream pointer which may be used to
 297 access the requested document, or NULL if an error occurred.
 298 .Pp
 299 .Nm Libfetch
 300 uses the Common Error Library
 301 .Nm ( libcom_err )
 302 to report errors.
 303 The error code passed to
 304 .Fn com_err
 305 is one of:
 306 .Bl -tag -width 18n
 307 .It Bq Er FETCH_ABORT
 308 Operation aborted
 309 .It Bq Er FETCH_AUTH
 310 Authentication failed
 311 .It Bq Er FETCH_DOWN
 312 Service unavailable
 313 .It Bq Er FETCH_EXISTS
 314 File exists
 315 .It Bq Er FETCH_FULL
 316 File system full
 317 .It Bq Er FETCH_INFO
 318 Informational response
 319 .It Bq Er FETCH_MEMORY
 320 Insufficient memory
 321 .It Bq Er FETCH_MOVED
 322 File has moved
 323 .It Bq Er FETCH_NETWORK
 324 Network error
 325 .It Bq Er FETCH_OK
 326 No error
 327 .It Bq Er FETCH_PROTO
 328 Protocol error
 329 .It Bq Er FETCH_RESOLV
 330 Resolver error
 331 .It Bq Er FETCH_SERVER
 332 Server error
 333 .It Bq Er FETCH_TEMP
 334 Temporary error
 335 .It Bq Er FETCH_TIMEOUT
 336 Operation timed out
 337 .It Bq Er FETCH_UNAVAIL
 338 File is not available
 339 .It Bq Er FETCH_UNKNOWN
 340 Unknown error
 341 .It Bq Er FETCH_URL
 342 Invalid URL
 343 .El
 344 .Pp
 345 The accompanying error message includes a protocol-specific error code
 346 and message, e.g. "File is not available (404 Not Found)"
 347 .Sh ENVIRONMENT
 348 The FTP and HTTP related functions use the
 349 .Ev HTTP_PROXY
 350 and
 351 .Ev FTP_PROXY
 352 environment variables, respectively, as the address of a proxy server
 353 to use for transferring files.
 354 .Sh SEE ALSO
 355 .Xr com_err 3 ,
 356 .Xr fetch 1 ,
 357 .Xr ftpio 3 ,
 358 .Xr ip 4 .
 359 .Rs
 360 .%A T. Berners-Lee
 361 .%A L. Masinter
 362 .%A M. McCahill
 363 .%D December 1994
 364 .%T Uniform Resource Locators (URL)
 365 .%O RFC1738
 366 .Re
 367 .Rs
 368 .%A R. Fielding
 369 .%A J. Gettys
 370 .%A J. Mogul
 371 .%A H. Frystyk
 372 .%A T. Berners-Lee
 373 .%D Januray 1997
 374 .%B Hypertext Transfer Protocol -- HTTP/1.1
 375 .%O RFC2068
 376 .Re
 377 .Rs
 378 .%A J. Postel
 379 .%A J. K. Reynolds
 380 .%D October 1985
 381 .%B File Transfer Protocol
 382 .%O RFC959
 383 .Re
 384 .Sh NOTES
 385 The
 386 .Nm fetch
 387 library uses the Common Error library, and applications which link
 388 with
 389 .Nm libfetch
 390 must therefore also link with
 391 .Nm libcom_err .
 392 .Sh HISTORY
 393 The
 394 .Nm fetch
 395 library first appeared in
 396 .Fx 3.0 .
 397 .Sh AUTHORS
 398 The
 399 .Nm fetch
 400 library was mostly written by
 401 .An Dag-Erling Coïdan Smørgrav Aq des@FreeBSD.org
 402 with numerous suggestions from
 403 .An Jordan K. Hubbard Aq jkh@FreeBSD.org ,
 404 .An Eugene Skepner Aq eu@qub.com
 405 and other FreeBSD developers.
 406 It replaces the older
 407 .Nm ftpio
 408 library written by
 409 .An Poul-Henning Kamp Aq pkh@FreeBSD.org
 410 and
 411 .An Jordan K. Hubbard Aq jkh@FreeBSD.org .
 412 .Pp
 413 This manual page was written by
 414 .An Dag-Erling Coïdan Smørgrav Aq des@FreeBSD.org
 415 .Sh BUGS
 416 Some parts of the library are not yet implemented.
 417 The most notable
 418 examples of this are
 419 .Fn fetchPutHTTP ,
 420 .Fn fetchListHTTP ,
 421 .Fn fetchListFTP
 422 and FTP proxy support.
 423 .Pp
 424 There's no way to select a proxy at run-time other than setting the
 425 .Ev HTTP_PROXY
 426 or
 427 .Ev FTP_PROXY
 428 environment variables as appropriate.
 429 There is also no way to stop the
 430 FTP and HTTP functions from trying to use a proxy if these variables
 431 are set.
 432 .Pp
 433 HTTP authentication doesn't work.
 434 I'm not sure that's a bug in my
 435 code; as far as I can determine,
 436 .Nm libfetch
 437 handles HTTP/1.1 basic authentication correctly as outlined in
 438 RFC2068, but I haven't been able to find an HTTP server that honors
 439 the Authentication: header field.
 440 Also,
 441 .Nm libfetch
 442 does not attempt to interpret and respond to authentication requests
 443 from the HTTP server.
 444 .Pp
 445 No attempt is made to encode spaces etc. within URLs.
 446 Spaces in the
 447 document part of an URLshould be replaced with "%20" in HTTP URLs and
 448 "\\ " in FTP URLs.
 449 .Pp
 450 Error numbers are unique only within a certain context; the error
 451 codes used for FTP and HTTP overlap, as do those used for resolver and
 452 system errors.
 453 For instance, error code 202 means "Command not
 454 implemented, superfluous at this site" in an FTP context and
 455 "Accepted" in an HTTP context.
 456 .Pp
 457 .Fn fetchStatFTP
 458 does not check that the result of an MDTM command is a valid date.
 459 .Pp
 460 The HTTP code needs a complete rewrite, or at least a serious cleanup.
 461 .Pp
 462 The man page is poorly written and produces badly formatted text.
 463 .Pp
 464 Tons of other stuff.