I, L, M & N

Back to [Book] [Topic]

Functions and Macros beginning with I, L, M & N

The following functions and macros are discussed in this section:

`insert()` Function	`log_error()` Function	`MALLOC()` Macro	`net_flush()` Function
`net_ip2host()` Function	`net_read()` Function	`net_sendfile()` Function	`net_write()` Function
`netbuf_buf2sd()` Function	`netbuf_close()` Function	`netbuf_getbytes()` Function	`netbuf_getc()` Function
`netbuf_grab()` Function	`netbuf_open()` Function	`nsapi_module_init()` Function	`NSAPI_RUNTIME_VERSION()` Macro	`NSAPI_VERSION()` Macro

`insert()` Function

The insert filter method is called when a filter is inserted into a filter stack by the filter_insert function or insert-filter SAF.

Syntax	Return Values	Parameters	Example
int insert(FilterLayer layer, pblock pb);	`REQ_PROCEED` if the filter should be inserted into the filter stack, `REQ_NOACTION` if the filter should not be inserted because it is not required, or `REQ_ABORTED` if the filter should not be inserted because of an error.	`FilterLayer layer` is the filter layer at which the filter is being inserted. `pblock pb` is the set of parameters passed to `filter_insert` or specified by the `fn="insert-filter"` directive.	int myfilter_insert(FilterLayer layer, pblock pb) { if (pblock_findval("dont-insert-filter", pb)) return REQ_NOACTION; return REQ_PROCEED; } ... FilterMethods myfilter_methods = FILTER_METHODS_INITIALIZER; const Filter *myfilter; myfilter_methods.insert = &myfilter_insert; myfilter = filter_create("myfilter", &myfilter_methods); ...

See Also

`log_error()` Function

The log_error function creates an entry in an error log, recording the date, the severity, and a description of the error.

Syntax	Return Values	Parameters	Example
int log_error(int degree, char func, Session sn, Request rq, char fmt, ...);	`0` if the log entry is created, or `-1` if the log entry is not created.	`int degree` specifies the severity of the error. The parameter value must be one of the following constants: `LOG_VERBOSE` — Debug message `LOG_VERBOSE` — Debug message `LOG_INFORM` — Information message `LOG_WARN` — Warning `LOG_FAILURE` — Operation failed `LOG_MISCONFIG`— Misconfiguration `LOG_SECURITY` — Authentication or authorization failure `LOG_CATASTROPHE`— Nonrecoverable server error `char func` is the name of the function where the error has occurred. `Session sn` is the session. `Request rq` is the request. `char fmt` specifies the format for the `printf` function that delivers the message.	log_error(LOG_WARN, "send-file", sn, rq, "error opening buffer from %s (%s)"), path, system_errmsg(fd));

See Also

func_exec() Function

`MALLOC()` Macro

The MALLOC macro is a platform-independent substitute for the C library routine malloc. It allocates size bytes from the requests's memory pool. The memory can be explicitly freed by a call to FREE. If the memory is not explicitly freed, it is automatically freed after processing of the current request has been completed. If pooled memory has been disabled in the configuration file with the built-in SAF pool-init , PERM_MALLOC and MALLOC both obtain their memory from the system heap. However, because memory allocated by MALLOC is automatically freed, it should not be shared between threads.

If pooled memory has been disabled in the configuration file with the built-in SAF pool-init, , PERM_MALLOC and MALLOC both obtain their memory from the system heap.

Syntax	Return Values	Parameters	Example
void *MALLOC(int size)	A void pointer to a block of memory.	`int size` is the number of bytes to allocate.	/* Allocate 256 bytes for a name / char name; name = (char *) MALLOC(256);

See Also

`net_flush()` Function

The net_flush function flushes any buffered data. If you require that data be sent immediately, call net_flush after calling the network output functions such as net_write or net_sendfile.

Syntax	Return Values	Parameters	Example
int net_flush(SYS_NETFD sd);	`0` on success, or a negative value if an error occurs.	`SYS_NETFD sd` is the socket to flush.	net_write(sn->csd, "Please wait... ", 15); net_flush(sn->csd); /* Perform some time-intensive operation */ ... net_write(sn->csd, "Thank you.\n", 11);

See Also

net_write() Function
net_sendfile() Function

`net_ip2host()` Function

The net_ip2host function transforms a textual IP address into a fully qualified domain name and returns the name.

