Sun Java System Web Server 7.0 Update 3 NSAPI Developer's Guide

S

sendfile() Function

The sendfile filter method is called when the contents of a file are to be sent. Filters that modify or consume outgoing data can choose to implement the sendfile filter method.

If a filter implements the write filter method but not the sendfile filter method, the server will automatically translate net_sendfile() calls to net_write() calls. As a result, filters interested in the outgoing data stream do not need to implement the sendfile filter method. However, for performance reasons, filters that implement the write filter method should also implement the sendfile filter method.

Syntax

int sendfile(FilterLayer *layer, const sendfiledata *data);

Return Values

The number of bytes consumed, which might be less than the requested amount if an error occurred.

Parameters

FilterLayer *layer is the filter layer in which the filter is installed.

const sendfiledata *sfd identifies the data to send.

Example

int myfilter_sendfile(FilterLayer *layer, const sendfiledata *sfd)
{
    return net_sendfile(layer->lower, sfd);
}

See Also

net_sendfile() Function, filter_create() Function

session_dns() Function

The session_dns function resolves the IP address of the client associated with a specified session into its DNS name. The function returns a newly allocated string. You can use session_dns to change the numeric IP address into something more readable.

The session_maxdns function verifies that the client matches its claimed identity. The session_dns function does not perform this verification.


Note –

This function works only if the DNS directive is enabled in the magnus.conf file. For more information, see Appendix B, Alphabetical List of NSAPI Functions and Macros.


Syntax

char *session_dns(Session *sn);

Return Values

A string containing the host name, or NULL if the DNS name cannot be found for the IP address.

Parameters

Session *sn is the session.

The Session is the same parameter as the one passed to your SAF.

session_maxdns() Function

The session_maxdns function resolves the IP address of the client associated with a specified session into its DNS name. This function returns a newly allocated string. You can use session_maxdns to change the numeric IP address into something more readable.


Note –

This function works only if the DNS directive is enabled in the magnus.conf file. For more information, see Appendix B, Alphabetical List of NSAPI Functions and Macros.


Syntax

char *session_maxdns(Session *sn);

Return Values

A string containing the host name, or NULL if the DNS name cannot be found for the IP address.

Parameters

Session *sn is the Session.

The Session is the same parameter as the one passed to your SAF.

shexp_casecmp() Function

The shexp_casecmp function validates a specified shell expression and compares it with a specified string. This function returns one of three possible values representing match, no match, and invalid comparison. The comparison, in contrast to the comparison made by the shexp_cmp function is not case sensitive.

Use this function if you have a shell expression like *.netscape.com and make sure that a string matches it, such as foo.netscape.com.

Syntax

int shexp_casecmp(char *str, char *exp);

Return Values

0 if a match was found.

1 if no match was found.

-1 if the comparison resulted in an invalid expression.

Parameters

char *str is the string to be compared.

char *exp is the shell expression (wildcard pattern) to compare against.

See Also

shexp_cmp() Function, shexp_match() Function, shexp_valid() Function

shexp_cmp() Function

The shexp_cmp function validates a specified shell expression and compares it with a specified string. This returns one of three possible values representing match, no match, and invalid comparison. The comparison in contrast to the comparison made by the shexp_casecmp function is case sensitive.

Use this function for a shell expression like *.netscape.com and make sure that a string matches it, such as foo.netscape.com.

Syntax

int shexp_cmp(char *str, char *exp);

Return Values

0 if a match was found.

1 if no match was found.

-1 if the comparison resulted in an invalid expression.

Parameters

char *str is the string to be compared.

char *exp is the shell expression (wildcard pattern) to compare against.

Example

/* Use wildcard match to see if this path is one we want */
char *path;
char *match = "/usr/netscape/*";
if (shexp_cmp(path, match) != 0)    
    return REQ_NOACTION;   /* no match */

See Also

shexp_casecmp() Function, shexp_match() Function, shexp_valid() Function

shexp_match() Function

The shexp_match function compares a specified pre-validated shell expression against a specified string. This function returns one of three possible values representing match, no match, and invalid comparison. The comparison in contrast to the contrast made by the shexp_casecmp function is case sensitive.

