.\" -*- nroff -*-
.\" (C) 2001 David A. Wheeler
.\"
.TH BROWSE 1 "Feburary 2001" "browse"
.SH NAME
browse \- Invoke a browser to display a reference (URI/URL or file)
.SH SYNOPSIS
.B browse
[
.B \-\-file | \-\-uri
]
[
.B \-\-base
.I b
]
[
.B \-\-magic
]
[
.B \-\-relative
]
[
.B \-\-relfile
]
[
.B \-\-nochange
]
[
.B \-\-dir
]
[
.B \-\-browser
]
.B \-\-
.I "reference"
.SH DESCRIPTION
.B browse
invokes a browser to display a reference using the
Secure BROWSER convention.
A ``reference'' is either a file or a URI/URL.
.B browse
first converts the given reference into an ``absolute reference''
if it's not already one.
An ``absolute reference'' is either
an absolute local pathname (a filename beginning with "/") or
an absolute URI/URL (which begins with lower case letters followed by a ":").
.P
After it's converted into an absolute reference, browse then
examines the
the BROWSER environment variable, which should contain
a colon-separated series of browser command parts.
These command parts are tried in order, executing
each using /bin/sh, until one succeeds (returns 0);
empty command parts (e.g., "::") are ignored.
In a command part, %% becomes a single "%", %c becomes a single ":", and
"%s" becomes the ``escaped absolute reference'' to be viewed;
a command part not having a "%s" has " %s" appended to it.
An ``escaped absolute reference'' is an absolute
reference with backslashes inserted before
each character special to the shell (to prevent certain security attacks).
.P
If defined, the value of the environment variable
BROWSER_OVER_RIDE overrides the value BROWSER, but the value of
BROWSER_OVER_RIDE is not passed on to any browsers called by browse.
This supports ``temporary overriding'' of browsers.
.P
If not told otherwise, browse will determine that a reference beginning
with "/" is a filename and anything else is a URI/URL.
Use --file or --uri to declare otherwise.
browse returns 0 (true) if a browser was successfully invoked,
and non-zero (false) if one wasn't.
This definition of ``success'' is determined by the browsers selected;
if a browser considers displaying an error message ``success,''
then browse will too.
.SH OPTIONS
.TP
.B \-\-file
 The reference is a filename
.TP
.B \-\-uri
 The reference is a URI/URL
.TP
.B \-\-url
 Synonym for \-\-uri
.TP
.B "\-\-base \fIb\fB"
 Set base (``starting point'') to b
.TP
.B \-\-magic
 If no base, 'www.' becomes 'http://www.' and 'ftp.' becomes 'ftp://ftp.'
.TP
.B \-\-relative
 If no base, don't prefix relative URL references
.TP
.B \-\-relfile
  If no base, relative URLs are prefixed with 'file://'
  (otherwise they're prefixed as "http://")
.TP
.B \-\-nochange
 Don't change the reference in any way other than shell escapes.
.TP
.B \-\-dir
 The base is a directory, not a base document.
.TP
.B \-\-browser
  Don't set BROWSER if it's not already set.
.TP
.B \-\-
  End option processing.
.SH EXAMPLES
Here are some example uses.
From a shell:
.PP
.RS
.ft CW
  /usr/bin/browse -- "/etc/passwd"
.br
  /usr/bin/browse -- "http://www.dwheeler.com"
.br
  /usr/bin/browse --uri -- "$url"
.br
  /usr/bin/browse --base \e
     "http://www.dwheeler.com/index.html" \e
     -- "dwheeler.html"
.ft
.RE
.PP
In the last example, the ``base'' document 
is used as the starting point (as though the user had clicked
on a link in that document).  In this case, the resulting document is
"http://www.dwheeler.com/dwheeler.html".
.PP
From C (note - don't use system(3)):
.PP
.RS
.ft CW
  execl("/usr/bin/browse", "browse", "--", url, (char *) 0);
.ft
.RE
.PP
From perl (note - don't use backquotes or single-parameter system()):
.PP
.RS
.ft CW
  system("/usr/bin/browse", "browse", "--", url);
.ft
.RE

.SH SECURITY
It is
.I highly
recommended that you use the -- option if you're viewing references provided
by someone else.
Otherwise, attackers may create references that
begin with ``--'' to confuse this (and other) programs.
Unless directed otherwise, browse will convert any reference to
an absolute reference (which does not begin with ``-''), so no
browser will end up with ``-'' as the first character.
.P
.I WARNING!
From a non-shell, \fIdo not\fP invoke this program through a shell -
use whatever call does \fInot\fP invoke the shell.
in C, avoid system(3); in Perl, avoid back-ticks and the
single-argument version of system().
Otherwise, an attacker could insert shell special characters into a
link and force the user to a program and arguments of that attacker's choosing.
.P
By itself, this mechanism doesn't protect against hypertext links such as
``file:///dev/zero'', which provide an infinite number of 0's
(and may crash your browser).
If protection from this sort of thing is
important to you, either modify your browser to protect itself, or
modify your BROWSER value so that it first checks for
``dangerous'' references.
.SH AUTHOR
.B browse
was written by David A. Wheeler <dwheeler@dwheeler.com>,
who also developed the Secure BROWSER specification.
.SH BUGS
None are known.
The heuristic converting non-absolute references to absolute references
is somewhat complex, but that seems unavoidable for ``doing the right thing.''
.SH AVAILABILITY
You can get this program and related information from
http://www.dwheeler.com/browse.
.SH SEE ALSO
.BR uri (7)