Note -
This function works only if the DNS directive is enabled in the magnus.conf file.

Syntax	Return Values	Parameters
char net_ip2host(char ip, int verify);	A new string containing the fully qualified domain name if the transformation is accomplished, or NULL if the transformation is not accomplished.	`char ip` is the IP address as a character string in dotted-decimal notation: nnn.nnn.nnn.nnn*. `int verify`, if nonzero, specifies that the function should verify the fully qualified domain name. Though this verification requires an extra query, you should use it when checking the access control.

`net_read()` Function

The net_read function reads bytes from a specified socket into a specified buffer. The function waits to receive data from the socket until either at least one byte is available in the socket or the specified time has elapsed.

Syntax	Return Values	Parameters
int net_read (SYS_NETFD sd, char *buf, int sz, int timeout);	The number of bytes read, which will not exceed the maximum size, `sz`. A negative value is returned if an error has occurred, in which case `errno` is set to the constant `ETIMEDOUT` if the operation did not complete before `timeout` seconds elapsed.	`SYS_NETFD sd` is the platform-independent socket descriptor. `char *buf` is the buffer to receive the bytes. `int sz` is the maximum number of bytes to read. `int timeout` is the number of seconds to allow for the read operation before returning. The purpose of `timeout` is to limit the amount of time devoted to waiting until some data arrives.

See Also

net_write() Function

`net_sendfile()` Function

The net_sendfile function sends the contents of a specified file to a specified a socket. Either the whole file or a fraction might be sent, and the contents of the file might optionally be preceded or followed by caller-specified data.

Parameters are passed to net_sendfile in the sendfiledata structure. Before invoking net_sendfile, the caller must initialize every sendfiledata structure member.

Syntax Return Values Parameters Example

int net_sendfile(SYS_NETFD sd, const sendfiledata *sfd);

A positive number indicating the number of bytes successfully written, including the headers, file contents, and trailers. A negative value indicates an error.

SYS_NETFD sd is the socket to write to.
const sendfiledata *sfd identifies the data to send.

The following Service SAF sends a file bracketed by the strings "begin" and "end."

#include &lt;string.h>
#include "nsapi.h"

NSAPI_PUBLIC int service_net_sendfile(pblock *pb, Session *sn, Request *rq)
{
    char *path;
    SYS_FILE fd;
    struct sendfiledata sfd;
    int rv;

    path = pblock_findval("path", rq->vars);
    fd = system_fopenRO(path);
    if (!fd) {
        log_error(LOG_MISCONFIG, "service-net-sendfile", sn, rq,
                  "Error opening %s (%s)", path, system_errmsg());
        return REQ_ABORTED;
    }

    sfd.fd = fd;                     /* file to send */
    sfd.offset = 0;                  /* start sending from the beginning */
    sfd.len = 0;                     /* send the whole file */
    sfd.header = "begin";            /* header data to send before the file */
    sfd.hlen = strlen(sfd.header);   /* length of header data */
    sfd.trailer = "end";             /* trailer data to send after the file */
    sfd.tlen = strlen(sfd.trailer);  /* length of trailer data */

    /* send the headers, file, and trailers to the client */
    rv = net_sendfile(sn->csd, &amp;sfd);

    system_fclose(fd);

    if (rv &lt; 0) {
        log_error(LOG_INFORM, "service-net-sendfile", sn, rq,
                 "Error sending %s (%s)", path, 
                 system_errmsg());
        return REQ_ABORTED;
    }

    return REQ_PROCEED;
}

See Also

net_flush() Function

`net_write()` Function

The net_write function writes a specified number of bytes to a specified socket from a specified buffer.

Syntax	Return Values	Parameters	Example
int net_write(SYS_NETFD sd, char *buf, int sz);	The number of bytes written, which might be less than the requested size if an error occurs.	`SYS_NETFD` `sd` is the platform-independent socket descriptor. `char *buf` is the buffer containing the bytes. `int sz` is the number of bytes to write.	if (net_write(sn->csd, FIRSTMSG, strlen(FIRSTMSG)) == IO_ERROR) return REQ_EXIT;

See Also

net_read() Function

`netbuf_buf2sd()` Function

The netbuf_buf2sd function sends a buffer to a socket. You can use this function to send data from IPC pipes to the client.