The shexp_match function does not perform validation of the shell expression. To perform validation, use shexp_valid().

Use this function for a shell expression such as *.netscape.com, and make sure that a string matches it, such as foo.netscape.com.

Syntax

int shexp_match(char *str, char *exp);

Return Values

0 if a match was found.

1 if no match was found.

-1 if the comparison resulted in an invalid expression.

Parameters

char *str is the string to be compared.

char *exp is the prevalidated shell expression (wildcard pattern) to compare against.

See Also

shexp_casecmp() Function, shexp_cmp() Function, shexp_valid() Function

shexp_valid() Function

The shexp_valid function validates a specified shell expression named by exp. Use this function to validate a shell expression before using the function shexp_match to compare the expression with a string.

Syntax

int shexp_valid(char *exp);

Return Values

The constant NON_SXP if exp is a standard string.

The constant INVALID_SXP if exp is an invalid shell expression.

The constant VALID_SXP if exp is a valid shell expression.

Parameters

char *exp is the shell expression (wildcard pattern) to be validated.

See Also

shexp_casecmp() Function, shexp_match() Function, shexp_cmp() Function

STRDUP() Macro

The STRDUP macro is a platform-independent substitute for the C library routine strdup. This macro creates a new copy of a string in the request’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 the current request. If pooled memory has been disabled in the configuration file with the built-in pool-init SAF, PERM_STRDUP and STRDUP both obtain their memory from the system heap. However, because the memory allocated by STRDUP is automatically freed, do not share this memory between threads.

The STRDUP routine is functionally equivalent to:


newstr = (char *) MALLOC(strlen(str) + 1);
strcpy(newstr, str);

         

Syntax

char *STRDUP(char *ptr);

Return Values

A pointer to the new string.

Parameters

char *ptr is a pointer to a string.

Example

char *name1 = "MyName";
char *name2 = STRDUP(name1);

See Also

CALLOC() Macro,MALLOC() Macro, FREE() Macro, REALLOC() Macro, PERM_STRDUP() Macro

system_errmsg() Function

The system_errmsg function returns the last error that occurred from the most recent system call. This function is implemented as a macro that returns an entry from the global array sys_errlist. Use this macro to help with I/O error diagnostics.

Syntax

char *system_errmsg(int param1);

Return Values

A string containing the text of the latest error message that resulted from a system call. Do not FREE this string.

Parameters

int param1 is reserved, and should always have the value 0.

See Also

system_fopenRO() Function, system_fopenRW() Function, system_fopenWA() Function, system_lseek() Function, system_fread() Function, system_fwrite() Function, system_fwrite_atomic() Function, system_flock() Function, system_ulock() Function, system_fclose() Function

system_fclose() Function

The system_fclose function closes a specified file descriptor. The system_fclose function must be called for every file descriptor opened by any of the system_fopen functions.

Syntax

int system_fclose(SYS_FILE fd);

Return Values

0 if the close succeeds, or the constant IO_ERROR if the close fails.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

Example

SYS_FILE logfd; 
system_fclose(logfd);

See Also

system_errmsg() Function, system_fopenRO() Function, system_fopenRW() Function, system_fopenWA() Function, system_lseek() Function, system_fread() Function, system_fwrite() Function, system_fwrite_atomic() Function, system_flock() Function, system_ulock() Function

system_flock() Function

The system_flock function locks the specified file against interference from other processes. Use system_flock if you do not want other processes to use the file you currently have open. Overusing file locking can cause performance degradation and possibly lead to deadlocks.

Syntax

int system_flock(SYS_FILE fd);

Return Values

The constant IO_OKAY if the lock succeeds, or the constant IO_ERROR if the lock fails.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

See Also

system_errmsg() Function, system_fopenRO() Function, system_fopenRW() Function, system_fopenWA() Function, system_lseek() Function, system_fread() Function, system_fwrite() Function, system_fwrite_atomic() Function, system_ulock() Function, system_fclose() Function

system_fopenRO() Function

