Technical Reference: Communications, Volume 2

FrcaCtrlCreate Subroutine

Purpose

Creates a Fast Response Cache Accelerator (FRCA) control instance.

Syntax

#include <frca.h> int32_t FrcaCtrlCreate ( FrcaHandle, InstanceSpec); int32_t * FrcaHandle; frca_ctrl_create_t * InstanceSpec;

The FrcaCtrlCreate subroutine creates and configures an FRCA instance that is associated with a previously configured TCP listen socket. TCP connections derived from the TCP listen socket are intercepted by the FRCA instance and, if applicable, adequate responses are generated by the in-kernel code on behalf of the user-level application.

The only FRCA instance type that is currently supported handles static GET requests as part of the Hypertext Transfer Protocol (HTTP).

Parameters

FrcaHandle Returns a handle that is required by the other FRCA API subroutines to refer to the newly configured FRCA instance.

InstanceSpec

Points to a frca_ctrl_create_t structure, which specifies the parameters used to configure the newly created FRCA instance. The structure contains the following members:
uint32_t serverType; char * serverName; uint32_t nListenSockets; uint32_t * ListenSockets; uint32_t flags; uint32_t nMaxConnections; uint32_t nLogBufs; char * logFile;

Note: Structure members do not necessarily appear in this order.

serverType

Specifies the type for the FRCA instance. This field must be set to FCTRL_SERVERTYPE_HTTP.

serverName

Specifies the value to which the HTTP header field is set.

nListenSocket

Specifies the number of listen socket descriptors pointed to by listenSockets.

listenSocket

Specifies the TCP listen socket that the FRCA instance should be configured to intercept.

Note: The TCP listen socket must exist and the SO_KERNACCEPT socket option must be set at the time of calling the FrcaCtrlCreate subroutine.

flags

Specifies the logging format, the initial state of the logging subsystem, and whether responses generated by the FRCA instance should include the Server: HTTP header field. The valid flags are as follows:

FCTRL_KEEPALIVE
FCTRL_LOGFORMAT
FCTRL_LOGFORMAT_ECLF
FCTRL_LOGFORMAT_VHOST
FCTRL_LOGMODE
FCTRL_LOGMODE_ON
FCTRL_SENDSERVERHEADER

nMaxConnections

Specifies the maximum number of intercepted connections that are allowed at any given point in time.

nLogBufs

Specifies the number of preallocated logging buffers used for logging information about HTTP GET requests that have been served successfully.

logFile: Specifies the absolute path to a file used for appending logging information. The HTTP GET engine uses logFile as a base name and appends a sequence number to it to generate the actual file name. Whenever the size of the current log file exceeds the threshold of approximately 1 gigabyte, the sequence number is incremented by 1 and the logging subsystem starts appending to the new log file.
Note: The FRCA instance creates the log file, but not the path to it. If the path does not exist or is not accessible, the FRCA instance reverts to the default log file /tmp/frca.log.

Return Values

0	The subroutine completed successfully.
-1	The subroutine failed. The global variable errno is set to indicate the specific type of error.

Error Codes

EINVAL	The FrcaHandle or the InstanceSpec parameter is zero or is not of the correct type or the listenSockets components do not specify any socket descriptors.
EFAULT	The FrcaHandle or the InstanceSpec or a component of the InstanceSpec points to an invalid address.
ENOTREADY	The kernel extension is currently being loaded or unloaded.
ENOTSOCK	A TCP listen socket does not exist.

Related Information

The FrcaCacheCreate subroutine, the FrcaCacheDelete subroutine, the FrcaCacheLoadFile subroutine, the FrcaCacheUnloadFile subroutine, the FrcaCtrlDelete subroutine, the FrcaCtrlLog subroutine, the FrcaCtrlStart subroutine, the FrcaCtrlStop subroutine.