Syntax	Return Values	Parameters
int netbuf_buf2sd(netbuf *buf, SYS_NETFD sd, int len);	The number of bytes transferred to the socket, if successful, or the constant `IO_ERROR` if unsuccessful.	`netbuf *buf` is the buffer to send. `SYS_NETFD` `sd` is the platform-independent identifier of the socket. `int len` is the length of the buffer.

See Also

netbuf_close() Function
netbuf_getc() Function
netbuf_getbytes() Function
netbuf_grab() Function
netbuf_open() Function

`netbuf_close()` Function

The netbuf_close function deallocates a network buffer and closes its associated files. Use this function when you need to deallocate the network buffer and close the socket.

Never close the netbuf parameter in a session structure.

Syntax	Return Values	Parameters
void netbuf_close(netbuf *buf);	`void`	`netbuf *buf` is the buffer to close.

See Also

netbuf_buf2sd() Function
netbuf_getc() Function
netbuf_getbytes() Function
netbuf_grab() Function
netbuf_open() Function

`netbuf_getbytes()` Function

The netbuf_getbytes function reads bytes from a network buffer into a caller-supplied buffer. If the network buffer is empty, the function waits to receive data from the network buffer's socket until either at least one byte is available from the socket or the network buffer's timeout has elapsed.

Syntax Return Values Parameters Example

int netbuf_getbytes(netbuf *buf, char *buffer, int sz);

The number of bytes placed into the buffer between 1 and sz if the operation is successful, the constant NETBUF_EOF on end of file, or the constant NETBUF_ERROR if an error occurred.

netbuf *buf is the buffer from which to retrieve bytes.
char *buffer is the caller-supplied buffer that receives the bytes.
int sz is the maximum number of bytes to read.

int cl = 0;

* Read the entire request body */
for (;;) {
     char mybuf[1024];
     int rv;

     rv = netbuf_getbytes(sn->inbuf, mybuf, sizeof(mybuf));
     if (rv == NETBUF_EOF) {
         log_error(LOG_INFORM, "mysaf", sn, rq,
                   "Received %d byte(s)",
                   cl);
         break;
     }
     if (rv == NETBUF_ERROR) {
         log_error(LOG_FAILURE, "mysaf", sn, rq,
                   "Error reading request body (%s)",
                   cl, system_errmsg());
         break;     }

     cl += rv;
}

See Also

netbuf_buf2sd() Function
netbuf_close() Function
netbuf_getc() Function
netbuf_grab() Function
netbuf_open() Function

`netbuf_getc()` Function

The netbuf_getc function retrieves a character from the cursor position of the network buffer specified by b.

Note -
Because the constant IO_EOF has a value of 0, netbuf_getc cannot be used to read data that might contain a null character. To read binary data, use netbuf_getbytes() Function or netbuf_grab() Function.

Syntax	Return Values	Parameters
netbuf_getc(netbuf b);	The integer representing the character if a character is retrieved, or the constant `IO_EOF` or `IO_ERROR` for end of file or an error.	`netbuf b` is the buffer from which to retrieve one character.

See Also

netbuf_buf2sd() Function
netbuf_close() Function
netbuf_getbytes() Function
netbuf_grab() Function
netbuf_open() Function

`netbuf_grab()` Function

The netbuf_grab function reads sz number of bytes from the network buffer’s (buf) socket into the network buffer. If the buffer is not large enough it is resized. The data can be retrieved from buf->inbuf on success.

This function is used by the function netbuf_buf2sd.

Syntax	Return Values	Parameters
int netbuf_grab(netbuf *buf, int sz);	The number of bytes actually read between `1` and `sz` if the operation is successful, or the constant `IO_EOF` or `IO_ERROR` for end of file or an error.	`netbuf *buf` is the buffer to read into. `int sz` is the number of bytes to read.

See Also

netbuf_buf2sd() Function
netbuf_close() Function
netbuf_getbytes() Function
netbuf_getc() Function
netbuf_open() Function

`netbuf_open()` Function

The netbuf_open function opens a new network buffer and returns it. You can use netbuf_open to create a netbuf structure and start using buffered I/O on a socket.

Syntax	Return Values	Parameters
netbuf* netbuf_open(SYS_NETFD sd, int sz);	A pointer to a new `netbuf` network buffer structure.	`SYS_NETFD sd` is the platform-independent identifier of the socket. `int sz` is the number of characters to allocate for the network buffer.

See Also

