Sun Java System Web Server 6.1 SP9 NSAPI Programmer's Guide

Overview of NSAPI C Functions

NSAPI provides a set of C functions that are used to implement SAFs. They serve several purposes. They provide platform independence across Sun Java System Web Server operating system and hardware platforms. They provide improved performance. They are thread-safe which is a requirement for SAFs. They prevent memory leaks. And they provide functionality necessary for implementing SAFs. You should always use these NSAPI routines when defining new SAFs.

This section provides an overview of the function categories available and some of the more commonly used routines. All of the public routines are detailed in Chapter 7, NSAPI Function Reference.

The main categories of NSAPI functions are:

Parameter Block Manipulation Routines

The parameter block manipulation functions provide routines for locating, adding, and removing entries in a pblock data structure:

Protocol Utilities for Service SAFs

Protocol utilities provide functionality necessary to implement Service SAFs:

Memory Management

Memory management routines provide fast, platform-independent versions of the standard memory management routines. They also prevent memory leaks by allocating from a temporary memory (called “pooled” memory) for each request, and then disposing the entire pool after each request. There are wrappers for standard memory routines for using permanent memory. To disable pooled memory for debugging, see the built-in SAF pool-init in Chapter 2, SAFs in the magnus.conf File

File I/O

The file I/O functions provide platform-independent, thread-safe file I/O routines.

Network I/O

Network I/O functions provide platform-independent, thread-safe network I/O routines. These routines work with SSL when it’s enabled.


Thread functions include functions for creating your own threads that are compatible with the server’s threads. There are also routines for critical sections and condition variables.


Utility functions include platform-independent, thread-safe versions of many standard library functions (such as string manipulation), as well as new utilities useful for NSAPI.

Note –

You cannot use an embedded null in a string, because NSAPI functions assume that a null is the end of the string. Therefore, passing unicode-encoded content through an NSAPI plug-in doesn’t work.

Virtual Server

The virtual server functions provide routines for retrieving information about virtual servers.