libexec/httpd/libbozohttpd/libbozohttpd.3

   1 .\" $NetBSD: libbozohttpd.3,v 1.3 2014/03/18 18:20:38 riastradh Exp $
   2 .\"
   3 .\" $eterna: libbozohttpd.3,v 1.2 2010/05/10 02:48:23 mrg Exp $
   4 .\"
   5 .\" Copyright (c) 2009 The NetBSD Foundation, Inc.
   6 .\" All rights reserved.
   7 .\"
   8 .\" This manual page is derived from software contributed to The
   9 .\" NetBSD Foundation by Alistair Crooks (agc@NetBSD.org)
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  22 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  24 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  25 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  26 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  27 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  28 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  29 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  30 .\" POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .Dd November 5, 2009
  33 .Dt LIBBOZOHTTPD 3
  34 .Os
  35 .Sh NAME
  36 .Nm libbozohttpd
  37 .Nd embedded web server library
  38 .Sh LIBRARY
  39 .Lb libbozohttpd
  40 .Sh SYNOPSIS
  41 .In bozohttpd.h
  42 .Ft int
  43 .Fo bozo_set_pref
  44 .Fa "bozoprefs_t *prefs" "char *name" "char *value"
  45 .Fc
  46 .Ft char *
  47 .Fo bozo_get_pref
  48 .Fa "bozoprefs_t *prefs" "char *name"
  49 .Fc
  50 .Ft int
  51 .Fo bozo_set_defaults
  52 .Fa "bozohttpd_t *httpd" "bozoprefs_t *prefs"
  53 .Fc
  54 .Ft void
  55 .Fo bozo_setup
  56 .Fa "bozohttpd_t *httpd" "bozoprefs_t *prefs" "const char *vhost" "char *slash"
  57 .Fc
  58 .Ft bozo_httpreq_t *
  59 .Fo bozo_read_request
  60 .Fa "bozohttpd_t *httpd"
  61 .Fc
  62 .Ft void
  63 .Fo bozo_process_request
  64 .Fa "bozo_httpreq_t *"
  65 .Fc
  66 .Ft void
  67 .Fo bozo_clean_request
  68 .Fa "bozo_httpreq_t *"
  69 .Fc
  70 .Sh DESCRIPTION
  71 .Nm
  72 is a library interface to the
  73 .Xr bozohttpd 8
  74 web server.
  75 The
  76 .Nm
  77 library can be used to embed a webserver
  78 in your applications.
  79 .Pp
  80 Normal operation sees the
  81 .Nm
  82 process be initialised using the
  83 .Fn bozo_set_defaults
  84 function, which will set up the default port
  85 and other internal settings, allocating
  86 any necessary space as needed.
  87 The
  88 .Fn bozo_set_defaults
  89 function returns 1 on sucess, 0 on failure.
  90 .Pp
  91 The
  92 .Fn bozo_setup
  93 function is used to specify the virtual host name
  94 for the web server.
  95 A NULL host name will mean that
  96 .Nm
  97 will use the local value for the host name,
  98 as returned by
  99 .Xr gethostname 3 .
 100 This virtual hostname should be a fully qualified domain name.
 101 The final argument to
 102 .Fn bozo_setup
 103 is the name of the directory to serve as the root
 104 directory of the web server tree.
 105 .Pp
 106 Once the server has been set up, it serves
 107 requests by using the
 108 .Fn bozo_read_request
 109 function, which returns a pointer to a request structure,
 110 and
 111 .Fn bozo_process_request ,
 112 which deals with the request, and answers the client.
 113 The request space is de-allocated
 114 using the
 115 .Fn bozo_clean_request
 116 function.
 117 .Pp
 118 Preferences are set
 119 using the function
 120 .Fn bozo_set_pref
 121 function
 122 and queried using the two
 123 .Fn bozo_get_pref
 124 function.
 125 This is the main interface for selecting options, and for
 126 setting preferences.
 127 .Sh SEE ALSO
 128 .Xr gethostname 3 ,
 129 .Xr ssl 3 ,
 130 .Xr services 5 ,
 131 .Xr httpd 8
 132 .Sh HISTORY
 133 The
 134 .Nm
 135 library first appeared in
 136 .Nx 6.0 .
 137 .Sh AUTHORS
 138 .An Matthew R. Green Aq Mt mrg@eterna.com.au
 139 .An Alistair Crooks Aq Mt agc@NetBSD.org
 140 wrote this high-level interface.
 141 .Pp
 142 This manual page was written by
 143 .An Alistair Crooks .