The system_fopenRO function opens the file identified by path in read-only mode and returns a valid file descriptor. Use this function to open files that will not be modified by your program. In addition, you can use system_fopenRO to open a new file buffer structure using filebuf_open.

Syntax

SYS_FILE system_fopenRO(char *path);

Return Values

The system-independent file descriptor (SYS_FILE) if the open succeeds, or 0 if the open fails.

Parameters

char *path is the file name.

See Also

system_errmsg() Function, system_fopenRW() Function, system_fopenWA() Function, system_lseek() Function, system_fread() Function, system_fwrite() Function, system_fwrite_atomic() Function, system_flock() Function, system_ulock() Function, system_fclose() Function

system_fopenRW() Function

The system_fopenRW function opens the file identified by path in read-write mode and returns a valid file descriptor. If the file already exists, system_fopenRW does not truncate it. Use this function to open files that can be read and written by your program.

Syntax

SYS_FILE system_fopenRW(char *path);

Return Values

The system-independent file descriptor (SYS_FILE) if the open succeeds, or 0 if the open fails.

Parameters

char *path is the file name.

Example

SYS_FILE fd;
fd = system_fopenRO(pathname);
if (fd == SYS_ERROR_FD)    
break;

See Also

system_errmsg() Function, system_fopenRO() Function, system_fopenWA() Function, system_lseek() Function, system_fread() Function, system_fwrite() Function, system_fwrite_atomic() Function, system_flock() Function, system_ulock() Function, system_fclose() Function

system_fopenWA() Function

The system_fopenWA function opens the file identified by path in write-append mode and returns a valid file descriptor. Use this function to open those files to which your program will append data.

Syntax

SYS_FILE system_fopenWA(char *path);

Return Values

The system-independent file descriptor (SYS_FILE) if the open succeeds, or 0 if the open fails.

Parameters

char *path is the file name.

See Also

system_errmsg() Function, system_fopenRO() Function, system_fopenRW() Function, system_lseek() Function, system_fread() Function, system_fwrite() Function, system_fwrite_atomic() Function, system_flock() Function, system_ulock() Function, system_fclose() Function

system_fread() Function

The system_fread function reads a specified number of bytes from a specified file into a specified buffer. This function returns the number of bytes read. Before system_fread can be used, you must open the file using any of the system_fopen functions except system_fopenWA.

Syntax

int system_fread(SYS_FILE fd, char *buf, int sz);

Return Values

The number of bytes read, which might be less than the requested size if an error occurs, or if the end of the file was reached before that number of characters were obtained.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

char *buf is the buffer to receive the bytes.

int sz is the number of bytes to read.

See Also

system_errmsg() Function, system_fopenRO() Function, system_fopenRW() Function, system_fopenWA() Function, system_lseek() Function, system_fwrite() Function, system_fwrite_atomic() Function, system_flock() Function, system_ulock() Function, system_fclose() Function

system_fwrite() Function

The system_fwrite function writes a specified number of bytes from a specified buffer into a specified file.

Before system_fwrite can be used, you must open the file using any of the system_fopen functions except system_fopenRO.

Syntax

int system_fwrite(SYS_FILE fd, char *buf, int sz);

Return Values

The constant IO_OKAY if the write succeeds, or the constant IO_ERROR if the write fails.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

char *buf is the buffer containing the bytes to be written.

int sz is the number of bytes to write to the file.

See Also

system_errmsg() Function, system_fopenRO() Function, system_fopenRW() Function, system_fopenWA() Function, system_lseek() Function, system_fread() Function, system_fwrite() Function, system_fwrite_atomic() Function, system_flock() Function, system_ulock() Function, system_fclose() Function

system_fwrite_atomic() Function

The system_fwrite_atomic function writes a specified number of bytes from a specified buffer into a specified file. This function also locks the file prior to performing the write, and then unlocks it when done, thereby avoiding interference between simultaneous write actions. Before system_fwrite_atomic can be used, you must open the file using any of the system_fopen functions except system_fopenRO.

Syntax

int system_fwrite_atomic(SYS_FILE fd, char *buf, int sz);

Return Values

The constant IO_OKAY if the write/lock succeeds, or the constant IO_ERROR if the write/lock fails.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

