The libfcgi2.dll addresses issues with the original libfcgi.dll with Windows Web Servers, most
notably the lack of a SIGTERM handler.
The Dll has been completely redesigned, exposing as many of the same functions as the original.
These are defined in the C Header file libfcgi2.h (or the BASIC include file FCGX_Header.inc)
To use this library, at a minimum, three function calls are required.
(See the Hello World examples, or a more complete C++ example, or a BASIC complete example of a client application)
If you want the Request parameters you would additionally need to call
And if the request contains some STDIN data (like from a POST method)
All these functions work identically to the original dll, meaning the arguments
are the same, and the calling convention is the same. They are a drop in
To use the library, the only change you will need to make is in the Structure
definitions for FCGX_REQUEST and FCGX_STREAM (see the header file)
For the SIGTERM notification event to be sent by the Web Server to this library
under IIS, the 'SignalBeforeTerminateSeconds' property in fcgiext.ini file must
be > 0. If it is not, the library will still work, but there will be no
opportunity for a graceful exit as no SIGTERM notification will be sent.
For testing, 'FCGIecho.exe' is included. This application will echo any GET
Query string and all POST data sent, and increment a counter for each request.
Since we wrote this from the ground up, we took the opportunity to provide
access to some of the more relevant request parameters, and also implemented a
more powerful StringBuilder class for buffering stream data.
Since the QUERY_STRING request parameter is most often needed, we put an ASCIIZ
pointer to it right in the FCGX_REQUEST structure. To get the entire string
just de-reference the pointer 'pzQuery'. (This pointer is always valid and
never NUL). If the request does not contain a query string, it will point to an
ASCIIZ string of zero length.
NOTE: The return is just the value portion of the name=value pair contained in
the param array. This saves the step of parsing out the value.
Assigning this pointer is done at the lowest level when the FCGI name=value
pairs are decoded. At that level, it only requires a few additional steps to
put some variables at your fingertips. At the application level it is more
work. Because of this, we also added Request Method (ReqMethod) and
CONTENT_LENGTH (ContLen) to the FCGX_REQUEST structure.
The Request Variables are sent with *every* request and depending on the web
server, there can be over 3k of them. To minimize the amount of memory copy,
they are read directly into memory and an a pointer is assigned to each name/value
pair. A pointer to the array of pointers is stored in the structure variable ‘envp’
CONTENT_LENGTH is stored in the ‘ContLen’ member of the structure, and is a 4
byte signed integer.
Request Method is stored in the 'ReqMethod' property of the FCGX_REQUEST
structure as a 4 byte signed integer code. The codes are in the header file:
HTTP_GET = 1
HTTP_POST = 2
HTTP_HEAD = 3
HTTP_PUT = 4
HTTP_DELETE = 5
HTTP_OPTIONS = 6
HTTP_TRACE = 7
HTTP_CONNECT = 8
HTTP_UNKNOWN = 9
This makes using Request Method in a switch/select/if statement much faster
than comparing a string byte by byte for example.
The entire request parameter set is in an ASCIIZ string array (in exactly the
same way it was designed in the original libfcgi.dll), pointed to by the
pointer 'envp', meaning the pointer points to an array of ASCIIZ pointers. The
last pointer in the array is a NUL pointer indicating the end of the array.
Double de-referencing this pointer will return the name=value request
To complete the request parameter variables, for convenience, we also added
'nParam'. This is a count of the name=value pairs in the array.
Next we have 'Role' and 'ConnFlags'. These were added in case we eventually
support other roles. For now the only role supported is Responder.
'ReqCount' is simply a cumulative count of the number if requests received in
liew of ID.
Finally, 'zVersion' will give you the version of the library as an integer
x1000. meaning 2089 would be 2.089
(The version is also contained in the Properties of the Dll)
For this dll, we wrote a custom implementation of the C++ String Builder class.
For those that are new to this concept, the class is a suite of functions that
manage memory for tasks like string concatenation (because concatenation is a
very slow way to append data to a string.)
This implementation starts with a small amount of memory and as more data is
added, the class automatically requests more memory to hold it, managing all
the memory allocation in the background. The available buffer length in memory,
is the 'Capacity', and the length of the data within that buffer memory is
'LenStored'. 'pData' points to the first byte of the buffer.
In managing memory, the class doubles the size of the buffer every time you
exceed 'Capacity' - this makes the most sense from a memory management standpoint as Joel Spolsky points out in his article on strings.
The string can be thought of, simply as a sequence of bytes that are available
as a buffer for your output. You can write to the buffer at any position, you
can read from it at any position, and you can increase its size and set the
LenStored value at any time. There are three buffers STDIN, STDOUT and STDERR
that can be used in this fashion.
The legacy reading and writing functions FCGX_GetStr(), FCGX_PutStr() read and
write sequentially, meaning when you write bytes, they are appended to whatever
is already in the buffer.
When you read bytes, the read where the last read left off. (The position
within the buffer is contained in the structure variable 'CurPos'. This will
have a value between 1 and LenStored and is reset at the begging of each new
Once your STDOUT buffer has been created, it can be sent to the Web Server by
calling FCGX_Flush(), or FCGX_Finish_r(). If neither are called and the application
simply loops back and calls FCGX_Accept_r() the buffer will be sent and then
emptied ready for the next Request.
It should be noted that FCGX_Flush() takes the request structure as an
argument, NOT a pointer to the stream structure like FCGX_FFlush did in the
original libfcgi.dll. FCGX_Flush() simply checks STDOUT and STDERR for any data
('LenStored' > 0) and sends it to the Web Server.
If you want to increase the size of a buffer, you must call FCGX_EnsureCap(). This
is the only way to accomplish this using the String Builder Class. The new
Capacity will be contained in the structure variable 'Capacity' and also
returned from the function call.
FCGX_URLDecode() is a very fast "in place" URL decoder, meaning the buffer
you send to it will be overwritten with the decoded string. The decoded length
(possibly shorter, never longer) is returned by the function.
FCGX_GetBytes() & FCGX_PutBytes() simply wrap a very fast ASM copymem
function for copying bytes to or from any of the buffers. For all the
variations tried (six register versions and eight mmx register versions) this
one still beats them all. The speed limit on memory copy is evidently imposed
by the actual speed of memory, however, the rep movsd pair is very well optimized
and has slightly less overhead than the others. It is up to you to make sure
your pointers are within the bounds of the buffer ('pData' to
'pData'+'Capacity'). These functions offer the flexibility to put/get bytes
anywhere within the buffer. (For languages that make use of BSTR, there are
also FCGX_Read and FCGX_Write.)
If an exception is thrown, a numeric error code is generated along with a
description of the error. Depending on the error, this may be the result of
FormatMessage(GetLastError) a Pipe error or FCGI Library error. The Error code
will be returned as a -ve integer in all cases, and the description can be
obtained by dereferencing the pzLastErr pointer in the FCGX_REQUEST structure.
Library errors usually preclude returning an error via STDERR. This should be
used to report errors from your application (probably by printing them to a
text file somewhere outside the cgi-bin directory). Depending on the web server
settings, these errors may be written to the log or returned to the user.
For FCGI troubleshooting, a FCGI debug log may be enabled by calling
FCGX_InitRequest() with FCGX_DEBUG as the last parameter. This will create a directory of the root drive (C in this case)
Each instance of the application will have a distinct pipe name and a distinct debug file name. The contents will be something like this debug from FCGIecho.exe