chiark - git - mdw - mLib/blob - man/url.3

   1 .\" -*-nroff-*-
   2 .de VS
   3 .sp 1
   4 .in +5n
   5 .ft B
   6 .nf
   7 ..
   8 .de VE
   9 .ft R
  10 .in -5n
  11 .sp 1
  12 .fi
  13 ..
  14 .TH url 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
  15 .SH NAME
  16 url \- manipulation of form-urlencoded strings
  17 .\" @url_initenc
  18 .\" @url_enc
  19 .\" @url_initdec
  20 .\" @url_dec
  21 .SH SYNOPSIS
  22 .nf
  23 .B "#include <mLib/url.h>"
  24
  25 .BI "void url_initenc(url_ectx *" ctx );
  26 .BI "void url_enc(url_ectx *" ctx ", dstr *" d ,
  27 .BI "             const char *" name ", const char *" value );
  28
  29 .BI "void url_initdec(url_dctx *" ctx ", const char *" p );
  30 .BI "int url_dec(url_dctx *" ctx ", dstr *" n ", dstr *" v );
  31 .fi
  32 .SH DESCRIPTION
  33 The functions in
  34 .B <mLib/url.h>
  35 read and write `form-urlencoded' data, as specified in RFC1866.  The
  36 encoding represents a sequence of name/value pairs where both the name
  37 and value are arbitrary binary strings (although the format is optimized
  38 for textual data).  An encoded string contains no nonprintable
  39 characters or whitespace.  This interface is capable of decoding any
  40 urlencoded string; however, it can currently only
  41 .I encode
  42 names and values which do not contain null bytes, because the encoding
  43 interface uses standard C strings.
  44 .PP
  45 Encoding a sequence of name/value pairs is achieved using the
  46 .B url_enc
  47 function.  It requires as input an
  48 .IR "encoding context" ,
  49 represented as an object of type
  50 .BR url_ectx .
  51 This must be initialized before use by passing it to the function
  52 .BR url_initenc .
  53 Each call to
  54 .B url_enc
  55 encodes one name/value pair, appending the encoded output to a dynamic
  56 string (see
  57 .BR dstr (3)
  58 for details).
  59 .PP
  60 You can set flags in the encoding context's
  61 .B f
  62 member:
  63 .TP
  64 .B URLF_STRICT
  65 Be strict about escaping non-alphanumeric characters.  Without this,
  66 potentially unsafe characters such as
  67 .RB ` / '
  68 and
  69 .RB ` ~ '
  70 will be left unescaped, which makes encoded filenames (for example) more
  71 readable.
  72 .TP
  73 .B URLF_LAX
  74 Be very lax about non-alphanumeric characters.  Everything except
  75 obviously-unsafe characters like
  76 .RB ` & '
  77 and
  78 .RB ` = '
  79 are left unescaped.
  80 .PP
  81 Decoding a sequence of name/value pairs is performed using the
  82 .B url_dec
  83 function.  It requires as input a
  84 .IR "decoding context" ,
  85 represented as an object of type
  86 .BR url_dctx .
  87 This must be initialized before use by passing it to the function
  88 .BR url_initdec ,
  89 along with the address of the urlencoded string to decode.  The string
  90 is not modified during decoding.  Each call to
  91 .B url_dec
  92 extracts a name/value pair.  The name and value are written to the
  93 dynamic strings
  94 .I n
  95 and
  96 .IR v ,
  97 so you probably want to reset them before each call.  If there are no
  98 more name/value pairs to read,
  99 .B url_dec
 100 returns zero; otherwise it returns a nonzero value.
 101 .SH EXAMPLE
 102 The example code below demonstrates converting between a symbol table
 103 and a urlencoded representation.  The code is untested.
 104 .VS
 105 #include <stdlib.h>
 106 #include <mLib/alloc.h>
 107 #include <mLib/dstr.h>
 108 #include <mLib/sym.h>
 109 #include <mLib/url.h>
 110
 111 typedef struct {
 112   sym_base _b;
 113   char *v;
 114 } val;
 115
 116 void decode(sym_table *t, const char *p)
 117 {
 118   url_dctx c;
 119   dstr n = DSTR_INIT, v = DSTR_INIT;
 120
 121   for (url_initdec(&c, p); url_dec(&c, &n, &v); ) {
 122     unsigned f;
 123     val *vv = sym_find(t, n.buf, -1, sizeof(*vv), &f);
 124     if (f)
 125       free(vv->v);
 126     vv->v = xstrdup(v.buf);
 127     DRESET(&n);
 128     DRESET(&v);
 129   }
 130   dstr_destroy(&n);
 131   dstr_destroy(&v);
 132 }
 133
 134 void encode(sym_table *t, dstr *d)
 135 {
 136   sym_iter i;
 137   url_ectx c;
 138   val *v;
 139
 140   url_initenc(&c);
 141   for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; )
 142     url_enc(&c, d, SYM_NAME(v), v->v);
 143 }
 144 .VE
 145 .SH "SEE ALSO"
 146 .BR mLib (3).
 147 .SH AUTHOR
 148 Mark Wooding, <mdw@distorted.org.uk>.