Update to the new FSF address
[infodrom/cgilib] / cgiGetCookie.3
1 .\" cgiGetCookie - Return a cookie
2 .\" Copyright (c) 1998,9,2007,8 by Martin Schulze <joey@infodrom.org>
3 .\" 
4 .\" This program is free software; you can redistribute it and/or modify
5 .\" it under the terms of the GNU General Public License as published by
6 .\" the Free Software Foundation; either version 2 of the License, or
7 .\" (at your option) any later version.
8 .\" 
9 .\" This program is distributed in the hope that it will be useful,
10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 .\" GNU General Public License for more details.
13 .\" 
14 .\" You should have received a copy of the GNU General Public License
15 .\" along with this program; if not, write to the Free Software Foundation
16 .\" Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
17 .\"
18 .TH cgiGetCookie 3 "6 April 2008" "CGI Library" "Programmer's Manual"
19 .SH NAME
20 cgiGetCookie \- Return a cookie
21 .SH SYNOPSYS
22 .nf
23 .B #include <cgi.h>
24 .sp
25 .BI "s_cookie *cgiGetCookie (s_cgi *" parms ", const char *" name );
26 .fi
27 .SH DESCRIPTION
28 This routine returns a pointer to a s_cookie structure that contains all
29 values for the cookie as referenced by
30 .IR name .
31 The pointer must not be freed.
32
33 The
34 .I s_cookie
35 structure is declared as follows:
36
37 .RS
38 .nf
39 typedef struct cookie_s {
40     char     *version,
41              *name,
42              *value,
43              *path,
44              *domain;
45 } s_cookie;
46 .fi
47 .RE
48
49 Memory allocated by this data structure is automatically freed by the
50 final call to
51 .BR cgiFree (3).
52
53 To set a cookie in your program you'll need to manually add additional
54 header lines.  Please take a look at
55 .IR cgitest.c .
56 Basically, you'll need to add the following code:
57
58 .nf
59    cgiSetHeader ("Set-Cookie", "Version=1; name=value; Path=/");
60    cgiHeader();
61 .fi
62
63 Please read the included file
64 .I cookies.txt
65 as well.
66 .SH "RETURN VALUE"
67 On success a pointer to a s_cookie structure is returned.  If no
68 cookie was set or no cookie with a given name exists NULL is returned.
69 .SH "AUTHOR"
70 This CGI library is written by Martin Schulze
71 <joey@infodrom.org>.  If you have additions or improvements
72 please get in touch with him.
73 .SH "SEE ALSO"
74 .BR cgiGetValue (3),
75 .BR cgiGetVariables (3),
76 .BR cgiGetCookies (3),
77 .BR cgiDebug (3),
78 .BR cgiHeader (3),
79 .BR cgiInit (3),
80 .BR cgiFree (3).