sys/man/4/webfs

   1 .TH WEBFS 4
   2 .SH NAME
   3 webfs \- world wide web file system
   4 .SH SYNOPSIS
   5 .B webfs
   6 [
   7 .B -A
   8 .I useragent
   9 ] [
  10 .B -T
  11 .I timeout
  12 ] [
  13 .B -m
  14 .I mtpt
  15 ]
  16 [
  17 .B -s
  18 .I service
  19 ]
  20 .SH DESCRIPTION
  21 .I Webfs
  22 presents a file system interface to the parsing and retrieving
  23 of URLs.
  24 .I Webfs
  25 mounts itself at
  26 .I mtpt
  27 (default
  28 .BR /mnt/web ),
  29 and, if
  30 .I service
  31 is specified, will post a service file descriptor in
  32 .BR /srv/\fIservice .
  33 .PP
  34 If the environment variable
  35 .B httpproxy
  36 is set, all HTTP request initiated by
  37 .I webfs
  38 will be made through that proxy url.
  39 .PP
  40 .I Webfs
  41 presents a three-level file system suggestive
  42 of the network protocol hierarchies
  43 .IR ip (3)
  44 and
  45 .IR ether (3).
  46 .PP
  47 The top level contains the two files:
  48 .BR ctl ,
  49 and
  50 .BR clone .
  51 .PP
  52 The top level
  53 .B ctl
  54 file is used to maintain parameters global to the instance of
  55 .IR webfs .
  56 Reading the
  57 .B ctl
  58 file yields the current values of the parameters.
  59 Writing strings of the form
  60 .RB `` attr " " value ''
  61 sets a particular attribute.
  62 .PP
  63 The following global parameters can be set:
  64 .TP
  65 .B useragent
  66 Sets the HTTP user agent string.
  67 .TP
  68 .B timeout
  69 Sets the request timeout in seconds.
  70 .TP
  71 .BI flushauth " url"
  72 Flushes any associated authentication information for
  73 resources under
  74 .I url
  75 or all resources if no url was given.
  76 .TP
  77 .BI preauth " url realm"
  78 Preauthenticates all resources under
  79 .I url
  80 with the given
  81 .I realm
  82 using HTTP Basic authentication. This will cause
  83 .I webfs
  84 to preemptively send the resulting authorization information
  85 not waiting for the server to respond with an
  86 HTTP 401 Unauthorized status.
  87 .PP
  88 The top-level directory also contains
  89 numbered directories corresponding to connections, which
  90 may be used to fetch a single URL.
  91 To allocate a connection, open the
  92 .B clone
  93 file and read a number
  94 .I n
  95 from it.
  96 After opening, the
  97 .B clone
  98 file is equivalent to the file
  99 .IB n /ctl \fR.
 100 A connection is assumed closed once all files in its
 101 directory have been closed, and is then will be reallocated.
 102 .PP
 103 Each connection has a URL attribute
 104 .B url
 105 associated with it.
 106 This URL may be an absolute URL such as
 107 .I http://www.lucent.com/index.html
 108 or a relative URL such as
 109 .IR ../index.html .
 110 The
 111 .B baseurl
 112 attribute sets the URL against which relative URLs
 113 are interpreted.
 114 Once the URL has been set by writing to the
 115 .B ctl
 116 file of the connection, its pieces can be retrieved via
 117 individual files in the
 118 .B parsed
 119 directory:
 120 .de UU
 121 .TP
 122 .B parsed/\fI\\$1
 123 \\$2
 124 ..
 125 .UU url http://pete:secret@www.example.com:8000/cgi/search?q=kittens#results
 126 .UU scheme http
 127 .UU user pete
 128 .UU pass secret
 129 .UU host www.example.com
 130 .UU port 8000
 131 .UU path /cgi/search
 132 .UU query q=kittens
 133 .UU fragment results
 134 .PP
 135 If there is associated data to be posted with the request,
 136 it can be written to
 137 .BR postbody .
 138 Opening
 139 .B postbody
 140 or
 141 .B body
 142 initiates the request. If the request fails,
 143 then opening the
 144 .B body
 145 or writing to
 146 .B postbody
 147 file will fail and return a error string.
 148 .PP
 149 When the
 150 .B body
 151 file has been opened, response headers appear
 152 as files in the connection directory. For example
 153 reading the
 154 .B contenttype
 155 file yields the MIME content type of the body data.
 156 If the request was redirected, the URL represented
 157 by the
 158 .B parsed
 159 directory will change to the final destination.
 160 .PP
 161 The resulting data may be read from
 162 .B body
 163 as it arrives.
 164 .PP
 165 The following is a list of attributes that can be
 166 set to do a connection prior initiating the request:
 167 .TP
 168 .B url,baseurl
 169 See above.
 170 .TP
 171 .B useragent
 172 Sets a custom useragent string to be used with the request.
 173 .TP
 174 .B contenttype
 175 Sets the MIME content type of the postbody.
 176 .TP
 177 .B request
 178 Usually, the HTTP method used is
 179 .B POST
 180 when
 181 .B postbody
 182 file is opend first or
 183 .B GET
 184 otherwise. This can be overridden with the
 185 .B request
 186 attribute so send arbitrary HTTP requests.
 187 .TP
 188 .B headers
 189 Adds arbitrary HTTP headers to be send with
 190 the request.
 191 .SH EXAMPLE
 192 .B /rc/bin/hget
 193 is a simple client.
 194 .SH SOURCE
 195 .B /sys/src/cmd/webfs
 196 .SH "SEE ALSO"
 197 .IR webcookies (4),
 198 .IR hget (1)
 199 .SH DIAGNOSTICS
 200 For cookies to work,
 201 .IR webcookies (4),
 202 should be running and mounted on
 203 .B /mnt/webcookies
 204 otherwise cookies will be ignored.
 205 .SH HISTORY
 206 .I Webfs
 207 first appeared in Plan 9 from Bell Labs. It was
 208 rewritten from scratch for 9front (January, 2012).