char *buf is the buffer containing the bytes to be written.

int sz is the number of bytes to write to the file.

Example

SYS_FILE logfd;
char *logmsg = "An error occurred.";
system_fwrite_atomic(logfd, logmsg, strlen(logmsg));

See Also

system_errmsg() Function, system_fopenRO() Function, system_fopenRW() Function, system_fopenWA() Function, system_lseek() Function, system_fread() Function, system_fwrite() Function, system_flock() Function, system_ulock() Function, system_fclose() Function

system_gmtime() Function

The system_gmtime function is a thread-safe version of the standard gmtime function. This function returns the current time adjusted to Greenwich Mean Time.

Syntax

struct tm *system_gmtime(const time_t *tp, const struct tm *res);

Return Values

A pointer to a calendar time (tm) structure containing the GMT time. Depending on your system, the pointer might point to the data item represented by the second parameter, or the pointer might point to a statically allocated item. For portability, do not assume either situation.

Parameters

time_t *tp is an arithmetic time.

tm *res is a pointer to a calendar time (tm) structure.

Example

time_t tp;
struct tm res, *resp;
tp = time(NULL);
resp = system_gmtime(&tp, &res);

See Also

system_localtime() Function, util_strftime() Function

system_localtime() Function

The system_localtime function is a thread-safe version of the standard localtime function. This function returns the current time in the local time zone.

Syntax

struct tm *system_localtime(const time_t *tp, const struct tm *res);

Return Values

A pointer to a calendar time (tm) structure containing the local time. Depending on your system, the pointer might point to the data item represented by the second parameter, or the pointer might point to a statically allocated item. For portability, do not assume either situation.

Parameters

time_t *tp is an arithmetic time.

tm *res is a pointer to a calendar time (tm) structure.

See Also

system_gmtime() Function, util_strftime() Function

system_lseek() Function

The system_lseek function sets the file position of a file. This position affects where data from system_fread or system_fwrite is read or written.

Syntax

int system_lseek(SYS_FILE fd, int offset, int whence);

Return Values

The offset, in bytes, of the new position from the beginning of the file if the operation succeeds, or -1 if the operation fails.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

int offset is a number of bytes relative to whence. This value may be negative.

int whence is one of the following constants:

See Also

system_errmsg() Function, system_fopenRO() Function, system_fopenRW() Function, system_fopenWA() Function, system_fread() Function, system_fwrite() Function, system_fwrite_atomic() Function, system_flock() Function, system_ulock() Function, system_fclose() Function

system_rename() Function

The system_rename function renames a file. This function does not work on directories if the old and new directories are on different file systems.

Syntax

int system_rename(char *old, char *new);

Return Values

0 if the operation succeeds, or -1 if the operation fails.

Parameters

char *old is the old name of the file.

char *new is the new name for the file.

system_ulock() Function

The system_ulock function unlocks the specified file that has been locked by the function system_lock. For more information about locking, see system_flock() Function.

Syntax

int system_ulock(SYS_FILE fd);

Return Values

The constant IO_OKAY if the operation succeeds, or the constant IO_ERROR if the operation fails.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

See Also

system_errmsg() Function, system_fopenRO() Function, system_fopenRW() Function, system_fopenWA() Function, system_fread() Function, system_fwrite() Function, system_fwrite_atomic() Function, system_flock() Function, system_fclose() Function

system_unix2local() Function

The system_unix2local function converts a specified UNIX-style path name to a local file system path name. Use this function when you have a file name in the UNIX format such as one containing forward slashes, and you need to access a file on another system such as Windows. You can use system_unix2local to convert the UNIX file name into the format that Windows accepts. In the UNIX environment this function has no effect, but can be called for portability.

Syntax

char *system_unix2local(char *path, char *lp);

Return Values

A pointer to the local file system path string.

Parameters

char *path is the UNIX-style path name to be converted.

char *lp is the local path name.

You must allocate the parameter lp, which must contain enough space to hold the local path name.

See Also

system_fclose() Function, system_flock() Function, system_fopenRO() Function, system_fopenRW() Function, system_fopenWA() Function, system_fwrite() Function

