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