The sem_grab function requests exclusive access to a specified semaphore. If exclusive access is unavailable, the caller blocks execution until exclusive access becomes available. Use this function to ensure that only one server processor thread performs an action at a time.
#include <base/sem.h> int sem_grab(SEMAPHORE id);
-1 if an error occurred
0 to signal success
SEMAPHORE id is the unique identification number of the requested semaphore.
sem_init, sem_release, sem_terminate, sem_tgrab
The sem_init function creates a semaphore with a specified name and unique identification number. Use this function to allocate a new semaphore that will be used with the functions sem_grab and sem_release. Call sem_init from an init class function to initialize a static or global variable that the other classes will later use.
#include <base/sem.h> SEMAPHORE sem_init(char *name, int number);
The constant SEM_ERROR if an error occurred.
SEMAPHORE *name is the name for the requested semaphore. The file name of the semaphore should be a file accessible to the process.
int number is the unique identification number for the requested semaphore.
sem_grab, sem_release, sem_terminate
The sem_release function releases the process’s exclusive control over a specified semaphore. Use this function to release exclusive control over a semaphore created with the function sem_grab.
#include <base/sem.h> int sem_release(SEMAPHORE id);
-1 if an error occurred
0 if no error occurred
SEMAPHORE id is the unique identification number of the semaphore.
sem_grab, sem_init, sem_terminate
The sem_terminate function deallocates the semaphore specified by id. You can use this function to deallocate a semaphore that was previously allocated with the function sem_init.
#include <base/sem.h> void sem_terminate(SEMAPHORE id);
void
SEMAPHORE id is the unique identification number of the semaphore.
sem_grab, sem_init, sem_release
The sem_tgrab function tests and requests exclusive use of a semaphore. Unlike the similar sem_grab function, if exclusive access is unavailable the caller is not blocked but receives a return value of -1. Use this function to ensure that only one server processor thread performs an action at a time.
#include <base/sem.h> int sem_grab(SEMAPHORE id);
-1 if an error occurred or if exclusive access was not available
0 exclusive access was granted
SEMAPHORE id is the unique identification number of the semaphore.
sem_grab, sem_init, sem_release, sem_terminate
The sendfile filter method is called when the contents of a file are to be sent. Filters that modify or consume outgoing data might 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.
int sendfile(FilterLayer *layer, const sendfiledata *data);
The number of bytes consumed, which may be less than the requested amount if an error occurred.
FilterLayer *layer is the filter layer the filter is installed in.
const sendfiledata *sfd identifies the data to send.
int myfilter_sendfile(FilterLayer *layer, const sendfiledata *sfd) { return net_sendfile(layer->lower, sfd); }
The session_create function creates a new Session structure for the client with a specified socket descriptor and a specified socket address. The function returns a pointer to that structure.
#include <base/session.h> Session *session_create(SYS_NETFD csd, struct sockaddr_in *sac);
A pointer to the new Session structure f one was created.
NULL if no new Session structure was created.
SYS_NETFD csd is the platform-independent socket descriptor.
sockaddr_in *sac is the socket address.
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 the client identification information. The session_dns function does not perform this verification.
This function works only if the DNS directive is enabled in the obj.conf file. For more information, see Sun Java System Web Proxy Server 4.0.5 Configuration File Reference.
char *session_dns(Session *sn);
A string containing the host name, or NULL if the DNS name cannot be found for the IP address.
Session *sn identifies the Session structure.
The Session is the same as the Session structure passed to your SAF.
The session_free function frees a specified Session structure. The session_free function does not close the client socket descriptor associated with the Session structure.
#include <base/session.h> void session_free(Session *sn);
void
session_create, session_maxdns
Session *sn is the Session structure to be freed.
The session_maxdns 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_maxdns to change the numeric IP address into more readable format.
This function works only if the DNS directive is enabled in the obj.conf file. For more information, see Sun Java System Web Proxy Server 4.0.5 Configuration File Reference.
char *session_maxdns(Session *sn);
A string containing the host name, or NULL if the DNS name cannot be found for the IP address.
Session *sn identifies the Session structure.
The Session is the same as the Session structure passed to your SAF.
The shexp_casecmp function validates a specified shell expression and compares it with a specified string. The function returns one of three possible values representing match, no match, and invalid comparison. This comparison, in contrast to that of the shexp_cmp function, is not case sensitive.
Use this function if you have a shell expression like *.netscape.com and you want to make sure that a string matches it, such as foo.netscape.com.
int shexp_casecmp(char *str, char *exp);
0 if a match was found.
1 if no match was found.
-1 if the comparison resulted in an invalid expression.
char *str is the string to be compared.
char *exp is the shell expression (wildcard pattern) to compare against.
shexp_cmp, shexp_match, shexp_valid
The shexp_casecmp function validates a specified shell expression and compares the expression with a specified string. The function returns one of three possible values representing match, no match, and invalid comparison. This comparison, in contrast to the comparison made by the shexp_casecmp function, is case sensitive.
Use this function if you have a shell expression like *.netscape.com and you want to make sure that a string matches it, such as foo.netscape.com.
int shexp_cmp(char *str, char *exp);
0 if a match was found.
1 if no match was found.
-1 if the comparison resulted in an invalid expression.
char *str is the string to be compared.
char *exp is the shell expression (wildcard pattern) to compare against.
/* 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 */
shexp_casecmp, shexp_match, shexp_valid
The shexp_match function compares a specified prevalidated shell expression against a specified string. The function returns one of three possible values representing match, no match, and invalid comparison. This comparison, in contrast to the comparison made by the shexp_casecmp function, is case sensitive.
The shexp_match function doesn’t perform validation of the shell expression. The function assumes shexp_valid have already been called .
Use this function if you have a shell expression such as *.netscape.com and you want to make sure that a string matches it, such as foo.netscape.com.
int shexp_match(char *str, char *exp);
0 if a match was found.
1 if no match was found.
-1 if the comparison resulted in an invalid expression.
char *str is the string to be compared.
char *exp is the prevalidated shell expression (wildcard pattern) to compare against.
shexp_casecmp, shexp_cmp, shexp_valid
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.
int shexp_valid(char *exp);
The constant NON_SXP if exp is a standard string.
The constant INVALID_SXP if exp is a shell expression but is invalid.
The constant VALID_SXP if exp is a valid shell expression.
char *exp is the shell expression (wildcard pattern) to be validated.
shexp_casecmp, shexp_match, shexp_cmp
The shmem_alloc function allocates a region of shared memory of the given size, using the given name to avoid conflicts between multiple regions in the program. The size of the region will not be automatically increased if its boundaries are overrun. Use the shmem_realloc function for that automatic increases.
This function must be called before any daemon workers are spawned in order for the handle to the shared region to be inherited by the children.
Because the region must be inherited by the children, the region cannot be reallocated with a larger size when necessary.
#include <base/shmem.h> shmem_s *shmem_alloc(char *name, int size, int expose);
A pointer to a new shared memory region.
char *name is the name for the region of shared memory being created. The value of name must be unique to the program that calls the shmem_alloc() function or conflicts will occur.
int size is the number of characters of memory to be allocated for the shared memory.
int expose is either zero or nonzero. If nonzero, then on systems that support it, the file that is used to create the shared memory becomes visible to other processes running on the system.
The shmem_free function deallocates (frees) the specified region of memory.
#include <base/shmem.h> void *shmem_free(shmem_s *region);
void
shmem_s *region is a shared memory region to be released.
The STRDUP macro is a platform-independent substitute for the C library routine strdup. It creates a new copy of a string in the request’s memory pool.
The STRDUP routine is functionally equivalent to:
newstr = (char *) MALLOC(strlen(str) + 1); strcpy(newstr, str); |
A string created with STRDUP should be disposed with FREE.
char *STRDUP(char *ptr);
A pointer to the new string.
char *ptr is a pointer to a string.
char *name1 = "MyName";char *name2 = STRDUP(name1);
MALLOC, FREE, CALLOC, REALLOC, PERM_MALLOC, PERM_FREE, PERM_CALLOC, PERM_REALLOC, PERM_STRDUP
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.
char *system_errmsg(int param1);
A string containing the text of the latest error message that resulted from a system call. Do not FREE this string.
int param1 is reserved, and should always have the value 0.
system_fopenRO, system_fopenRW, system_fopenWA, system_lseek, system_fread, system_fwrite, system_fwrite_atomic, system_flock, system_ulock, system_fclose
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.
int system_fclose(SYS_FILE fd);
0 if the close succeeded, or IO_ERROR if the close failed.
SYS_FILE fd is the platform-independent file descriptor.
SYS_FILE logfd; system_fclose(logfd);
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA, system_lseek, system_fread, system_fwrite, system_fwrite_atomic, system_flock, system_ulock
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.
int system_flock(SYS_FILE fd);
Returns IO_OKAY if the lock succeeded, or IO_ERROR if the lock failed.
SYS_FILE fd is the platform-independent file descriptor.
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA, system_lseek, system_fread, system_fwrite, system_fwrite_atomic, system_ulock, system_fclose
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.
SYS_FILE system_fopenRO(char *path);
The system-independent file descriptor (SYS_FILE) if the open succeeded, or 0 if the open failed.
char *path is the file name.
system_errmsg, system_fopenRO, system_fopenWA, system_lseek, system_fread, system_fwrite, system_fwrite_atomic, system_flock, system_ulock, system_fclose
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 will be read from and written to by your program.
SYS_FILE system_fopenRW(char *path);
The system-independent file descriptor (SYS_FILE) if the open succeeded, or 0 if the open failed.
char *path is the file name.
SYS_FILE fd;fd = system_fopenRO(pathname);if (fd == SYS_ERROR_FD) break;
system_errmsg, system_fopenRO, system_fopenWA, system_lseek, system_fread, system_fwrite, system_fwrite_atomic, system_flock, system_ulock, system_fclose
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.
SYS_FILE system_fopenWA(char *path);
The system-independent file descriptor (SYS_FILE) if the open succeeded, or 0 if the open failed.
char *path is the file name.
system_errmsg, system_fopenRO, system_fopenRW, system_lseek, system_fread, system_fwrite, system_fwrite_atomic, system_flock, system_ulock, system_fclose
The system_fread function reads a specified number of bytes from a specified file into a specified buffer. It 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.
int system_fread(SYS_FILE fd, char *buf, int sz);
The number of bytes read, which might be less than the requested size if an error occurred or the end of the file was reached before that number of characters were obtained.
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.
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA, system_lseek, system_fwrite, system_fwrite_atomic, system_flock, system_ulock, system_fclose
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.
int system_fwrite(SYS_FILE fd, char *buf, int sz);
Returns IO_OKAY if the write succeeded, or IO_ERROR if the write failed.
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.
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA, system_lseek, system_fread, system_fwrite_atomic, system_flock, system_ulock, system_fclose
The system_fwrite_atomic function writes a specified number of bytes from a specified buffer into a specified file. The function also locks the file prior to performing the write, and then unlocks it when done. This process avoids 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.
int system_fwrite_atomic(SYS_FILE fd, char *buf, int sz);
Returns IO_OKAY if the write/lock succeeded, or IO_ERROR if the write/lock failed.
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.
SYS_FILE logfd;char *logmsg = "An error occurred."; system_fwrite_atomic(logfd, logmsg, strlen(logmsg));
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA, system_lseek, system_fread, system_fwrite, system_flock, system_ulock, system_fclose
The system_gmtime function is a thread-safe version of the standard gmtime function. It returns the current time adjusted to Greenwich Mean Time.
struct tm *system_gmtime(const time_t *tp, const struct tm *res);
A pointer to a calendar time (tm) structure containing the GMT time. Depending on your system, the pointer may point to the data item represented by the second parameter, or it may point to a statically allocated item. For portability, do not assume either situation.
time_t *tp is an arithmetic time.
tm *res is a pointer to a calendar time (tm) structure.
time_t tp;struct tm res, *resp;tp = time(NULL); resp = system_gmtime(&tp, &res);
system_localtime, util_strftime
The system_localtime function is a thread-safe version of the standard localtime function. It returns the current time in the local time zone.
struct tm *system_localtime(const time_t *tp, const struct tm *res);
A pointer to a calendar time (tm) structure containing the local time. Depending on your system, the pointer may point to the data item represented by the second parameter, or it may point to a statically allocated item. For portability, do not assume either situation.
time_t *tp is an arithmetic time.
tm *res is a pointer to a calendar time (tm) structure.
The system_lseek function sets the file position of a file. This function affects where data from system_fread or system_fwrite is read or written.
int system_lseek(SYS_FILE fd, int offset, int whence);
The offset, in bytes, of the new position from the beginning of the file if the operation succeeded, or -1 if the operation failed.
SYS_FILE fd is the platform-independent file descriptor.
int offset is a number of bytes relative to whence. It may be negative.
int whence is one of the following constants:
SEEK_SET, from the beginning of the file.
SEEK_CUR, from the current file position.
SEEK_END, from the end of the file.
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA, system_fread, system_fwrite, system_fwrite_atomic, system_flock, system_ulock, system_fclose
The system_rename function renames a file. This function might not work on directories if the old and new directories are on different file systems.
int system_rename(char *old, char *new);
0 if the operation succeeded, or -1 if the operation failed.
char *old is the old name of the file.
char *new is the new name for the file.
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.
int system_ulock(SYS_FILE fd);
Returns IO_OKAY if the operation succeeded, or IO_ERROR if the operation failed.
SYS_FILE fd is the platform-independent file descriptor.
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA, system_fread, system_fwrite, system_fwrite_atomic, system_flock, system_fclose
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA, system_fread, system_fwrite, system_fwrite_atomic, system_flock, system_fclose
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 using 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 does nothing, but may be called for portability.
char *system_unix2local(char *path, char *lp);
A pointer to the local file system path string.
char *path is the UNIX-style path name to be converted.
char *lp is the local path name.
You must allocate the parameter lp. The parameter must contain enough space to hold the local path name.
system_fclose, system_flock, system_fopenRO, system_fopenRW, system_fopenWA, system_fwrite
The systhread_attach function converts an existing thread into a platform-independent thread.
SYS_THREAD systhread_attach(void);
A SYS_THREAD pointer to the platform-independent thread.
none
systhread_current, systhread_getdata, systhread_init, systhread_newkey, systhread_setdata, systhread_sleep, systhread_start, systhread_timerset
The systhread_current function returns a pointer to the current thread.
SYS_THREAD systhread_current(void);
A SYS_THREAD pointer to the current thread.
none
systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep, systhread_start, systhread_timerset
The systhread_getdata function gets data that is associated with a specified key in the current thread.
void *systhread_getdata(int key);
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. Returns NULL if the call did not succeed; for example, if the systhread_setkey function was never called with the specified key during this session.
int key is the value associated with the stored data by a systhread_setdata function. Keys are assigned by the systhread_newkey function.
systhread_current, systhread_newkey, systhread_setdata, systhread_sleep, systhread_start, systhread_timerset
The systhread_init function initializes the threading system.
#include <base/systhr.h> void systhread_init(char *name);
void
char *name is a name to be assigned to the program for debugging purposes.
systhread_attach, systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep,systhread_start, systhread_terminate, systhread_ timerset
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.
int systhread_newkey(void);
An integer key.
none
systhread_current, systhread_getdata, systhread_setdata, systhread_sleep, systhread_start, systhread_timerset
The systhread_setdata function associates data with a specified key number for the current thread. Keys are assigned by the systhread_newkey function.
void systhread_setdata(int key, void *data);
void
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.
systhread_current, systhread_getdata, systhread_newkey, systhread_sleep, systhread_start, systhread_timerset
The systhread_sleep function puts the calling thread to sleep for a given time.
void systhread_sleep(int milliseconds);
void
int milliseconds is the number of milliseconds the thread is to sleep.
systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_start, systhread_timerset
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.
SYS_THREAD systhread_start(int prio, int stksz, void (*fn)(void *), void *arg);
A new SYS_THREAD pointer if the call succeeded, or SYS_THREAD_ERROR if the call did not succeed.
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.
systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep, systhread_timerset
The systhread_terminate function terminates a specified thread.
#include <base/systhr.h> void systhread_terminate(SYS_THREAD thr);
void
SYS_THREAD thr is the thread to terminate.
systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep, systhread_start, systhread_timerset
The systhread_timerset function starts or resets the interrupt timer interval for a thread system.
Because most systems don’t allow the timer interval to be changed, this function should be considered a suggestion rather than a command.
void systhread_timerset(int usec);
void
int usec is the time, in microseconds
systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep, systhread_start