systhread_attach() Function

The systhread_attach function makes an existing thread into a platform-independent thread.

Syntax

SYS_THREAD systhread_attach(void);

Return Values

A SYS_THREAD pointer to the platform-independent thread.

Parameters

None

See Also

systhread_current() Function, systhread_getdata() Function, systhread_newkey() Function, systhread_setdata() Function, systhread_sleep() Function, systhread_start() Function, systhread_timerset() Function

systhread_current() Function

The systhread_current function returns a pointer to the current thread.

Syntax

SYS_THREAD systhread_current(void);

Return Values

A SYS_THREAD pointer to the current thread.

Parameters

None

See Also

systhread_getdata() Function, systhread_newkey() Function, systhread_setdata() Function, systhread_sleep() Function, systhread_start() Function, systhread_timerset() Function

systhread_getdata() Function

The systhread_getdata function gets data that is associated with a specified key in the current thread.

Syntax

void *systhread_getdata(int key);

Return Values

A pointer to the data that was earlier used with the systhread_setkey function from the current thread, using the same value of key if the call succeeds. Return Values NULL if the call does not succeed, for example, if the systhread_setkey function was never called with the specified key during this session.

Parameters

int key is the value associated with the stored data by a systhread_setdata function. Keys are assigned by the systhread_newkey function.

See Also

systhread_current() Function, systhread_newkey() Function, systhread_setdata() Function, systhread_sleep() Function, systhread_start() Function, systhread_timerset() Function

systhread_newkey() Function

The systhread_newkey function allocates a new integer key (identifier) for thread-private data. Use this key to identify a variable that you want to localize to the current thread, then use the systhread_setdata function to associate a value with the key.

Syntax

int systhread_newkey(void);

Return Values

An integer key.

Parameters

None

See Also

systhread_current() Function, systhread_getdata() Function, systhread_setdata() Function, systhread_sleep() Function, systhread_start() Function, systhread_timerset() Function

systhread_setdata() Function

The systhread_setdata function associates data with a specified key number for the current thread. Keys are assigned by the systhread_newkey function.

Syntax

void systhread_setdata(int key, void *data);

Return Values

void

Parameters

int key is the priority of the thread.

void *data is the pointer to the string of data to be associated with the value of key.

See Also

systhread_current() Function, systhread_getdata() Function, systhread_newkey() Function, systhread_sleep() Function, systhread_start() Function, systhread_timerset() Function

systhread_sleep() Function

The systhread_sleep function puts the calling thread to sleep for a given time.

Syntax

void systhread_sleep(int milliseconds);

Return Values

void

Parameters

int milliseconds is the number of milliseconds the thread is to sleep.

See Also

systhread_current() Function, systhread_getdata() Function, systhread_newkey() Function, systhread_setdata() Function, systhread_start() Function, systhread_timerset() Function

systhread_start() Function

The systhread_start function creates a thread with the given priority, allocates a stack of a specified number of bytes, and calls a specified function with a specified argument.

Syntax

SYS_THREAD systhread_start(int prio, int stksz, void (*fn)(void *), void *arg);

Return Values

A new SYS_THREAD pointer if the call succeeds, or the constant SYS_THREAD_ERROR if the call does not succeed.

Parameters

int prio is the priority of the thread. Priorities are system-dependent.

int stksz is the stack size in bytes. If stksz is zero (0), the function allocates a default size.

void (*fn)(void *) is the function to call.

void *arg is the argument for the fn function.

See Also

systhread_current() Function, systhread_getdata() Function, systhread_newkey() Function, systhread_setdata() Function, systhread_sleep() Function, systhread_timerset() Function

systhread_timerset() Function

The systhread_timerset function starts or resets the interrupt timer interval for a thread system.


Note –

Because most systems do not allow the timer interval to be changed, this function should be considered a suggestion rather than a command.


Syntax

void systhread_timerset(int usec);

Return Values

void

Parameters

int usec is the time in microseconds

See Also

systhread_current() Function, systhread_getdata() Function, systhread_newkey() Function, systhread_setdata() Function, systhread_sleep() Function, systhread_start() Function