FrcaCtrlCreate Subroutine

Purpose

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

Library

FRCA Library (libfrca.a)

Syntax

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

Description

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

Item Description
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

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

Error Codes

Item Description
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.