chiark / gitweb /
cleanup: All the whitespace fixes, all at once.
[mLib] / man / url.3
CommitLineData
b6b9d458 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..
fbf20b5b 14.TH url 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
b6b9d458 15.SH NAME
16url \- manipulation of form-urlencoded strings
08da152e 17.\" @url_initenc
18.\" @url_enc
19.\" @url_initdec
20.\" @url_dec
b6b9d458 21.SH SYNOPSIS
22.nf
d2a91066 23.B "#include <mLib/url.h>"
b6b9d458 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
33The functions in
34.B <mLib/url.h>
35read and write `form-urlencoded' data, as specified in RFC1866. The
36encoding represents a sequence of name/value pairs where both the name
37and value are arbitrary binary strings (although the format is optimized
38for textual data). An encoded string contains no nonprintable
39characters or whitespace. This interface is capable of decoding any
40urlencoded string; however, it can currently only
41.I encode
42names and values which do not contain null bytes, because the encoding
43interface uses standard C strings.
44.PP
45Encoding a sequence of name/value pairs is achieved using the
46.B url_enc
47function. It requires as input an
48.IR "encoding context" ,
49represented as an object of type
50.BR url_ectx .
51This must be initialized before use by passing it to the function
52.BR url_initenc .
53Each call to
54.B url_enc
55encodes one name/value pair, appending the encoded output to a dynamic
56string (see
08da152e 57.BR dstr (3)
b6b9d458 58for details).
59.PP
7e4708e4
MW
60You can set flags in the encoding context's
61.B f
62member:
63.TP
64.B URLF_STRICT
65Be strict about escaping non-alphanumeric characters. Without this,
d4efbcd9 66potentially unsafe characters such as
7e4708e4
MW
67.RB ` / '
68and
69.RB ` ~ '
70will be left unescaped, which makes encoded filenames (for example) more
71readable.
72.TP
73.B URLF_LAX
74Be very lax about non-alphanumeric characters. Everything except
75obviously-unsafe characters like
76.RB ` & '
d4efbcd9 77and
7e4708e4
MW
78.RB ` = '
79are left unescaped.
80.PP
b6b9d458 81Decoding a sequence of name/value pairs is performed using the
82.B url_dec
83function. It requires as input a
84.IR "decoding context" ,
85represented as an object of type
86.BR url_dctx .
87This must be initialized before use by passing it to the function
88.BR url_initdec ,
89along with the address of the urlencoded string to decode. The string
90is not modified during decoding. Each call to
91.B url_dec
92extracts a name/value pair. The name and value are written to the
93dynamic strings
94.I n
95and
96.IR v ,
97so you probably want to reset them before each call. If there are no
98more name/value pairs to read,
99.B url_dec
100returns zero; otherwise it returns a nonzero value.
101.SH EXAMPLE
102The example code below demonstrates converting between a symbol table
103and 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
111typedef struct {
112 sym_base _b;
113 char *v;
114} val;
115
116void 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
134void 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
08da152e 145.SH "SEE ALSO"
146.BR mLib (3).
b6b9d458 147.SH AUTHOR
9b5ac6ff 148Mark Wooding, <mdw@distorted.org.uk>.