tclfcgi/README at master · jdc8/tclfcgi · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194

fcgi - A Tcl wrapper for the FastCGI library
Generated from file '' by tcllib/doctools with format 'text'
fcgi(n) 1.0.0  "A Tcl wrapper for the FastCGI library"

NAME
====

fcgi - fcgi Package Reference

SYNOPSIS
========

package require Tcl 8.6
package require critcl ?3?

fcgi Init
fcgi OpenSocket path ?backlog?
fcgi CloseSocket socket
fcgi InitRequest socket ?flags?
fcgi Free request close
fcgi Accept_r request
fcgi Finish_r request
fcgi GetParam request ?name?
fcgi PutStr request stream string
fcgi GetStr request stream n
fcgi SetExitStatus request stream status

DESCRIPTION
===========

The _fcgi_ package is a wrapper for the _FastCGI library_
<URL:http://www.fastcgi.com>. The wrapper is based on version 2.4.1 of the
FastCGI library. It is written using critcl 3.

The package tries to stay close to the C calls in the FastCGI library
application server API. Consult the _FastCGI library documentations_
<URL:http://www.fastcgi.com/drupal/node/6> for more details about the wrapped
API functions and data structures.

The _fcgi_ package code can be found on _GitHub_
<URL:http://github.com/jdc8/tclfcgi>.

_fcgi_ commands
===============

    fcgi Init

        Initialize the FCGX library. Must be called before calling the Accept_r
        command.

    fcgi OpenSocket path ?backlog?

        Create a FastCGI listen socket.

        The path arguments can be a Unix domain socket, a Windows named pipe, or
        a colon followed by a port number.

        The backlog argument is the listen queue depth used in the _listen()_
        call. Default value is 5.

        The socket file descriptor is returned.

    fcgi CloseSocket socket

        Close the FastCGI listen socket.

    fcgi InitRequest socket ?flags?

        Initialize a _FCGX_Request_ structure for use with Accept_r.

        The socket argument is the file descriptor as returned by the OpenSocket
        command.

        the flags argument is specified as an integer. Default value is 0.

        A _FCGX_Request_ handle is returned.

    fcgi Free request close

        Frees the memory allocated by the _FCGX_Request_ structure. If the close
        close is true, the associated stream are closed too.

    fcgi Accept_r request

        Accept a new request.

    fcgi Finish_r request

        Finish the request.

    fcgi GetParam request ?name?

        Obtain value of FCGI parameter.

    fcgi PutStr request stream string

        Write the specified string to the specified stream. Known streams are
        _stdout_ and _stderr_.

    fcgi GetStr request stream n

        Read n consecutive bytes from the specified stream. The string is
        returned. The only known value for stream is _stdin_.

    fcgi SetExitStatus request stream status

        Set the exit status for the stream.

Examples
========

The following example opens a FCGI listen socket on the specified path or port
and responds to requests with a HTML page containing the FCGI parameters and, if
present, the POST-ed data.

| package require fcgi

| if {[llength $argv] != 1} {
|     puts stderr "Usage: example.tcl <path_or_port>"
|     exit
| }

| set sock [fcgi OpenSocket [lindex $argv 0] 1]
| fcgi Init
| set req [fcgi InitRequest $sock {}]

| while {1} {
|     puts "### Accepr_r ###################################################################"
|     fcgi Accept_r $req
|     puts $req
|     puts "### GetParam ###################################################################"
|     set pd [fcgi GetParam $req]
|     dict for {k v} $pd {
| 	puts "$k=$v"
|     }
|     puts "### GetStr #####################################################################"
|     set content ""
|     if {[dict exists $pd "CONTENT_LENGTH"] && [string is integer -strict [dict get $pd "CONTENT_LENGTH"]] && [dict get $pd "CONTENT_LENGTH"] > 0} {
| 	set content [fcgi GetStr $req stdin [dict get $pd "CONTENT_LENGTH"]]
| 	puts $content
|     }
|     puts "### PutStr #####################################################################"
|     set C "Status: 200 OK
| Content-Type: text/html

| <html>
| <body>
| <h1>FCGI CriTcl wrapper test</h1>
| <h2>Parameters<h2>
| <table>
| "
|     dict for {k v} $pd {
| 	append C "<tr><td>$k</td><td>$v</td></tr>\n"
|     }
|     append C "</table>
| <h2>Body</h2>
| <pre>"
|     append C $content
|     append C "</pre>\n</body>\n</html>\n"
|     fcgi PutStr $req stdout $C
|     puts "### Finish_r ###################################################################"
|     fcgi SetExitStatus $req stdout 0
|     fcgi Finish_r $req
| }

Bugs, ideas, feedback
=====================

This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such at the _Github tracker_
<URL:https://github.com/jdc8/tclfcgi/issues>. Please also report any ideas for
enhancements you may have for either package and/or documentation.

License
=======

The fcgi wrapper is relicensed under the BSD license (specifically Modified BSD
aka New BSD aka 3-clause BSD). Check COPYING.BSD for more info.

KEYWORDS
========

cgi fcgi fastcgi

CATEGORY
========

cgi

COPYRIGHT
=========

Copyright (c) Jos Decoster <jos.decoster@gmail.com>