netbuf_buf2sd() Function
netbuf_close() Function
netbuf_getc() Function
netbuf_getbytes() Function
netbuf_grab() Function

`nsapi_module_init()` Function

Defines the nsapi_module_init function, which is a module initialization entry point that enables a plug-in to create filters when it is loaded. When an NSAPI module contains an nsapi_module_init function, the server will call that function immediately after loading the module. The nsapi_module_init presents the same interface as an Init SAF, and it must follow the same rules.

Use the nsapi_module_init function to register SAFs with func_insert, create filters with filter_create, register virtual server initialization/destruction callbacks with vs_register_cb, and perform other initialization tasks.

Syntax	Return Values	Parameters
int nsapi_module_init(pblock pb, Session sn, Request *rq);	`REQ_PROCEED` on success, or `REQ_ABORTED` on error.	`pblock pb` is a set of parameters specified by the `fn="load-modules"` directive. `Session sn` (the session) is NULL. `Request *rq` (the request) is NULL.

See Also

`NSAPI_RUNTIME_VERSION()` Macro

The NSAPI_RUNTIME_VERSION macro defines the NSAPI version available at runtime. This version is the same as the highest NSAPI version supported by the server the plug-in is running in. The NSAPI version is encoded as in USE_NSAPI_VERSION.

The value returned by the NSAPI_RUNTIME_VERSION macro is valid only in iPlanet™ Web Server 6.0, Netscape Enterprise Server 6.0, Sun ONE Web Server 6.1, and Sun Java System Web Server 7.0 Update 2. The server must support NSAPI 3.1 for this macro to return a valid value. Additionally, to use NSAPI_RUNTIME_VERSION, you must compile against an nsapi.h header file that supports NSAPI 3.2 or higher.

Do not attempt to set the value of the NSAPI_RUNTIME_VERSION macro directly. Instead, use the USE_NSAPI_VERSION macro.

Syntax

Example

int NSAPI_RUNTIME_VERSION

NSAPI_PUBLIC int log_nsapi_runtime_version(pblock *pb, Session *sn, Request *rq) 
{
    log_error(LOG_INFORM, "log-nsapi-runtime-version", sn, rq,
                "Server supports NSAPI version %d.%d\n",
                NSAPI_RUNTIME_VERSION / 100,
                NSAPI_RUNTIME_VERSION % 100);
     return REQ_PROCEED;
}

See Also

`NSAPI_VERSION()` Macro

The NSAPI_VERSION macro defines the NSAPI version used at compile time. This value is determined by the value of the USE_NSAPI_VERSION macro or by the highest NSAPI version supported by the nsapi.h header the plug-in was compiled against. The NSAPI version is encoded as in USE_NSAPI_VERSION.

Do not attempt to set the value of the NSAPI_VERSION macro directly. Instead, use the USE_NSAPI_VERSION macro.

Syntax

Example

int NSAPI_VERSION

NSAPI_PUBLIC int log_nsapi_compile_time_version(pblock *pb, Session *sn, Request *rq) 
{
    log_error(LOG_INFORM, "log-nsapi-compile-time-version", sn, rq,
            "Plugin compiled against NSAPI version %d.%d\n",
            NSAPI_VERSION / 100,
            NSAPI_VERSION % 100);
    return REQ_PROCEED;
}

See Also

I, L, M & N

Functions and Macros beginning with I, L, M & N

insert() Function

log_error() Function

MALLOC() Macro

net_flush() Function

net_ip2host() Function

net_read() Function

net_sendfile() Function

net_write() Function

netbuf_buf2sd() Function

netbuf_close() Function

netbuf_getbytes() Function

netbuf_getc() Function

netbuf_grab() Function

netbuf_open() Function

nsapi_module_init() Function

NSAPI_RUNTIME_VERSION() Macro

NSAPI_VERSION() Macro

Labels

`insert()` Function

`log_error()` Function

`MALLOC()` Macro

`net_flush()` Function

`net_ip2host()` Function

`net_read()` Function

`net_sendfile()` Function

`net_write()` Function

`netbuf_buf2sd()` Function

`netbuf_close()` Function

`netbuf_getbytes()` Function

`netbuf_getc()` Function

`netbuf_grab()` Function

`netbuf_open()` Function

`nsapi_module_init()` Function

`NSAPI_RUNTIME_VERSION()` Macro

`NSAPI_VERSION()` Macro