FILE NAME $RCSfile: reference.manual,v $ $Revision: 1.5 $ $Date: 2003/03/24 05:11:22 $ PROGRAM INFORMATION Developed by: libcsc project Developer: Douglas R. Jerome, drj, FILE DESCRIPTION Reference manual for libcsc version 0.8X.X. CHANGE LOG 06nov02 drj Replaced text for CSClistPop() and CSClistNodeNext()/ 12may02 drj Changed libcsc version in title from 0.81.0 to 0.8X.X. 02may02 drj Added file header. Fixed libcsc version in title. REFERENCE MANUAL for LIBCSC VERSION 0.8X.X Programming with libcsc Copyright (c) 2002 Douglas R. Jerome Peoria, Arizona USA Douglas Jerome ------------ djerome@users.sourceforge.net jerome@globalcrossing.net --------------------------------------------------------------------- Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". --------------------------------------------------------------------- ------------------------------------------------ Table of Contents Paragraph Page 1.0 SCOPE .................................................................. X 2.0 OVERVIEW ............................................................... X 3.0 SUBSYSTEMS ............................................................. X Appendices A SUBSYSTEM REFERENCE ...................................................... X B FUNCTION REFERENCE ....................................................... X C LICENSE .................................................................. X ------------------------------------------------ ===== 1.0 SCOPE ===== -------------- 1.1 Identification -------------- This document is the reference manual for the C language programming library named "libcsc". See the title page of this document for the exact date and revision of this document and applicable version of libcsc. --------------- 1.2 System Overview --------------- libcsc is a library of C functions implementing several general purpose programming abstractions e.g., balanced binary tree, hash table, list, etc. Much of libcsc is appropriate for use in embedded systems. libcsc is distributed under the GNU Library Public License and is freely available at: o http://hackerlabs.sourceforge.net o ftp://hackerlabs.sourceforge.net/pub/hackerlabs Here is a sample command line ftp session, fetching a version of libcsc. % ftp hackerlabs.sourceforge.net Connected to hackerlabs.sourceforge.net. 220 orbital.i.sourceforge.net FTP server (Version wu-2.5.0(1) Tue Sep 21 16:48:12 EDT 1999) ready. Name (hackerlabs.sourceforge.net:jerome): anonymous 331 Guest login ok, send your complete e-mail address as password. Password: djerome@users.sourceforge.net 230- 230- 230-****************************************************** 230-* Welcome to ftp.sourceforge.net * 230-****************************************************** 230- 230-If you find that this server is slow please try our 230-much faster httpd server @ http://sourceforge.net 230- 230- 230- 230- 230 Guest login ok, access restrictions apply. Remote system type is UNIX. Using binary mode to transfer files. ftp> cd pub/hackerlabs 250 CWD command successful. ftp> get libcsc-0.4.2.tar.gz local: libcsc-0.4.2.tar.gz remote: libcsc-0.4.2.tar.gz 200 PORT command successful. 150 Opening BINARY mode data connection for libcsc-0.4.2.tar.gz (114895 bytes). 226 Transfer complete. 114895 bytes received in 24.8 secs (4.5 Kbytes/sec) ftp> quit 221-You have transferred 114895 bytes in 1 files. 221-Total traffic for this session was 117273 bytes in 2 transfers. 221-Thank you for using the FTP service on orbital.i.sourceforge.net. 221 Goodbye. % The file is a compressed tar (tape archive) file. To extract the files, once you have the compressed archive, type: % gunzip -c libcsc-0.4.2.tar.gz | tar xf - LIBCSC IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. THERE ARE NO REPRESENTATIONS ABOUT THE SUITABILITY OF THIS SOFTWARE FOR ANY PURPOSE. DOUGLAS R. JEROME SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY THE USERS OF THIS SOFTWARE. ----------------- 1.3 Document Overview ----------------- Chapter 1.0 _SCOPE_ describes this document, introduces what libcsc is and the logistics of finding and downloading libcsc. Chapter 2.0 _OVERVIEW_ describes concepts and structure implementing libcsc. Chapter 3.0 _SUBSYSTEMS_ provides a list of the libcsc software subsystems. Appendix A _SUBSYSTEM REFERENCE_ provides a an overview description of each libcsc software subsystem. Appendix B _FUNCTION REFERENCE_ is a detailed description of each function in libcsc. Appendix C _LICENSE_ is the GNU Free Documentation License, the license under which this document is distributed. --------------- 1.4 libcsc Glossary --------------- API - Application Program Interface This generally refers to the functions and global data comprising an interface to something; in this case, the libcsc subsystems. c-switch - Conditional compilation; implemented with #ifdef or #if. client code - This is the "user" code that includes libcsc header files and makes libcsc function calls. embedded - A computer or software execution environment that is actually a part of something else, like a telephone. There may not be anything like a Unix operating system in there. ISO - International Standards Organization (I think) instrument - Instrumented code is code that has extra debug/trace output. The libcsc source code is instrumented. By defining macros DEBUG and/or TRACE at compile time, extra output is generated by the libcsc code. opaque - A variable type, or data structure, that client code has no internal access. This is usually a void pointer for the client code, and it is passed to susbsystem functions which use and update the internal fields of the data structure/type. STDC - Most people call this "ANSI C". There is an international Standard C ISO standard that is essentially the ANSI standard, probably written in internationalized English. subsystem - A collection of similar functions grouped together in a single .c file, typically implementing an abstract data type such as a hash table. target - Kernel (operating system) for which libcsc is compiled. You do the compilation. TBS - To Be Specified This means someone has been too lazy to document it. ------------------------------------------------ ======== 2.0 OVERVIEW ======== ---------------- 2.1 Software License ---------------- libcsc is copyright (c) 1998 - 2002 by Douglas R. Jerome; the software is protected as an unpublished work under the U.S. Copyright Act of 1976. All rights reserved by Douglas R. Jerome. libcsc is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. libcsc is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with libcsc; see the file COPYRIGHT. If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. I don't really care what you do with the libcsc software; I just want some credit for the work that I've done and ask that something like the following message be included in all derived works: Portions developed by: Douglas R. Jerome --------- 2.2 Structure --------- [ This section is TBS. ] ----- 2.3 Usage ----- DEBUG ----- libcsc can be built with the macro DEBUG defined; it will be on the make command line (specified with -DDEBUG) e.g., make CDEBUGFLAGS=-DDEBUG libcsc source code is heavily c-switched on DEBUG e.g., this code fragment: . . . #ifdef DEBUG if (ptr == NULL) printf ("barf in %s at line %s\n", __FILE__, __LINE__); #endif . . . When you build libcsc, use DEBUG until you know there are no bugs in the client code (or libcsc). It will keep monsters away, your boss will give you a raise, people will love you, and you will be happier in general. assertions ---------- Define DEBUG in your client code and use the libcsc assertion macros, from libcsc_debug.h, everywhere in your client code. return values ------------- As a general rule, libcsc functions return 0 indicating success, and return -1 OR A SMALL POSITIVE NUMBER indicating failure; exceptions are some functions that return a pointer wherein a return value of NULL indicates failure. All return values, excluding pointers, have a symbolic definition, implemented by a #define in the libcsc.h header file. CSCstatStr() is a function that prints a (descriptive) message string associate with these return values. --------------------------- 2.4 Notes on libcsc Compilation --------------------------- libcsc is intended to: BUILD ON BUILD FOR --------------------------------- Linux ................. Linux Solaris ............... Solaris Linux, Solaris ........ vxWorks (cross-compile) embedded cross-compile ---------------------- Most of libcsc is intended to be able to be built for embedded environments. Unfortunately, to cross-compile for vxWorks, you need to make your own makefile for the src directory, name it something like "Makefile.src.embedded", and do something like this: rm Makefile ln -s Makefile.src.embedded Makefile make Not all files will successfully cross-compile. unix compile ------------ Make with Makefile.src.unix; you should be able to simply run make because there should be a symbolic link from Makefile to Makefile.src.unix. make options ------------ RECOMMENDED Always build with DEBUG, until your application/system is debugged. You can control the DEBUG c-switches in the libcsc code; it is conveniently specified on the make command line with the CDEBUGFLAGS macro, like this: make "CDEBUGFLAGS=-DDEBUG" # make with DEBUG To build with debugger information (for use with GDB), or to build with a high level of optimization, one can conveniently use the CC_PARAMS macro on the make command line, like this: make "CC_PARAMS=-g" # for GDB make "CC_PARAMS=-O3" # for optimization These can be mixed: make "CC_PARAMS=-g" "CDEBUGFLAGS=-DDEBUG" # make for GDB and with DEBUG ------------------------ 2.5 Notes on the Source Code ------------------------ libcsc directory structure: directory usage ================== =============== / / doc - documentation / include - .h files / lib - object code / src - .c files / t - example/test client code libcsc is completely written in C. It contains functions implementing general subsystems. Some subsystem are abstract data types, and some subsystems are simply a collection of similar functions. The libcsc code is developed with strict Standard C (ANSI/ISO) compliance enforced by compiler switches. libcsc compilation command lines, in the makefiles, contain Standard C compliance switches. If this is a problem, then spank yourself ask "wtf am I doing with a non-Standard C compilation system?" The csc_sock subsystem in libcsc uses the BSD socket subsystem and won't completely build without it. Without your compilation and runtime system having a BSD socket subsystem you'll probably get a lib/libcsc.a file when you build libcsc, but it won't have the csc_sock subsystem. ------------------------------------------------ 3.0 SUBSYSTEMS ========== Subsystem Overview ------------------ csc_config - libcsc specific checks ................................ libcsc.h csc_file(P) - File Access and Location Subsystem .................... libcsc.h csc_hash - Hash Table Subsystem .................................. libcsc.h csc_io - Miscellaneous I/O Functions ........................... libcsc.h csc_list - List (stack, queue, linked list) Subsystem ............ libcsc.h csc_math - Miscellaneous Math Functions .......................... libcsc.h csc_mem - Dynamically Allocated Memory Subsystem ................ libcsc.h csc_notify - Notification (callback) Subsystem ..................... libcsc.h csc_sock(B) - BSD Network Socket Subsystem .......................... libcsc.h csc_string - Miscellaneous String Functions ........................ libcsc.h csc_symbol - Symbol (individual, not as a table) Subsystem ......... libcsc.h csc_symtab - Symbol Table Subsystem ................................ libcsc.h csc_sys(P) - Miscellaneous System Functions ........................ libcsc.h csc_timer(B) - Timer Subsystem ....................................... libcsc.h csc_tree - Balanced Binary Tree Subsystem ........................ libcsc.h (B) - 4.3+BSD The subsystem names ending with "(B)" make use of 4.3+BSD conventions. These subsystems may not compile for an embedded environment. (P) - POSIX The subsystem names ending with "(P)" make use of unix conventions and POSIX compliance. Don't expect these subsystems to compile for an embedded environment. ================================================================ APPENDICES ================================================================ APPENDIX A SUBSYSTEM REFERENCE =================================== ------------------------------------------------------------------------ csc_config(l) NAME csc_config DESCRIPTION Configuration and General Function Subsystem FUNCTIONS CSCstatStr - get string describing libcsc function return value CSCcflags - get string containing compiler command-line options CSCldflags - get string containing compiler command-line options CSClibs - get string containing compiler command-line options CSCversion - get string containing the libcsc version CSCcredits - get string containing the libcsc credits CSCchkup - check scalar data sizes assumed by libcsc ------------------------------------------------------------------------ csc_file(l) NAME csc_file DESCRIPTION File Subsystem FUNCTIONS CSCfileReadLock - read-lock a region in a file CSCfileWriteLock - write-lock a region in a file CSCfileUnlock - unlock a region in a file CSCfileGetHomeDir - find home directory pathname CSCfileGetUserHomeDir - find home directory pathname of specific user CSCfileBaseName - strip directory from pathname CSCfilePathName - strip last component (file) from pathname CSCfileExpandPath - expand ~ and environment variables in pathname CSCfileOpen - create a file in a path that doesn't (yet) exist ------------------------------------------------------------------------ csc_hash(l) NAME csc_hash DESCRIPTION Hash table Subsystem FUNCTIONS CSChashNew - create a new libcsc hash table CSChashDel - remove a libcsc hash table CSChashStat - query statistics of a libcsc hash table CSChashEntryPut - put an entry into a libcsc hash table CSChashEntryGet - get an item from a libcsc hash table CSChashEntryDel - remove an entry from a libcsc hash table CSChashEntryNext - find next entry in a libcsc hash table CSChashEntryStat - query the fields of a libcsc hash table entry CSChashRead - read an ASCII format libcsc hash table CSChashWrite - write a libcsc hash table in an ASCII format CSChashDump - write a formatted dump of a libcsc hash table ------------------------------------------------------------------------ csc_io(l) NAME csc_io DESCRIPTION I/O Subsystem FUNCTIONS CSCioInfoPrint - formatted write to stdout CSCioWarnPrint - formatted write to stdout CSCioErrorPrint - formatted write to stderr CSCioSoftwareError - print a parameterized software error message CSCioRead - read a specific number of bytes CSCioReadLine - read bytes that are terminated by a newline CSCioBufWrite - write an ASCII buffer CSCioBufRead - read an ASCII buffer ------------------------------------------------------------------------ csc_list(l) NAME csc_list DESCRIPTION List Subsystem The csc library's list subsystem; there are functions for managing arbitrary data in lists. These lists can act like queues, stacks, or just linked lists. FUNCTIONS CSClistNew - create a new libcsc list CSClistDel - remove a libcsc list CSClistRead - read an ASCII format libcsc list CSClistWrite - write a libcsc list in an ASCII format CSClistSetCFunc - set a libcsc list entry data compare function CSClistStat - retrieve libcsc list statistics CSClistPush - create a new entry and push it onto a libcsc list CSClistPop - pop an entry from a libcsc list and retrieve its data CSClistPeek - retrieve data from entry at libcsc list head or tail CSClistNodeNext - find next entry (node) in a libcsc list CSClistNodeFindByValue - find libcsc list entry by data value CSClistNodeFindByReference - find libcsc list entry (node) by reference CSClistNodeStat - retrieve data fields from a libcsc list entry (node) CSClistNodeValidate - verify an entry (node) is really in a libcsc list CSClistNodeDel - remove an entry (node) from a libcsc list ------------------------------------------------------------------------ csc_math(l) NAME csc_math DESCRIPTION Miscellaneous math functions. FUNCTIONS CSC2x - 2 to a the power of x, 0 <= x <= 30 CSCurand - uniform random number generator ------------------------------------------------------------------------ csc_mem(l) NAME csc_mem DESCRIPTION Memory (Dynamic Allocation) Subsystem FUNCTIONS CSCmemInit - initialize a csc memlist for subsequent memory allocations CSCmemDone - cleanup and remove a memList (free all its memory) CSCmemAlloc - allocate memory (and keep thrack of it in memList) CSCmemDup - duplicate (dynamically allocate and copy) memory CSCmemFree - free dynamically allocated memory CSCmemLookup - lookup a memory pointer in memList CSCmemValidate - validate that a memory pointer is in memList CSCmemListFree - free all memory allocated in a memList CSCmemListStat - get information about a memList CSCmemListPrintProfile - write a memlist profile to standard output CSCmemListWriteProfile - write a memlist profile to a file descriptor ------------------------------------------------------------------------ csc_notify(l) NAME csc_notify DESCRIPTION Notification System (callback) Subsystem Create a notification board, add some notifications to it, then regisiter some functions, each with some private data (pointer is useful) on some the the notifications. When a notification is posted, the registered functions will be called, each with their corresponding private data. FUNCTIONS CSCnotificationBoardNew - create a new notification board CSCnotificationBoardDel - completely remove a notification board CSCnotificationBoardPrint - print a notification board in ASCII format CSCnotificationNew - create a new notification in a board CSCnotificationDel - delete a notification from a board CSCnotificationPost - post to a notification in a board CSCnotificationRegister - register client function to a notification ------------------------------------------------------------------------ csc_sock(l) NAME csc_sock DESCRIPTION BSD Network Socket Subsystem FUNCTIONS CSCsockConnectTCP - initiate a socket connection CSCsockConnectUDP - initiate a socket connection CSCsockPassiveTCP - listen for connections on a socket CSCsockPassiveUCP - listen for connections on a socket ------------------------------------------------------------------------ csc_string(l) NAME csc_string DESCRIPTION String Subsystem FUNCTIONS CSCstringOctal - format an ASCII string to represent an octal number CSCstringBinary - format an ASCII string to represent a binary number CSCstringBasename - strip directory from a filename ------------------------------------------------------------------------ csc_symbol(l) NAME csc_symbol DESCRIPTION Symbol Subsystem FUNCTIONS CSCsymbolIntInit - initialize a integer symbol CSCsymbolFloatInit - initialize a floating point symbol CSCsymbolPtrInit - initialize a pointer symbol CSCsymbolIntNew - allocate and initialize a integer symbol CSCsymbolFloatNew - allocate and initialize a floating point symbol CSCsymbolPtrNew - allocate and initialize a pointer symbol CSCsymbolIntDel - delete a integer symbol CSCsymbolFloatDel - delete a floating point symbol CSCsymbolPtrDel - delete a pointer symbol CSCsymbolIntWrite - write a integer symbol in ASCII format CSCsymbolFloatWrite - write a floating point symbol in ASCII format CSCsymbolPtrWrite - write a pointer symbol in ASCII format CSCsymbolDup - dynamically allocate and duplicate a symbol CSCsymbolDel - remove a libcsc symbol table ------------------------------------------------------------------------ csc_symtab(l) NAME csc_symtab DESCRIPTION Symbol Table Subsystem FUNCTIONS CSCsymtabNew - create a new libcsc hash table CSCsymtabDel - remove a libcsc symbol table CSCsymtabStat - retrieve statistics for a libcsc symbol table CSCsymtabEntryPut - add a symbol to a libcsc symbol table CSCsymtabEntryGet - get a symbol in a libcsc symbol table CSCsymtabEntryDel - remove a symbol from a libcsc symbol table CSCsymtabEntryNext - find next entry in a libcsc symbol table ------------------------------------------------------------------------ csc_sys(l) NAME csc_sys DESCRIPTION System Subsystem FUNCTIONS CSCsysLimitsGet - find some system limits CSCsysInstallSignal - fairly portable signal installer CSCsysUsleep - sleep some microseconds ------------------------------------------------------------------------ csc_timer(l) NAME csc_timer DESCRIPTION Timer Subsystem FUNCTIONS CSCtimerInit - create a timer CSCtimerDone - delete a timer CSCtimerClear - clear marks in timer CSCtimerMark - create a mark in a timer CSCtimerStat - create and get current timer's time CSCtimerStat - get current timer's time ------------------------------------------------------------------------ csc_tree(l) NAME csc_tree DESCRIPTION Balanced Binary Tree Subsystem The CSCbinTree functions provide an interface to a balanced binary tree subsystem. The tree is an opaque data type, and client code never has direct access to the nodes. Note that you can't remove nodes, but the tree can be deleted. The CSCbinTreeNode functions provide individual node manipulation capability. Trees can be built with the CSCbinTreeNodeJoin function, which returns a pointer to the upper node. These trees are not likely to be balanced. Don't try mixing the CSCbinTree and CSCbinTreeNode functions on the same tree. FUNCTIONS tree ---- CSCbinTreeNew - create an empty libcsc balanced binary tree CSCbinTreeDel - delete a libcsc balanced binary tree CSCbinTreeInsert - insert a node into a libcsc balanced binary tree CSCbinTreeTagOrderedInsert - put node into libcsc balanced binary tree CSCbinTreeTraverse - traverse a libcsc balanced binary tree CSCbinTreeUserSearch - arbitrary search of libcsc balanced binary tree CSCbinTreeTagSearch - search a balanced binary tree for node with tag CSCbinTreeStat - retrieve libcsc balanced binary tree statistics CSCbinTreePrint - print a libcsc balanced binary tree node ---- CSCbinTreeNodeNew - create a new empty libcsc binary tree node CSCbinTreeNodeDel - deallocate a libcsc binary tree node CSCbinTreeNodeJoin - join libcsc binary tree nodes CSCbinTreeNodeBreak - break libcsc binary tree at a node CSCbinTreeNodeTraverse - traverse a libcsc binary tree CSCbinTreeNodeUserSearch - arbitrary libcsc binary tree traversal CSCbinTreeNodeTagSearch - search a libcsc binary tree for a given tag CSCbinTreeNodeStat - retrieve fields from a libcsc binary tree node CSCbinTreeNodePrint - print the values of a libcsc binary tree node ------------------------------------------------ APPENDIX B FUNCTION REFERENCE ================================== ------------------------------------------------------------------------ CSC2x(3) NAME CSC2x - 2 to a the power of x, 0 <= x <= 30 SYNOPSYS #include "libcsc.h" int CSC2x ( int exponent ); RETURN VALUE DESCRIPTION CSC2x() returns 2 to the power of exponent, unless exponent is less than 0 or greater than 30, in which case CSC2x() returns -1. CSC2x() uses a table, so it is extremly fast. SEE ALSO CSCurand(3) ------------------------------------------------------------------------ CSCbinTreeDel(3) NAME CSCbinTreeDel - delete a libcsc balanced binary tree SYNOPSYS #include "libcsc.h" int CSCbinTreeDel ( CSCbinTreeType const tree, CSCgenFnType cbFn ); RETURN VALUE CSC_OK ......... if successful, and the opaque data structure represented by `tree' will be deallocated. CSC_NOTFOUND ... if not successful. CSC_BADARG ..... if libcsc was compiled with the DEBUG macro and `tree' or `cbFn' is NULL. CSC_CORRUPT .... if libcsc was compiled with the DEBUG macro and CSCbinTreeDel() detects something munged up in the tree or in some internal data. DESCRIPTION CSCbinTreeDel() delete the balanced binary tree and the opaque CSCbinTreeType data structure represented by `tree'. Probably the only way to get a valid CSCbinTreeType data structure in the first place is by calling CSCbinTreeNew(). `cbFn' is a pointer to a libcsc CSCgenFnType function that is called for EACH NODE in the tree, before each node is deallocated. The prototype for CSCgenFnType is: int (*CSCgenFnType) (int, int, void*); The client callback function `cbFn' is called with the client defined node data: (*cbFn) (tag, dataSize, dataPtr); This gives the client an opportunity to process the client node data (such as CSCmemFree() any client CSCmemAlloc()'d node data) before the node is deallocated. BUGS When CSCbinTreeDel() fails to deallocate internal nodes, in some conditions, CSC_OK may still be returned. SEE ALSO CSCbinTreeNew(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeInsert(3) NAME CSCbinTreeInsert - insert a node into a libcsc balanced binary tree SYNOPSYS #include "libcsc.h" int CSCbinTreeInsert ( CSCbinTreeType const tree, CSCbinTreeNodeType const node, CSCcmpFnType cmpfn ); RETURN VALUE CSC_OK ........ if successful. CSC_DUPKEY .... if `node' already exists in `tree'; this is defined by the value of tree nodes' tags and is discerned by the client callback function pointed to by `cmpfn'. CSC_BADARG .... if libcsc was compiled with the DEBUG macro and `tree', `node', or `cmpfn' is NULL. CSC_CORRUPT ... if libcsc was compiled with the DEBUG macro and CSCbinTreeInsert() detects something munged up in the tree or in some internal data. DESCRIPTION CSCbinTreeInsert() inserts `node' into the libcsc balanced binary tree `tree', and then maintains the balance. DANGER Take care to never insert a node that was joined with another with CSCbinTreeNodeJoin() because it lacks balance information and will completely whack a balanced tree. `cmpfn' is a pointer to a libcsc CSCcmpFnType function that is called for each node in the tree, until the node pointed to by node is inserted. The prototype for `cmpfn' is: int (*cmpfn) (void*, void*); The client callback function `cmpfn' is called to compare the tag field values of the node at node with a node, P, in the tree (note the actual arguments are the addresses of the tag fields): (*cmpfuncptr) ((void*)&node->tag, (void*)&P->tag); This gives the client control over the insertion order. The CSCcmpFnType function should return only the values -1, 0, and 1: -1 .... indicates less than (new node goes into left subtree). 0 .... indicates a duplicate. 1 .... indicates more than (new node goes into right subtree). The tag field of libcsc balanced binary tree nodes is a long, but its semantics are entirely up to the client. Insertion metrics, count comparisons and subtree rotations, can be gotten with CSCbinTreeStat(). CREDITS The balanced tree insertion algorithm is directly taken from Donald E. Knuth, "Sorting and Searching," The Art of Computer Programming, vol. 3 (Reading Mass.: Addison-Wesley 1973). SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeNew(3) NAME CSCbinTreeNew - create an empty libcsc balanced binary tree SYNOPSYS #include "libcsc.h" CSCbinTreeType CSCbinTreeNew ( const char* namePtr, CSCmonFnType monFunc, const void* monData, CSCprofileType profiling ); RETURN VALUE CSCbinTreeNew(), if successful, returns an opaque data type that represents the newly created libcsc balanced binary tree, or NULL if otherwise unsuccessful. DESCRIPTION CSCbinTreeNew() creates and initializes a libcsc balanced binary tree and returns a CSCbinTreeType; the data structure is opaque. DANGER Take care to never insert into a balanced binary tree a node that was joined with another by using CSCbinTreeNodeJoin() because it lacks balance information and will completely whack a balanced tree. DANGER Never, never, never use CSCbinTreeNodeBreak() on a node in a libcsc balanced binary tree. In general: do not try mixing the CSCbinTree and CSCbinTreeNode functions on the same tree. SEE ALSO CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeNodeBreak(3) NAME CSCbinTreeNodeBreak - break libcsc binary tree at a node SYNOPSYS #include "libcsc.h" int CSCbinTreeNodeBreak ( CSCbinTreeNodeType const node, CSCbinTreeNodeType* const leftPtr, CSCbinTreeNodeType* const rightPtr ); RETURN VALUE CSCbinTreeNodeBreak() returns CSC_OK, unless node is NULL, in which case CSC_BADARG is returned. DESCRIPTION CSCbinTreeNodeBreak() takes `node' and optionally replaces its left and/or right node pointers with NULL and writes its original left and/or right node pointers to the CSCbinTreeNodeTypethat are pointed to by `leftPtr' and `rightPtr'. NEVER, EVER do this to a node in a libcsc balanced binary tree. Only use CSCbinTreeNodeBreak() on nodes in trees that are built with CSCbinTreeNodeJoin(). If `leftPtr' is not NULL, then `node''s left node is written to the CSCbinTreeNodeType pointed to by `leftPtr'. If `rightPtr' is not NULL, then `node''s right node is written to the CSCbinTreeNodeType pointed to by `rightPtr'. Remember .....> Either of the left and/or right nodes that may be returned via `leftPtr' and `rightPtr' may be NULL; certainly this is the case when node is a leaf node. BUGS Odd But True Department: If `leftPtr' and `rightPtr' are both NULL then no action is taken and CSC_OK is returned. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeNodeDel(3) NAME CSCbinTreeNodeDel - deallocate a libcsc binary tree node SYNOPSYS #include "libcsc.h" int CSCbinTreeNodeDel ( CSCbinTreeNodeType const node ); RETURN VALUE CSC_OK ......... if successful. CSC_NOTFOUND ... if not successful. CSC_BADARG ..... if libcsc was compiled with the DEBUG macro and node is NULL. CSC_CORRUPT .... if libcsc was compiled with the DEBUG macro and some internal tree data is munged up. DESCRIPTION CSCbinTreeNodeDel() deallocates `node'. NEVER, EVER do this to a node in a libcsc balanced binary tree. Only use CSCbinTreeNodeDel() on nodes removed from tree that are built with CSCbinTreeNodeJoin(). Nodes in a libcsc balanced binary trees cannot be removed. :/ The node data should be retreived with CSCbinTreeNodeStat() and removed, or otherwise cleaned up, before calling this function. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeNodeJoin(3) NAME CSCbinTreeNodeJoin - join libcsc binary tree nodes SYNOPSYS #include "libcsc.h" int CSCbinTreeNodeJoin ( CSCbinTreeNodeType const node, CSCbinTreeNodeType const left, CSCbinTreeNodeType const right ); RETURN VALUE CSCbinTreeNodeJoin() returns CSC_OK unless node is NULL, in which case CSC_BADARG is returned. If libcsc is compiled with the DEBUG macro and some internal tree data is munged, then rtsBinTreeNodeJoin() returns CSC_CORRUPT. DESCRIPTION CSCbinTreeNodeJoin() simply assigns `left' to the left node pointer of `node', and assigns `right' to the right pointer of `node'. Use CSCbinTreeNodeJoin() to create your own libcsc binary trees that are distinct and separate from libcsc balanced binary trees that are created with CSCbinTreeNew() and CSCbinTreeInsert(). It is completely acceptable for `left' and/or `right' to be NULL. Beware, if the the `left' and/or `right' node pointer of the node is already in use, then it will be lost. Don't create dangling trees. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeNodeNew(3) NAME CSCbinTreeNodeNew - create a new empty libcsc binary tree node SYNOPSYS #include "libcsc.h" CSCbinTreeNodeType CSCbinTreeNodeNew ( CSCdataCntrlType push, long tag, const void* const dataPtr, size_t dataSize ); RETURN VALUE CSCbinTreeNodeNew(), if successful, returns a CSCbinTreeNodeType for the newly created libcsc binary tree node, or NULL if otherwise not successful. DESCRIPTION CSCbinTreeNodeNew() creates a new libcsc binary tree node that is appropriate for use: 1) with CSCbinTreeInsert() on libcsc balanced binary trees that are created with CSCbinTreeNew() 2) for joining together with CSCbinTreeNodeJoin() The new node's `tag' is used by client callback compare functions when libcsc balanced binary tree nodes are inserted, searched, or traversed. `push' is one of CSC_DATA_DUP the data pointed to by `dataPtr', for `dataSize' bytes, is duplicated and put into the new node. CSC_DATA_NODUP `dataPtr' and `dataSize' are directly put into the new node. This new node will retain the reference to the data at `dataPtr'; therefore, it should be clear that if that data is changed (or deallocated!) then it is the data that this new node points to that is affected. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeNodePrint(3) NAME CSCbinTreeNodePrint - print the values of a libcsc binary tree node SYNOPSYS #include "libcsc.h" int CSCbinTreeNodePrint ( CSCbinTreeNodeType const node ); RETURN VALUE CSCbinTreeNodePrint() returns CSC_OK. If libcsc was compiled with the DEBUG macro and node is NULL, then CSCbinTreeNodePrint() returns CSC_BADARG. If libcsc was compiled with the DEBUG macro and some internal tree data is munged up then CSCbinTreeNodePrint() returns CSC_CORRUPT. DESCRIPTION CSCbinTreeNodePrint() writes to standard output the values of the balance, tag, and data size fields of node. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) ------------------------------------------------------------------------ CSCbinTreeNodeStat(3) NAME CSCbinTreeNodeStat - retrieve fields from a libcsc binary tree node SYNOPSYS #include "libcsc.h" int CSCbinTreeNodeStat ( CSCbinTreeNodeType const node, CSCdataCntrlType* const pushPtr, long* const tagPtr, size_t* const sizePtr, void** const dataPtrPtr ); RETURN VALUE CSCbinTreeNodeStat() returns CSC_OK. If libcsc was compiled with the DEBUG macro and node is NULL, then CSCbinTreeNodeStat() returns CSC_BADARG. If libcsc was compiled with the DEBUG macro and some internal tree data is munged up then CSCbinTreeNodeStat() returns CSC_CORRUPT. DESCRIPTION CSCbinTreeNodeStat() is used to get values of various fields from the given libcsc binary tree node `node'. if `pushPtr' is not NULL, then the value of the push field of `node' is written to the CSCdataCntrlType pointed to by `pushPtr'. if `tagPtr' is not NULL, then the value of the tag field of `node' is written to the long pointed to by `tagPtr'. if `sizePtr' is not NULL, then the value of the data size field of `node' is written to the size_t pointed to by `sizePtr'. if `dataPtrPtr' is not NULL, then the value of the data pointer field `node' is written to the void pointer pointed to by `dataPtrPtr'. If tagPtr, sizePtr, and dataPtrPtr are all NULL, then this function does nothing interesting. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeNodeTagSearch(3) NAME CSCbinTreeNodeTagSearch - search a libcsc binary tree for a given tag SYNOPSYS #include "libcsc.h" CSCbinTreeNodeType CSCbinTreeNodeTagSearch ( CSCbinTreeNodeType const node, long tag ); RETURN VALUE CSCbinTreeNodeTagSearch(), if successful, returns a CSCbinTreeNodeType that is the node whose tag-field value is equal to tag, or NULL if otherwise not successful. DESCRIPTION CSCbinTreeNodeTagSearch() searches `node', and recursively all of its children, for a node with a tag-field that is equal to `tag'. A recursive postfix tree traversal algorithm is used. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeNodeTraverse(3) NAME CSCbinTreeNodeTraverse - traverse a libcsc binary tree SYNOPSYS #include "libcsc.h" int CSCbinTreeNodeTraverse ( const char* const method, CSCbinTreeNodeType const node, CSCcmpFnType clientFn, const void* const clientData ); RETURN VALUE CSCbinTreeNodeTraverse() returns CSC_OK on a successful traversal with the desired node being found, or CSC_NOTFOUND on a successful traversal with the desired node being not found. If libcsc was compiled with the DEBUG macro and some internal tree data is munged up then rtsBinTreeNodeTraverse() returns CSC_CORRUPT. If libcsc was compiled with the DEBUG macro and invalid arguments are detected, then rtsBinTreeNodeTraverse() returns CSC_BADARG. DESCRIPTION CSCbinTreeNodeTraverse() traverses a libcsc binary tree beginning with `node'. `method' is a string that specifies the search algorithm (case IS important): method ------ "PREFIX" "INFIX" "POSTFIX" If `clientFn' is not NULL, then it is a pointer to a libcsc CSCcmpFnType function that is called for EACH NODE in the tree. The prototype for clientFn is: int (*clientFn) (void*, void*); The client callback function `clientFn' is called with the client supplied data and a node pointer (on which the client then needs to use CSCbinTreeNodeQuery()): stat = (*clientFn) ((void*)&node, (void*)clientData); This gives the client an opportunity to terminate the traversal by returning CSC_OK; otherwise, the function pointed to by `clientFn' should return CSC_NOTFOUND. If `clientFn' returns any value besides CSC_NOTFOUND, then the tree traversal is terminated, and the return value from CSCbinTreeNodeTraverse() will be the value returned from `clientFn'. In this case, if libcsc was compiled with the DEBUG macro, then there will be an assertion if the return value is not CSC_OK or CSC_NOTFOUND, but no other processing is affected. If `clientFn' is NULL, then the libcsc binary tree is traversed according to `method', but nothing interesting happens. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeNodeUserSearch(3) NAME CSCbinTreeNodeUserSearch - arbitrary libcsc binary tree traversal SYNOPSYS #include "libcsc.h" CSCbinTreeNodeType CSCbinTreeNodeUserSearch ( CSCbinTreeNodeType const node, CSCcmpFnType clientFn, const void* const clientData ); RETURN VALUE CSCbinTreeNodeUserSearch(), if successful, returns a CSCbinTreeNodeType that is the desired libcsc binary tree node; otherwise NULL is returned if not successful. DESCRIPTION CSCbinTreeNodeUserSearch() traverses the libcsc binary tree beginning with `node'. The tree traversal algorithm and traversal termination are controlled by the client callback function `clientFn'. `clientFn' is a libcsc CSCcmpFnType function that is called for each node in the tree. The prototype for clientFn is: int (*clientFn) (void*, void*); `clientFn' is called with the client supplied data and a node pointer (on which the client then needs to use CSCbinTreeNodeQuery()): switchValue = (*clientFn) ((void*)&node, (void*)clientData); This gives the client control over tree traversal. `clientFn' should return only the values -1, 0, and 1: -1 .... traversal continues on left node. 0 .... terminate traversal. 1 .... traversal continues on right node. This function probably makes sense only with oddly shaped binary trees constructed with CSCbinTreeNodeJoin(). BUGS If `clientFn' is NULL, and libcsc was NOT compiled with the DEBUG macro, then CSCbinTreeNodeUserSearch() probably dies a horrible segfault death. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreePrint(3) NAME CSCbinTreePrint - print a libcsc balanced binary tree SYNOPSYS #include "libcsc.h" int CSCbinTreePrint ( CSCbinTreeType const tree ); RETURN VALUE CSCbinTreePrint() returns CSC_OK. If libcsc was compiled with the DEBUG macro and tree is NULL, then CSCbinTreePrint() returns CSC_BADARG. If libcsc was compiled with the DEBUG macro and some internal tree data is munged up, then CSCbinTreePrint() returns CSC_CORRUPT. DESCRIPTION CSCbinTreePrint() writes to standard output these statistics for the libcsc balanced binary tree `tree': statistic --------- count ......... total number of nodes in the tree. height ........ maximum current height of the tree. compares ...... number of compares from most recent insert. rotates ....... number of rotations from most recent insert. After the overall tree statistics, various fields of all the nodes in tree are written, to standard output, via an internal call to CSCbinTreeNodePrint(). For each node, the value of the left and right node's tag field is printed for tracability. A prefix binary tree traversal algorithm is used. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeStat(3) NAME CSCbinTreeStat - retrieve libcsc balanced binary tree statistics SYNOPSYS #include "libcsc.h" int CSCbinTreeStat ( CSCbinTreeType const tree, size_t* const countPtr, size_t* const heightPtr, size_t* const comparesPtr, size_t* const rotatesPtr ); RETURN VALUE CSCbinTreeStat() returns CSC_OK. If libcsc was compiled with the DEBUG macro and tree is NULL, then CSCbinTreeStat() returns CSC_BADARG. If libcsc was compiled with the DEBUG macro and some internal tree data is munged up, then CSCbinTreeStat() returns CSC_CORRUPT. DESCRIPTION CSCbinTreeStat() retrieves these statistics from the libcsc balanced binary tree `tree': statistic --------- count ......... total number of nodes in the tree. height ........ maximum current height of the tree. compares ...... number of compares from most recent insert. rotates ....... number of rotations from most recent insert. If `countPtr' is not NULL, then the total number of nodes in the tree is written to the size_t pointed to by `countPtr'. If `heightPtr' is not NULL, then the maximum current height of the tree is written to the size_t pointed to by `heightPtr'. If `comparesPtr' is not NULL, then the number of compares from most recent insert is written to the size_t pointed to by `comparesPtr'. If `rotatesPtr' is not NULL, then the number of rotations from most recent insert is written to the size_t pointed to by `rotatesPtr'. If `countPtr', `heightPtr', `comparesPtr', and `rotatesPtr' are all NULL, then this function does nothing interesting. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeTagOrderedInsert(3) NAME CSCbinTreeTagOrderedInsert - put node into libcsc balanced binary tree SYNOPSYS #include "libcsc.h" int CSCbinTreeTagOrderedInsert ( CSCbinTreeType const tree, CSCbinTreeNodeType const node ); RETURN VALUE CSC_OK ........ if successful. CSC_DUPKEY .... if `node' already exists in `tree' (this is defined by the value of the nodes' tags). CSC_BADARG .... if libcsc was compiled with the DEBUG macro and `tree' or `node' is NULL. CSC_CORRUPT ... if libcsc was compiled with the DEBUG macro and CSCbinTreeTagOrderedInsert() detects something munged up in the tree or in some internal data. DESCRIPTION CSCbinTreeTagOrderedInsert() inserts `node' into the libcsc balanced binary tree `tree', and then CSCbinTreeTagOrderedInsert() maintains the balance. The insertion order is strictly based upon the tag field values of node and the tag field values of the nodes in the libcsc balanced binary tree. DANGER Take care to never insert a node that was joined with another by using CSCbinTreeNodeJoin() because it lacks balance information and will completely whack a balanced tree. This function internally calls CSCbinTreeInsert() with its own internal tag comparison function. Insertion metrics, count comparisons and subtree rotations, can be gotten with CSCbinTreeStat(). CREDITS The balanced tree insertion algorithm is directly taken from Donald E. Knuth, "Sorting and Searching," The Art of Computer Programming, vol. 3 (Reading Mass.: Addison-Wesley 1973). SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeTagSearch(3) NAME CSCbinTreeTagSearch - search a balanced binary tree for node with tag SYNOPSYS #include "libcsc.h" CSCbinTreeNodeType CSCbinTreeTagSearch ( CSCbinTreeType const tree, long tag ); RETURN VALUE CSCbinTreeTagSearch(), if successful, returns a CSCbinTreeNodeType that is a libcsc balanced binary tree node whose tag-field value is equal to `tag', or NULL if otherwise not successful. DESCRIPTION CSCbinTreeTagSearch() searches the libcsc balanced binary tree `tree' for a node with a tag-field that is equal to `tag'. A recursive postfix tree traversal algorithm is used. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeUserSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeTraverse(3) NAME CSCbinTreeTraverse - traverse a libcsc balanced binary tree SYNOPSYS #include "libcsc.h" int CSCbinTreeTraverse ( const char* const method, CSCbinTreeType const tree, CSCcmpFnType clientFn, const void* const clientData ); RETURN VALUE CSC_OK ......... on a successful traversal with the desired node being found. CSC_NOTFOUND ... on a successful traversal with the desired node being not found. CSC_BADARG ..... if libcsc was compiled with the DEBUG macro and `method', `tree', or `clientFn' is NULL. CSC_CORRUPT .... if libcsc was compiled with the DEBUG macro and CSCbinTreeTraverse() detects something munged up in' the tree or in some internal data. DESCRIPTION CSCbinTreeTraverse() traverses the libcsc balanced binary tree `tree'. `method' is a string that specifies the search algorithm (case IS important): method ------ "PREFIX" "INFIX" "POSTFIX" `clientFn' is a pointer to a libcsc CSCcmpFnType function that is called for EACH NODE in the tree. The prototype for CSCcmpFnType is: int (*CSCcmpFnType) (void*, void*); The client callback function `clientFn' is called with the client supplied data and a node pointer (on which the client then needs to use rtsBinTreeNodeQuery()): stat = (*clientFn) ((void*)&node, (void*)clientData); This gives the client an opportunity to terminate the traversal by `clientFn' returning CSC_OK (indicating a match); otherwise, `clientFn' should return CSC_NOTFOUND. If `clientFn' returns any value besides CSC_NOTFOUND then the traversal is terminated, and the return value from CSCbinTreeTraverse() will be the value returned from `clientFn'. In this case, if libcsc was compiled with the DEBUG macro, then there will be an assertion if the return value is not CSC_OK or CSC_NOTFOUND, but no other processing is affected. If clientFn is NULL, then the libcsc balanced binary tree is traversed according to method, but nothing interesting happens; except if libcsc was compiled with the DEBUG macro, in which case the tree will be sanity checked. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeUserSearch(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCbinTreeUserSearch(3) NAME CSCbinTreeUserSearch - arbitrary search of libcsc balanced binary tree SYNOPSYS #include "libcsc.h" CSCbinTreeNodeType CSCbinTreeUserSearch ( CSCbinTreeType const tree, CSCcmpFnType clientFn, const void* const clientData ); RETURN VALUE CSCbinTreeUserSearch(), if successful, returns a CSCbinTreeNodeType that is a node from the libcsc balanced binary tree `tree'. CSCbinTreeUserSearch() returns NULL, if not successful. DESCRIPTION CSCbinTreeUserSearch() traverses the libcsc balanced binary tree `tree'. The tree traversal algorithm and traversal termination are controlled by the client callback function `clientFn'. `clientFn' is a pointer to a libcsc CSCcmpFnType function that is called for each node in `tree'. The prototype for clientFn is: int (*clientFn) (void*, void*); The client callback function `clientFn' is called with the client supplied data `clientData' and a node pointer (on which the client then needs to use CSCbinTreeNodeStat()): switchValue = (*clientFn) ((void*)&node, (void*)clientData); This gives the client control over tree traversal. `clientFn' should return only the values -1, 0, and 1: -1 .... traversal continues on left node. 0 .... terminate traversal. 1 .... traversal continues on right node. BUGS This function probably makes no sense. If `clientFn' is NULL, and libcsc was NOT compiled with the DEBUG macro, then CSCbinTreeUserSearch() probably dies a horrible segfault death. SEE ALSO CSCbinTreeNew(3) CSCbinTreeDel(3) CSCbinTreeInsert(3) CSCbinTreeTagOrderedInsert(3) CSCbinTreeTraverse(3) CSCbinTreeTagSearch(3) CSCbinTreeStat(3) CSCbinTreePrint(3) CSCbinTreeNodeNew(3) CSCbinTreeNodeDel(3) CSCbinTreeNodeJoin(3) CSCbinTreeNodeBreak(3) CSCbinTreeNodeTraverse(3) CSCbinTreeNodeUserSearch(3) CSCbinTreeNodeTagSearch(3) CSCbinTreeNodeStat(3) CSCbinTreeNodePrint(3) ------------------------------------------------------------------------ CSCcflags(3) NAME CSCcflags - get string containing compiler command-line options SYNOPSYS #include "libcsc.h" const char* CSCcflags (void); DESCRIPTION CSCldflags() returns a pointer to a constant ASCII-Z string containing the compiler specfic (cc) command-line options. SEE ALSO CSCstatStr(3) CSCldflags(3) CSClibs(3) CSCversion(3) CSCcredits(3) CSCchkup(3) ------------------------------------------------------------------------ CSCchkup(3) NAME CSCchkup - check scalar data sizes assumed by libcsc SYNOPSYS #include "libcsc.h" void CSCchkup (void); RETURN VALUE CSCchkup() returns no value. DESCRIPTION CSCchkup is a diagnostic function that checks libcsc assumptions made about scalar data sizes e.g., sizeof(int) is 4. SEE ALSO CSCstatStr(3) CSCcflags(3) CSCldflags(3) CSClibs(3) CSCversion(3) CSCcredits(3) ------------------------------------------------------------------------ CSCcredits(3) NAME CSCcredits - get string containing the libcsc credits SYNOPSYS #include "libcsc.h" const char* CSCcredits (void); DESCRIPTION CSCcredits() returns a pointer to a constant ASCII-Z string containing the names of the major libcsc developers. SEE ALSO CSCstatStr(3) CSCcflags(3) CSCldflags(3) CSClibs(3) CSCversion(3) CSCchkup(3) ------------------------------------------------------------------------ CSCfileBaseName(3) NAME CSCfileBaseName - strip directory from pathname SYNOPSYS #include "libcsc.h" char* CSCfileBaseName ( const char* const path, CSCmemListType const memList, int memTag ); RETURN VALUE CSCfileBaseName() returns a pointer to a new string that begins with the first character in path after the last occurence of a '/' character. CSCfileBaseName() returns a pointer to path if the path string does not contain a '/' character. CSCfileBaseName() returns NULL if `path' or `memList' argument is NULL. DESCRIPTION If CSCfileBaseName() is successful, it returns a pointer to a new string that is allocated by CSCmemAlloc(); the string must be freed with CSCmemFree() to avoid a memory leak. SEE ALSO CSCfilePathName(3) ------------------------------------------------------------------------ CSCfileExpandPath(3) NAME CSCfileExpandPath - expand ~ and environment variables in pathname SYNOPSYS #include "libcsc.h" char* cscFileExpandPath ( const char* const path, const size_t pathMax, CSCmemListType const memList, int memTag ); RETURN VALUE CSCfileExpandPath() returns a pointer to a newly allocated string, if successful; otherwise, it returns NULL on failure. DESCRIPTION CSCfileExpandPath() expands the `~' character and environment variables in the string in the path argument. The new expanded string must be a length less than or equal to pathMax, including the terminating NULL character. If successful, cscFileExpandPath() returns a pointer to a new string that is allocated by rtsMemAlloc(); the string must be freed with CSCmemFree() to avoid a memory leak. SEE ALSO ------------------------------------------------------------------------ CSCfileGetHomeDir(3) NAME CSCfileGetHomeDir - find home directory pathname SYNOPSYS #include "libcsc.h" char* CSCfileGetHomeDir ( const size_t pathSize, CSCmemListType const memList, int memTag ); RETURN VALUE CSCfileGetHomeDir() returns a pointer to the home directory associated with the user ID of the process, if successful; otherwise, NULL is returned. DESCRIPTION The returned home directory string should be a length less than or equal to `pathSize', including the terminating NULL character; if not, then an unterminated string containing `pathSize' characters is returned. If successful, CSCfileGetHomeDir() returns a pointer to a new string that is allocated by CSCmemAlloc(); the string must be freed with CSCmemFree() to avoid a memory leak. SEE ALSO CSCfileGetUserHomeDir(3) ------------------------------------------------------------------------ CSCfileGetUserHomeDir(3) NAME CSCfileGetUserHomeDir - find home directory pathname of specific user SYNOPSYS #include "libcsc.h" char* cscFileGetUserHomeDir ( const char* const userName, const size_t pathSize, CSCmemListType const memList, int memTag ); RETURN VALUE CSCfileGetUserHomeDir() returns a pointer to the home directory associated with the specific user name userName, if successful; otherwise, NULL is returned. DESCRIPTION The returned home directory string should be a length less than or equal to `pathSize', including the terminating NULL character; if not, then an unterminated string containing `pathSize' characters is returned. If successful, CSCfileGetUserHomeDir() returns a pointer to a new string that is allocated by CSCmemAlloc(); the string must be freed with CSCmemFree() to avoid a memory leak. SEE ALSO CSCfileGetHomeDir(3) ------------------------------------------------------------------------ CSCfileOpen(3) NAME CSCfileOpen - create a file in a path that doesn't (yet) exist SYNOPSYS #include "libcsc.h" FILE* CSCfileOpen ( const char* const path, const int mask, const size_t pathMax, CSCmemListType const memList, int memTag ); RETURN VALUE CSCfileOpen() returns a new file, open for writing, if successful. On failure, CSCfileOpen() returns NULL. DESCRIPTION CSCfileOpen() opens a new file for writing, creating the path if necessary. SEE ALSO ------------------------------------------------------------------------ CSCfilePathName(3) NAME CSCfilePathName - strip last component (file) from pathname SYNOPSYS #include "libcsc.h" char* CSCfilePathName ( const char* const path, CSCmemListType const memList, int memTag ); RETURN VALUE CSCfilePathName() returns a pointer to a new string that begins with the first character in path and terminates with the last character preceding the last '/' character. CSCfilePathName() returns NULL if it is not successful. DESCRIPTION If CSCfilePathName() is successful, it returns a pointer to a new string that is allocated by CSCmemAlloc(); the string must be freed with CSCmemFree() to avoid a memory leak. SEE ALSO CSCfileBaseName(3) ------------------------------------------------------------------------ CSCfileReadLock(3) NAME CSCfileReadLock - read-lock a region in a file SYNOPSYS #include "libcsc.h" int CSCfileReadLock ( int fd, off_t offset, int whence, off_t length ); RETURN VALUE CSCfileReadLock() returns 0 if successful, otherwise -1 and errno will be set to indicate the error. DESCRIPTION CSCfileReadLock() read locks a region of file associated with fd. The locked region in the file is at offset from beginning/end of the file depending upon the value of whence. The locked region is length bytes. whence usage is as follows: SEEK_SET The offset is set to offset bytes. SEEK_CUR The offset is set to its current location plus off-set bytes. SEEK_END The offset is set to the size of the file plus off-set bytes. SEE ALSO CSCfileWriteLock(3) CSCfileUnlock(3) ------------------------------------------------------------------------ CSCfileUnlock(3) NAME CSCfileUnlock - unlock a region in a file SYNOPSYS #include "libcsc.h" int CSCfileUnlock ( int fd, off_t offset, int whence, off_t length ); RETURN VALUE CSCfileUnlock() returns 0 if successful, otherwise -1 and errno will be set to indicate the error. DESCRIPTION CSCfileUnlock() unlocks a region of file associated with fd. The unlocked region in the file is at offset from beginning/end of the file depending upon the value of whence. The unlocked region is length bytes. whence usage is as follows: SEEK_SET The offset is set to offset bytes. SEEK_CUR The offset is set to its current location plus off-set bytes. SEEK_END The offset is set to the size of the file plus off-set bytes. SEE ALSO CSCfileReadLock(3) CSCfileWriteLock(3) ------------------------------------------------------------------------ CSCfileWriteLock(3) NAME CSCfileWriteLock - write-lock a region in a file SYNOPSYS #include "libcsc.h" int CSCfileWriteLock ( int fd, off_t offset, int whence, off_t length ); RETURN VALUE CSCfileWriteLock() returns 0 if successful, otherwise -1 and errno will be set to indicate the error. DESCRIPTION CSCfileWriteLock() read locks a region of file associated with fd. The locked region in the file is at offset from beginning/end of the file depending upon the value of whence. The locked region is length bytes. whence usage is as follows: SEEK_SET The offset is set to offset bytes. SEEK_CUR The offset is set to its current location plus off-set bytes. SEEK_END The offset is set to the size of the file plus off-set bytes. SEE ALSO CSCfileReadLock(3) CSCfileUnlock(3) ------------------------------------------------------------------------ CSChashDel(3) NAME CSChashDel - remove a libcsc hash table SYNOPSYS #include "libcsc.h" int CSChashDel ( CSChashTableType const hashTable ); RETURN VALUE CSChashDel(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION The libcsc hash table represented by the opaque `hashTable' is completely removed. SEE ALSO CSChashNew(3) CSChashStat(3) CSChashEntryPut(3) CSChashEntryGet(3) CSChashEntryDel(3) CSChashEntryNext(3) CSChashEntryStat(3) CSChashRead(3) CSChashWrite(3) CSChashDump(3) ------------------------------------------------------------------------ CSChashDump(3) NAME CSChashDump - write a formatted dump of a libcsc hash table SYNOPSYS #include "libcsc.h" int CSChashDump ( int fd, CSChashTableType const hashTable ); RETURN VALUE CSChashDump() always returns CSC_OK. Lame. DESCRIPTION CSChashDump() writes to `fd' a formatted dump of the entire hash table represented by the opaque `hashTable'. This formatted dump of the hash table is for visual inspection of the hash table. After a short header, each item's hash value, key, data size, and data dump is written. Don't do this with large hash tables, even if they are sparsely populated; nobody would read it. SEE ALSO CSChashNew(3) CSChashDel(3) CSChashStat(3) CSChashEntryPut(3) CSChashEntryGet(3) CSChashEntryDel(3) CSChashEntryNext(3) CSChashEntryStat(3) CSChashRead(3) CSChashWrite(3) ------------------------------------------------------------------------ CSChashEntryDel(3) NAME CSChashEntryDel - remove an entry from a libcsc hash table SYNOPSYS #include "lib.h" int CSChashEntryDel ( CSChashTableType const hashTable, CSChashKeyUnion* const keyPtr ); RETURN VALUE CSChashEntryDel(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION The hash table entry with the key value that is pointed to by `keyPtr' is removed from the hash table represented by the opaque `hashTable'. Of course, the type of the key pointed to by `keyPtr' must match the type of keys (CSC_HASH_INT32_KEY or CSC_HASH_ASCIIZ_KEY) used by `hashTable'. SEE ALSO CSChashNew(3) CSChashDel(3) CSChashStat(3) CSChashEntryPut(3) CSChashEntryGet(3) CSChashEntryNext(3) CSChashEntryStat(3) CSChashRead(3) CSChashWrite(3) CSChashDump(3) ------------------------------------------------------------------------ CSChashEntryGet(3) NAME CSChashEntryGet - get an item from a libcsc hash table SYNOPSYS #include "libcsc.h" int CSChashEntryGet ( CSChashTableType const hashTable, CSChashKeyUnion* const keyPtr, void** const itemPtrPtr, size_t* const itemSizePtr, CSCmemListType const memLst ); RETURN VALUE CSChashEntryGet(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSChashEntryGet() looks up the key pointed to by `keyPtr' in the libcsc hash table represented by the opaque `hashTable'. If the item corresponding to the key is found in the table, then a copy of the the data is allocated with CSCmemDup(), or malloc() if `memLst' is NULL, and the pointer of the newly allocated data it is written to the void pointer that is pointed to by `itemPtrPtr', and its size in bytes is written to the size_t pointed to by `itemSizePtr'. Since CSChashEntryGet(), if successful, allocates storage for the retrieved item. If `memLst' is not null then CSCmemDup() is used with the value of `memLst'; the data should be removed with CSCmemFree(), using "tagData" value of zero, to avoid leaking this memory. If `memLst' is NULL, then malloc() is use to allocate storage, and free() should be used to remove the data to avoid leaking this memory. SEE ALSO CSChashNew(3) CSChashDel(3) CSChashStat(3) CSChashEntryPut(3) CSChashEntryDel(3) CSChashEntryNext(3) CSChashEntryStat(3) CSChashRead(3) CSChashWrite(3) CSChashDump(3) ------------------------------------------------------------------------ CSChashEntryNext(3) NAME CSChashEntryNext - find next entry in a libcsc hash table SYNOPSYS #include "libcsc.h" CSChashEntryType CSChashEntryNext ( CSChashTableType const hashTable, CSChashEntryType const entry ); RETURN VALUE CSChashEntryNext(), if successful, returns an opaque libcsc hash table entry. If not successful, CSChashEntryNext() returns NULL. DESCRIPTION CSChashEntryNext() uses the libcsc hash table referred to by the opaque `hashTable' and returns the next consecutive entry following the entry indicated by the opaque `entry'. This next consecutive entry is the entry physically following `entry', its key may hash to the save value as `entry''s key, or it may be some larger hash value. If `entry' is NULL, then the first item in the table is returned. If `hashTable' is a table with no entries, or there are no more entries following entry, then NULL is returned. BUGS This function provides one of the few ways to get direct access to a libcsc hash table's internal data. Avoid using this function. SEE ALSO CSChashNew(3) CSChashDel(3) CSChashStat(3) CSChashEntryPut(3) CSChashEntryGet(3) CSChashEntryDel(3) CSChashEntryStat(3) CSChashRead(3) CSChashWrite(3) CSChashDump(3) ------------------------------------------------------------------------ CSChashEntryPut(3) NAME CSChashEntryPut - put an entry into a libcsc hash table SYNOPSYS #include "libcsc.h" int CSChashEntryPut ( CSChashTableType const hashTable, CSChashKeyUnion* const keyPtr, void* const itemPtr, size_t itemSize ); RETURN VALUE CSChashEntryPut(), if successful, returns CSC_OK. If the key is already in use in the table, then CSChashEntryPut() will return CSC_DUPKEY. Other values, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSChashEntryPut() puts the data pointed to by `itemPtr', whose key is pointed to by `keyPtr' and size in bytes is `itemSize', into the libcsc hash table represented by the opaque `hashTable'. The data that goes into the table is a duplicate of `itemSize' bytes from the address `itemPtr'. To avoid duplicating static data, put a pointer of the client data into the table. If the item being put into the table contains a pointer, beware of aliasing errors if the pointer is to allocated memory that becomes deallocated while the item is in the table. Of course, the type of the key pointed to by `keyPtr' must match the type of keys (CSC_HASH_INT32_KEY or CSC_HASH_ASCIIZ_KEY) used by `hashTable'. SEE ALSO CSChashNew(3) CSChashDel(3) CSChashStat(3) CSChashEntryGet(3) CSChashEntryDel(3) CSChashEntryNext(3) CSChashEntryStat(3) CSChashRead(3) CSChashWrite(3) CSChashDump(3) ------------------------------------------------------------------------ CSChashEntryStat(3) NAME CSChashEntryStat - query the fields of a libcsc hash table entry SYNOPSYS #include "libcsc.h" int CSChashEntryStat ( CSChashEntryType const entry, CSChashKeyUnion** const keyPtrPtr, void** const itemPtrPtr, size_t* const itemSizePtr ); RETURN VALUE If successful, CSChashEntryStat() returns CSC_OK. If entry is NULL, then CSC_BADARG is returned. If libcsc was compiled with the DEBUG macro and the libcsc hash entry at entry is munged up, then CSC_CORRUPT is returned. DESCRIPTION CSChashEntryStat() queries the libcsc hash table entry represented by the opaque `entry'. If `keyPtrPtr' is not NULL, then the a pointer to `entry''s key is written to the CSChashKeyUnion pointer that is pointed to by `keyPtrPtr'. If `itemPtrPtr' is not NULL, then `entry''s item pointer is written to the void pointer that is pointed to by `itemPtrPtr'. If `itemSizePtr' is not NULL, then the size, in bytes, of `entry''s item is written to the size_t pointed to by `itemSizePtr'. BUGS This function provides one of the few ways to get direct access to a libcsc hash table's internal data. Avoid using this function. SEE ALSO CSChashNew(3) CSChashDel(3) CSChashStat(3) CSChashEntryPut(3) CSChashEntryGet(3) CSChashEntryDel(3) CSChashEntryNext(3) CSChashRead(3) CSChashWrite(3) CSChashDump(3) ------------------------------------------------------------------------ CSChashNew(3) NAME CSChashNew - create a new libcsc hash table SYNOPSYS #include "libcsc.h" CSChashTableType CSChashNew ( const char* const name, CSChashKeyType keySpec, size_t size, CSCmonFnType monFunc, const void* monData, CSCprofileType profiling ); RETURN VALUE CSChashNew(), if successful, returns an opaque data type representing a new libcsc hash table, or NULL if otherwise not successful. DESCRIPTION CSChashNew() creates a new libcsc hash table with several attributes: name, type of key, and number of hash locations. `name' points to an arbitrary string that is used as the name of the new libcsc hash table. `keySpec' specifies the type of keys used by the new hash table; it is one of: CSC_HASH_ASCIIZ_KEY ... hash keys for this table will be ASCII NULL-terminated (ASCIIZ) strings. CSC_HASH_INT32_KEY .... hash keys for this table will be integers of the type int32. `size' specifies the number of hash locations, or buckets, in the new libcsc hash table. If size is zero, then the new libcsc hash table will begin life with four hash locations and will quadruple whenever the number of hash locations is some mysterious factor of the total number of hashed items (gets overfull). `profiling' can be CSC_DO_PROFILING or CSC_NO_PROFILING; it specifies whether alocate/free, insertion/deletion, etc. statistics should actually be generated and kept in the hash table. SEE ALSO CSChashDel(3) CSChashStat(3) CSChashEntryPut(3) CSChashEntryGet(3) CSChashEntryDel(3) CSChashEntryNext(3) CSChashEntryStat(3) CSChashRead(3) CSChashWrite(3) CSChashDump(3) ------------------------------------------------------------------------ CSChashRead(3) NAME CSChashRead - read an ASCII format libcsc hash table SYNOPSYS #include "libcsc.h" int CSChashRead ( int fd, CSChashTableType* const hashTablePtr, CSCmonFnType monFunc, const void* monData, CSCprofileType profiling ); RETURN VALUE CSChashRead() always returns CSC_OK. Lame. DESCRIPTION CSChashRead() reads from `fd' a libcsc hash table in ASCII format that was written with CSChashWrite(). `hashTablePtr' should point to a CSChashTableType that is set to NULL; a new libcsc hash table will be created. BUGS There is no error checking in this function. SEE ALSO CSChashNew(3) CSChashDel(3) CSChashStat(3) CSChashEntryPut(3) CSChashEntryGet(3) CSChashEntryDel(3) CSChashEntryNext(3) CSChashEntryStat(3) CSChashWrite(3) CSChashDump(3) ------------------------------------------------------------------------ CSChashStat(3) NAME CSChashStat - query statistics of a libcsc hash table SYNOPSYS #include "libcsc.h" int CSChashStat ( CSChashTableType const hashTable, CSChashStatType* const statStruct ); RETURN VALUE CSChashStat(), if successful, returns a pointer to a structure of queried data, or NULL if otherwise not successful. CSChashStat(), returns CSC_OK, or CSC_BADARG and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSChashStat() queries the libcsc hash table represented by the opaque `hashTable' and fills a CSChashStatType structure. The CSChashStatType structure is typedef struct CSChashStatType { char name[80]; // name of hash table CSCprofileType profiling; // profiling flag size_t count; // count of items in table size_t nhash; // number of hash locations CSCboolean grows; // CSC_TRUE or CSC_FALSE size_t resizes; // num of resizes, if table grows size_t deletions; // num of deletions since resize size_t insertions; // num of insertions since resize size_t collisions; // num of collisions since resize } CSChashStatType; Only up to seventy nine characters of the table name are retrieved. If the table size was specified a zero when it was created with CSChashNew() then the table quadruples its hash locations as it gets full. In this case the grows flag will be CSC_TRUE, otherwise it will be CSC_FALSE. If the table grows, then the deletions, insertions, and collisions fields of the CSChashStatType structure will represent those statistics only since the last time the table resized itself i.e., the deletions, insertions, and collisions are reset to zero when the table resizes itself. EXAMPLE CSChashTableType myTable; CSChashQueryType statStruct; int stat . . . stat = CSChashStat (myTable, &statStruct); . // do something with the statistics . . . SEE ALSO CSChashNew(3) CSChashDel(3) CSChashEntryPut(3) CSChashEntryGet(3) CSChashEntryDel(3) CSChashEntryNext(3) CSChashEntryStat(3) CSChashRead(3) CSChashWrite(3) CSChashDump(3) ------------------------------------------------------------------------ CSChashWrite(3) NAME CSChashWrite - write a libcsc hash table in an ASCII format SYNOPSYS #include "libcsc.h" int CSChashWrite ( int fd, CSChashTableType const hashTable ); RETURN VALUE CSChashWrite() always returns CSC_OK. Lame. DESCRIPTION CSChashWrite() writes to `fd' the libcsc hash table represented by the opaque `hashTable' in an ASCII format. Small, simple tables will be human-readable by patient humans, but CSChashRead() will be happy to read it and create another duplicate libcsc hash table. In this way, libcsc hash tables can be transported between processes, in space or time. Caution: client pointers stored in the table will be severe aliasing bugs when they are read by a different process. BUGS There is no error checking in this function. SEE ALSO CSChashNew(3) CSChashDel(3) CSChashStat(3) CSChashEntryPut(3) CSChashEntryGet(3) CSChashEntryDel(3) CSChashEntryNext(3) CSChashEntryStat(3) CSChashRead(3) CSChashDump(3) ------------------------------------------------------------------------ CSCioBufRead(3) NAME CSCioBufRead - read an ASCII buffer SYNOPSYS #include "libcsc.h" int CSCioBufRead ( int fd, void** const dataPtrPtr, size_t* const sizePtr, CSCmemListType const memList, int tagData ); RETURN VALUE CSC_OK ....... successful CSC_BADARG ... fd is zero, or dataPtrPtr or sizePtr is NULL CSC_ERROR .... read error; no bytes to read, or maybe an odd count of bytes where there was an expected even count CSC_NOMEM .... can't allocate memory for the read buffer DESCRIPTION CSCioBufRead() reads from `fd' an ASCII representation of arbitrary bytes that are formatted as created by CSCioBufWrite(). The ASCII data is converted to binary data and stored in a single dynamically allocated memory block. The void pointer that is pointed to by `dataPtrPtr' is updated with the pointer to newly allocated memory containing the bytes read from fd. NOTE Since the buffer is dynamically allocated with CSCmemAlloc(), the caller must free *bufPtrPtr with CSCmemFree() or CSCmemListFree() to avoid a memory leak. The size_t pointed to by `sizePtr' is updated to contain the number of bytes in the newly allocated buffer. Use CSCioBufWrite() and CSCioBufRead() to store and retrieve arbitrary binary data in portable ASCII format. `memList' and `tag' are as use with CSCmemAlloc(). EXAMPLE void* data; size_t size; // Read from fd (no NULL character received): "4\n12FACE55\n" stat = rtsIObufRead (fd, &data, &size); // Now: *data = 0x12, 0xFA, 0xCE, 0x55 // size = 4; SEE ALSO CSCioInfoPrint(3) CSCioWarnPrint(3) CSCioErrorPrint(3) CSCioSoftwareError(3) CSCioRead(3) CSCioReadLine(3) CSCioBufWrite(3) ------------------------------------------------------------------------ CSCioBufWrite(3) NAME CSCioBufWrite - write an ASCII buffer SYNOPSYS #include "libcsc.h" int CSCioBufWrite ( int fd, const void* dataPtr, size_t size ); RETURN VALUE CSC_OK ....... successful CSC_BADARG ... fd is zero, dataPtr is NULL, or size is zero CSC_ERROR .... write error DESCRIPTION CSCioBufWrite() converts the size_t value of `size' to an ASCII string and writes this to `fd', followed by a newline. Then, `size' bytes, starting at `dataPtr', are each converted to two ASCII characters (a standard "bin to hex" conversion) and written to `fd', followed by a newline. Use CSCioBufWrite() and CSCioBufRead() to store and retrieve arbitrary binary data in portable ASCII format. EXAMPLE int data = 0x12FACE55; stat = rtsIObufWrite (fd, &data, sizeof(int)); // Written to fd (no NULL character sent): "4\n12FACE55\n" SEE ALSO CSCioInfoPrint(3) CSCioWarnPrint(3) CSCioErrorPrint(3) CSCioSoftwareError(3) CSCioRead(3) CSCioReadLine(3) CSCioBufRead(3) ------------------------------------------------------------------------ CSCioErrorPrint(3) NAME CSCioErrorPrint - formatted write to stderr SYNOPSYS #include "libcsc.h" void CSCioErrorPrint ( const char* cscPtr, const char* csuPtr, const char* fmtPtr, ); RETURN VALUE CSCioErrorPrint() returns no value. DESCRIPTION CSCioErrorPrint() is a front end, or wrapper, around fprintf() to standard error. Before printing the typical formatted string, CSCioErrorPrint() prints a string with `csc' and `csu': "-ERROR-: ". EXAMPLE stat = 55; (void)CSCioErrorPrint ("CSCio", "CSCioBufRead", "bad stat %d\n", stat); // This will print to standard error: // "CSCio-ERROR-CSCioBufRead: bad stat 55\n" SEE ALSO CSCioInfoPrint(3) CSCioWarnPrint(3) CSCioSoftwareError(3) CSCioRead(3) CSCioReadLine(3) CSCioBufWrite(3) CSCioBufRead(3) ------------------------------------------------------------------------ CSCioInfoPrint(3) NAME CSCioInfoPrint - formatted write to stdout SYNOPSYS #include "libcsc.h" void CSCioInfoPrint ( const char* cscPtr, const char* csuPtr, const char* fmtPtr, ); RETURN VALUE CSCioInfoPrint() returns no value. DESCRIPTION CSCioInfoPrint() is a front end, or wrapper, around fprintf() to standard output. Before printing the typical formatted string, CSCioInfoPrint() prints a string with `csc' and `csu': "-INFO-: ". EXAMPLE stat = 55; (void)CSCioInfoPrint ("CSCio", "CSCioBufRead", "stat is %d\n", stat); // This will print to standard output: // "CSCio-INFO-CSCioBufRead: stat is 55\n" SEE ALSO CSCioWarnPrint(3) CSCioErrorPrint(3) CSCioSoftwareError(3) CSCioRead(3) CSCioReadLine(3) CSCioBufWrite(3) CSCioBufRead(3) ------------------------------------------------------------------------ CSCioRead(3) NAME CSCioRead - read a specific number of bytes SYNOPSYS #include "libcsc.h" int CSCioRead ( int fd, char* const bufPtr, size_t size ); RETURN VALUE CSCioRead() returns the number of bytes read. On read error, zero is returned. if `fd' is zero, `bufPtr' is NULL, or `size' is zero, then -1 is returned. DESCRIPTION CSCioRead() reads `size' bytes from `fd' into `bufPtr' by calling the read() system call in a loop until `size' bytes is read, or until a read error. SEE ALSO CSCioInfoPrint(3) CSCioWarnPrint(3) CSCioErrorPrint(3) CSCioSoftwareError(3) CSCioReadLine(3) CSCioBufWrite(3) CSCioBufRead(3) ------------------------------------------------------------------------ CSCioReadLine(3) NAME CSCioReadLine - read bytes that are terminated by a newline SYNOPSYS #include "libcsc.h" int CSCioReadLine ( int fd, char** const bufPtrPtr, CSCmemListType const memList, int tagData ); RETURN VALUE CSCioReadLine(), when successful, returns the number of bytes read from `fd'. CSCioReadLine() indicates error by returning -1. Errors are: `fd' is zero or `bufPtrPtr' is NULL, read error, or memory allocation error. DESCRIPTION CSCioReadLine() reads bytes from `fd' until a newline character is encountered. The bytes are stored in a single dynamically allocated buffer; the pointer to the buffer is returned to the caller by writing the pointer to *bufPtrPtr. NOTE Since the buffer is dynamically allocated with CSCmemAlloc(), the caller must free *bufPtrPtr with CSCmemFree() or CSCmemListFree() to avoid a memory leak. The terminating newline (maybe just LF or maybe CRLF) is in the returned data. `memList' and `tag' are as use with CSCmemAlloc(). SEE ALSO CSCioInfoPrint(3) CSCioWarnPrint(3) CSCioErrorPrint(3) CSCioSoftwareError(3) CSCioRead(3) CSCioBufWrite(3) CSCioBufRead(3) ------------------------------------------------------------------------ CSCioSoftwareError(3) NAME CSCioSoftwareError - print a parameterized software error message SYNOPSYS #include "libcsc.h" void CSCioSoftwareError ( const char* identPtr, const char* csciPtr, const char* fmtPtr, ... ); RETURN VALUE CSCioSoftwareError() returns no value. DESCRIPTION CSCioSoftwareError() is a utility function that prints a software error message with `csciPtr' being the name of the program, `identPtr' being a version description. `fmtPtr' is a printf() style format string, the last arguments, if any, are format items. The message will look something like this: -ERROR-softwareError: INTERNAL SOFTWARE ERROR. -- Please report this to the maintainer(s) of . -- Please include the command-line invocation of, the conditions under -- which this error happened, and the following version description: SEE ALSO CSCioInfoPrint(3) CSCioWarnPrint(3) CSCioErrorPrint(3) CSCioRead(3) CSCioReadLine(3) CSCioBufWrite(3) CSCioBufRead(3) ------------------------------------------------------------------------ CSCioWarnPrint(3) NAME CSCioWarnPrint - formatted write to stdout SYNOPSYS #include "libcsc.h" void CSCioWarnPrint ( const char* cscPtr, const char* csuPtr, const char* fmtPtr, ); RETURN VALUE CSCioWarnPrint() returns no value. DESCRIPTION CSCioWarnPrint() is a front end, or wrapper, around fprintf() to standard output. Before printing the typical formatted string, CSCioWarnPrint() prints a string with `csc' and `csu': "-WARN-: ". EXAMPLE stat = 55; (void)CSCioWarnPrint ("CSCio", "CSCioBufRead", "stat is %d\n", stat); // This will print to standard output: // "CSCio-WARN-CSCioBufRead: stat is 55\n" SEE ALSO CSCioInfoPrint(3) CSCioErrorPrint(3) CSCioSoftwareError(3) CSCioRead(3) CSCioReadLine(3) CSCioBufWrite(3) CSCioBufRead(3) ------------------------------------------------------------------------ CSCldflags(3) NAME CSCldflags - get string containing compiler command-line options SYNOPSYS #include "libcsc.h" const char* CSCldflags (void); DESCRIPTION CSCldflags() returns a pointer to a constant ASCII-Z string containing the linker (ld) command-line options. SEE ALSO CSCstatStr(3) CSCcflags(3) CSClibs(3) CSCversion(3) CSCcredits(3) CSCchkup(3) ------------------------------------------------------------------------ CSClibs(3) NAME CSClibs - get string containing compiler command-line options SYNOPSYS #include "libcsc.h" const char* CSClibs (void); DESCRIPTION CSClibs() returns a pointer to a constant ASCII-Z string containing the the compiler command-line options that specify the libraries that libcsc is linked against. SEE ALSO CSCstatStr(3) CSCcflags(3) CSCldflags(3) CSCversion(3) CSCcredits(3) CSCchkup(3) ------------------------------------------------------------------------ CSClistDel(3) NAME CSClistDel - remove a libcsc list SYNOPSYS #include "libcsc.h" int CSClistDel ( CSClistType const list ); RETURN VALUE CSClistDel(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_ERROR can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSClistDel() completely removes the libcsc list represented by the opaque `list'. SEE ALSO CSClistNew(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistNew(3) NAME CSClistNew - create a new libcsc list SYNOPSYS #include "libcsc.h" CSClistType CSClistNew ( const char* name, CSCmonFnType monFunc, const void* monData, CSCprofileType profiling ); RETURN VALUE CSClistNew(), if successful, returns an opaque CSClistType, or NULL if otherwise not successful. DESCRIPTION CSClistNew() creates a new list. `profiling' can be CSC_DO_PROFILING or CSC_NO_PROFILING; it specifies whether alocate/free statistics should actually be generated and kept in the list. SEE ALSO CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistNodeDel(3) NAME CSClistNodeDel - remove an entry (node) from a libcsc list SYNOPSYS #include "libcsc.h" int CSClistNodeDel ( CSClistType const list, CSClistNodeType node ); RETURN VALUE CSClistNodeDel(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION The list entry (node)specified by the opaque `node' is removed from `list'. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) ------------------------------------------------------------------------ CSClistNodeFindByReference(3) NAME CSClistNodeFindByReference - find libcsc list entry (node) by reference SYNOPSYS #include "libcsc.h" CSClistNodeType CSClistNodeFindByReference ( CSClistType const list, CSClistBiasType bias, const void* const itemPtr ); RETURN VALUE CSClistNodeFindByReference(), returns a CSClistNodeType if it is successful, or NULL if otherwise not successful. DESCRIPTION CSClistNodeFindByReference() searches `list' for an entry (node). The search is either from the head of `list' or the tail; this is specified by `bias', which is one of CSC_LIST_HEAD Search from the most recently added entries. CSC_LIST_TAIL Search from the oldest entry. Beginning at the specified end (head or tail), each entry's (node's) data pointer is compared to `itemPtr'. CSClistNodeFindByReference() returns the first entry (node) whose data pointer is equal to `itemPtr'. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistNodeFindByValue(3) NAME CSClistNodeFindByValue - find libcsc list entry by data value SYNOPSYS #include "libcsc.h" CSClistNodeType CSClistNodeFindByValue ( CSClistType const list, CSClistBiasType bias, const void* const itemPtr ); RETURN VALUE CSClistNodeFindByValue(), returns a CSClistNodeType if it is successful, or NULL if otherwise not successful. DESCRIPTION CSClistNodeFindByValue() searches `list' for an entry (node). The search is either from the head of `list' or the tail; this is specified by `bias', which is one of CSC_LIST_HEAD Search from the most recently added entries. CSC_LIST_TAIL Search from the oldest entry. Beginning at the specified end (head or tail), each entry's (node's) data is compared against the data at `itemPtr'. This compare is implemented by `list's client-specified compare function. If `list' does not have a client specified compare function, then CSClistNodeFindByValue() will fail and return NULL. `list's client-specified compare function is used in this manner: if ((*list->cfunc) ((void*)itemPtr, (void*)entry->dataPtr) == 0) return (entry); If `list's client-specified compare function returns zero, then the search is terminated, and the first entry found containing the desired data is returned. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistNodeNext(3) NAME CSClistNodeNext - find next entry (node) in a libcsc list SYNOPSYS #include "libcsc.h" CSClistNodeType CSClistNodeNext ( CSClistType const list, CSClistBiasType bias, CSClistNodeType node ); RETURN VALUE CSClistNodeNext(), if successful, returns an opaque libcsc list node. If not successful, CSClistNodeNext() returns NULL. DESCRIPTION CSClistNodeNext() uses the libcsc list referred to by the opaque `list' and returns the next/previous consecutive entry following/preceding the entry indicated by the opaque `node'. `bias' specifies whether the next or previous node is retreievd. Legal values for `bias' are CSC_LIST_HEAD and CSC_LIST_TAIL. If `node' is NULL, then the first item (head or tail depending upon the value of `bias') in list is returned. If `list' has no entries, or there are no more entries (nodes) following `node', then NULL is returned. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistNodeStat(3) NAME CSClistNodeStat - retrieve data fields from a libcsc list entry (node) SYNOPSYS #include "libcsc.h" int CSClistNodeStat ( CSClistNodeType const node, void** const itemPtrPtr, size_t* const itemSizePtr ); RETURN VALUE CSClistNodeStat(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSClistNodeStat() retrieves the relevant values of a list entry (node). If `itemPtrPtr' is not NULL, then entry's (node's) data pointer is written to the void pointer that is pointed to by `itemPtrPtr'. If `itemSizePtr' is not NULL, then entry's (node's) data size is written to the size_t that is pointed to by `itemSizePtr'. If both itemPtrPtr and itemSizePtr are NULL, then CSClistNodeStat() doesn't do anything very interesting. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistNodeValidate(3) NAME CSClistNodeValidate - verify an entry (node) is really in a libcsc list SYNOPSYS #include "libcsc.h" int CSClistNodeValidate ( CSClistType const list, CSClistNodeType const node ); RETURN VALUE CSClistNodeValidate(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSClistNodeValidate() looks up `node' in `list' to validate that `node' is actually in `list'. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistPeek(3) NAME CSClistPeek - retrieve data from entry at libcsc list head or tail SYNOPSYS #include "libcsc.h" int CSClistPeek ( CSClistType const list, CSClistBiasType bias, void** const itemPtrPtr, size_t* const itemSizePtr ); RETURN VALUE CSClistPeek(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSClistPeek() peeks at the head (newest) or tail (oldest) entry in `list' and retrieves the data pointer and size. When bias is: CSC_LIST_HEAD If `itemPtrPtr' is not NULL, then the data pointer from the list head (newest) entry is written to the void pointer that is pointed to by `itemPtrPtr'. If `itemSizePtr' is not NULL, then the data size from the list head (newest) entry is written to the size_t that is pointed to by `itemSizePtr'. CSC_LIST_TAIL If `itemPtrPtr' is not NULL, then the data pointer from the list tail (oldest) entry is written to the void pointer that is pointed to by `itemPtrPtr'. If `itemSizePtr' is not NULL, then the data size from the list tail (oldest) entry is written to the size_t that is pointed to by `itemSizePtr'. If both `itemPtrPtr' and `itemSizePtr' are NULL then CSClistPeek() doesn't do anything very interesting. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistPop(3) NAME CSClistPop - pop an entry from a libcsc list and retrieve its data SYNOPSYS #include "libcsc.h" int CSClistPop ( CSClistType const list, CSClistBiasType bias, void** const itemPtrPtr, size_t* const itemSizePtr ); RETURN VALUE CSClistPop(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSClistPop() pop the head (newest) or tail (oldest) entry from `list' depending upon the value of `bias'. Valid values of `bias': CSC_LIST_HEAD pop the head (newest) entry. CSC_LIST_TAIL pop the tail (oldest) entry. The entry is removed from `list', and its data is retrieved. If `itemPtrPtr' is not NULL, then the popped entry's data pointer is written to the void pointer that is pointed to by `itemPtrPtr'. NOTE If the retreived data was pushed into the list with the push type of CSC_DATA_DUP, then the retreived data is dynamically allocated (with malloc(), calloc(), etc.) and the caller is responsible for freeing (with free()) the retreived data. If `itemSizePtr' is not NULL, then the popped entry's data size is written to the size_t that is pointed to by `itemSizePtr'. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistPush(3) NAME CSClistPush - create a new entry and push it onto a libcsc list SYNOPSYS #include "libcsc.h" int CSClistPush ( CSClistType const list, CSCdataCntrlType push, const void* const itemPtr, size_t itemSize ); RETURN VALUE CSClistPush(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSClistPush() creates a libcsc list entry from `itemPtr' and `itemSize', and pushes it onto the list pointed to by `list'. `push' specifies how the client data pointed to by `itemPtr' is used: CSC_DATA_NODUP The new list entry simply copies the data pointer, `itemPtr', itself. If the data pointed to by `itemPtr' is dynamically allocated and is dellocated while the list entry has a pointer to it, then there will be an aliasing error and goblins will eat you. CSC_DATA_DUP The data pointed to by `itemPtr' is copied for `itemSize' bytes into a new dynamically allocated storage. The client code is responsible for deallocating the storage when the entry is popped from the list or there will be a memory leak, and you will have to tell your mother what you've done. Be careful of mixing push types CSC_DATA_NODUP and CSC_DATA_DUP in the same list; there may be no way for clients to later tell these entries apart from each other. CSClistDel() and CSClistNodeDel() should correctly deallocate data for entries with CSC_DATA_DUP push types. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistRead(3) NAME CSClistRead - read an ASCII format libcsc list SYNOPSYS #include "libcsc.h" int CSClistRead ( int fd, CSClistType const list ); RETURN VALUE CSClistRead(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSClistRead() reads from fd a libcsc list in ASCII format that was written with CSClistWrite(). `list' should be a CSClistType that is set to NULL; a new libcsc list will be created. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistSetCFunc(3) NAME CSClistSetCFunc - set a libcsc list entry data compare function SYNOPSYS #include "libcsc.h" int CSClistSetCFunc ( CSClistType const list, CSCcmpFnType funcptr ); RETURN VALUE CSClistSetCFunc(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSClistSetCFunc() sets the client-specified compare function `list'. The client-specified compare function is used by the libcsc list find functions CSClistNodeFindByValue() and CSClistNodeFindByReference(). `funcptr' is a function pointer pointer for a libcsc CSCcmpFnType function that is called from the libcsc list find functions CSClistNodeFindByValue() and CSClistNodeFindByReference(). The prototype for `funcptr' is: int (*CSCcmpFnType) (void*, void*); The client callback function `funcptr, is called with client supplied data and a list entry data pointer. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistStat(3) NAME CSClistStat - retrieve libcsc list statistics SYNOPSYS #include "libcsc.h" int CSClistStat ( CSClistType const list, size_t* const pushCountPtr, size_t* const popCountPtr, size_t* const maxAllocPtr, size_t* const curAllocPtr ); RETURN VALUE CSClistStat(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSClistStat() returns some statistics from `list'. If `pushCountPtr' is not NULL, then CSClistStat() writes the total of libcsc list pushes to the size_t that is pointed to by `pushCountPtr'. If `popCountPtr' is not NULL, then CSClistStat() writes the total of libcsc list pops to the size_t that is pointed to by `popCountPtr'. If `maxAllocPtr' is not NULL, then CSClistStat() writes the total count of bytes pushed to the size_t that is pointed to by `maxAllocPtr'. If `curAllocPtr' is not NULL, then CSClistStat() writes the current count of bytes in the libcsc list to the size_t that is pointed to by `curAllocPtr'. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistWrite(3) CSClistSetCFunc(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSClistWrite(3) NAME CSClistWrite - write a libcsc list in an ASCII format SYNOPSYS #include "libcsc.h" int CSClistWrite ( int fd, CSClistType const list ); RETURN VALUE CSClistWrite(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSClistWrite() writes to `fd' the libcsc list represented by the opaque `list' in an ASCII format. Small, simple lists will be human-readable by patient humans, but CSClistRead() will be happy to read it and create another duplicate libcsc list. In this way, libcsc lists can be transported between processes, in space or time. Caution: client pointers stored in the list will be severe aliasing bugs when they are read by a different process. SEE ALSO CSClistNew(3) CSClistDel(3) CSClistRead(3) CSClistSetCFunc(3) CSClistStat(3) CSClistPush(3) CSClistPop(3) CSClistPeek(3) CSClistNodeNext(3) CSClistNodeFindByValue(3) CSClistNodeFindByReference(3) CSClistNodeStat(3) CSClistNodeValidate(3) CSClistNodeDel(3) ------------------------------------------------------------------------ CSCmemAlloc(3) NAME CSCmemAlloc - allocate memory (and keep thrack of it in memList) SYNOPSYS #include "libcsc.h" int CSCmemAlloc ( CSCmemListType const memList, void** const memPtrPtr, size_t itemCount, size_t itemSize, int tagData ); RETURN VALUE CSC_OK ......... successful RTS_NOMEM ...... if no memory can be dynamically allocated CSC_BADARG ..... memList or memPtrPtr is NULL or itemCount or itemSize is zero CSC_CORRUPT .... corruption is detected in memList and CSCmemAlloc() is compiled with DEBUG DESCRIPTION CSCmemAlloc() allocates memory; the number of bytes that are allocated is `itemCount' multiplied by `itemSize'. Multiple calls to CSCmemAlloc() can use the same `memList'; each allocated memory block will be put into `memList' and CSCmemFree() can be called with `memList' to free the block, or CSCmemListFree() can be called to free all the memory blocks in `memList'. NOTE `memList' must first be created with CSCmemInit(). If CSCmemAlloc() is compiled with DEBUG, then CSCmemAlloc() will fill newly allocated memory with some well-defined garbage to prevent the use of accidentally good values. `tagData' is provided for profiling `memList's. When profiling, `memList' continues to contain a record of the allocation and free of the memory; the list doesn't really get smaller (the actual memory allocations for client code are of course freed). `tagData' is an arbitrary integer that the caller supplies for easier identification when using CSCmemListPrintProfile() or CSCmemListWriteProfile() on `memList'. EXAMPLE CSCmemListType myList; void* myData; int mysize = 100; int myTag = 55; int stat; myList = CSCmemInit ("my data", NULL, NULL, NULL, CSC_DO_PROFILING); stat = CSCmemAlloc (myList, &myData, 1, mySize, myTag); . . . stat = CSCmemFree (myList, &myData, myTag); SEE ALSO CSCmemInit(3) CSCmemDone(3) CSCmemDup(3) CSCmemFree(3) CSCmemLookup(3) CSCmemValidate(3) CSCmemListFree(3) CSCmemListStat(3) CSCmemListPrintProfile(3) CSCmemListWriteProfile(3) ------------------------------------------------------------------------ CSCmemDone(3) NAME CSCmemDone - cleanup and remove a memList (free all its memory) SYNOPSYS #include "libcsc.h" int CSCmemDone (CSCmemListType const memList); RETURN VALUE CSC_OK ......... successful CSC_BADARG ..... memList is NULL CSC_CORRUPT .... corruption is detected in memList and CSCmemDone() is compiled with DEBUG DESCRIPTION CSCmemDone() unconditionally remves all memory blocks contained in `memList' and then removes `memList' itself. `memList' is not checked for profiling; no statistics for `memList' are retained. Do not try to use `memList' after calling CSCmemDone(), at least until using `memList' in another CSCmemInit(). If CSCmemDone() is compiled with DEBUG, then the memory is shredded by writing well-defined garbage to it before it is freed. This avoids code that accidentally works by using deallocated memory that hasn't yet changed. SEE ALSO CSCmemInit(3) CSCmemAlloc(3) CSCmemDup(3) CSCmemLookup(3) CSCmemValidate(3) CSCmemFree(3) CSCmemListFree(3) CSCmemListStat(3) CSCmemListPrintProfile(3) CSCmemListWriteProfile(3) ------------------------------------------------------------------------ CSCmemDup(3) NAME CSCmemDup - duplicate (dynamically allocate and copy) memory SYNOPSYS #include "libcsc.h" int CSCmemDup ( CSCmemListType const memList, void** const dstPtrPtr, const void* srcPtr, size_t size, int tagData ); RETURN VALUE CSC_OK ......... successful, the memory pointed to by memPtr is duplicated CSC_BADARG ..... memList, dstPtrPtr, or srcPtr is NULL or size is zero CSC_CORRUPT .... corruption is detected in memList and CSCmemDup() is compiled with DEBUG DESCRIPTION CSCmemDup() dynamically allocates `size' bytes and copies `size' bytes from `srcPtr' into the newly allocated memory. `tagData' is provided for profiling `memList's. When profiling, `memList' continues to contain a record of the allocation and free of the memory; the list doesn't really get smaller (the actual memory allocations for client code are of course freed). `tagData' is an arbitrary integer that the caller supplies for easier identification when using CSCmemListPrintProfile() or CSCmemListWriteProfile() on the `memList'. `srcPtr' can point to any readable memory. This may be usefull for creating dynamic duplicates of constant strings, etc. EXAMPLE CSCmemListType myList; void* myData; int stat; myList = CSCmemInit ("my data", NULL, NULL, NULL, CSC_DO_PROFILING); . . . stat = CSCmemDup (myList, &myData, "duplicate this string", 22, myTag); SEE ALSO CSCmemInit(3) CSCmemDone(3) CSCmemAlloc(3) CSCmemFree(3) CSCmemLookup(3) CSCmemValidate(3) CSCmemListFree(3) CSCmemListStat(3) CSCmemListPrintProfile(3) CSCmemListWriteProfile(3) ------------------------------------------------------------------------ CSCmemFree(3) NAME CSCmemFree - free dynamically allocated memory SYNOPSYS #include "libcsc.h" int CSCmemFree ( CSCmemListType const memList, void** const memPtrPtr, int tagData ); RETURN VALUE CSC_OK ......... successful, memPtr was found in memList, and the memory pointed to by memPtr is freed CSC_NOTFOUND ... memPtr not found in memList, or memList has no allocated blocks CSC_BADARG ..... memList or memPtrPtr is NULL CSC_CORRUPT .... corruption is detected in memList and CSCmemFree() is compiled with DEBUG DESCRIPTION CSCmemFree() frees the dynamically allocated memory whose address is pointed to by `memPtr'. The memory to be freed is checked and validated in `memList'. If it is not found in `memList', then no memory is freed. Because of the `memList' usage, don't use CSCmemFree() on memory you got from malloc(), calloc(), etc. If CSCmemFree() is compiled with DEBUG, then the memory is shredded by writing well-defined garbage to it before it is freed. This avoids code that accidentally works by using deallocated memory that hasn't yet changed. `tagData' is provided for profiling `memList's. When profiling, `memList' continues to contain a record of the allocation and free of the memory; the list doesn't really get smaller (the actual memory allocations for client code are of course freed). `tagData' is an arbitrary integer that the caller supplies for easier identification when using CSCmemListPrintProfile() or CSCmemListWriteProfile() on the `memList'. EXAMPLE CSCmemListType myList; void* myData; int mysize = 100; int myTag = 55; int stat; myList = CSCmemInit ("my data", NULL, NULL, NULL, CSC_DO_PROFILING); stat = CSCmemAlloc (myList, &myData, 1, mySize, myTag); . . . stat = CSCmemFree (myList, &myData, myTag); SEE ALSO CSCmemInit(3) CSCmemDone(3) CSCmemAlloc(3) CSCmemDup(3) CSCmemLookup(3) CSCmemValidate(3) CSCmemListFree(3) CSCmemListStat(3) CSCmemListPrintProfile(3) CSCmemListWriteProfile(3) ------------------------------------------------------------------------ CSCmemInit(3) NAME CSCmemInit - initialize a csc memlist for subsequent memory allocations SYNOPSYS #include "libcsc.h" CSCmemListType CSCmemInit ( const char* name, CSCtagFnType tagFunc, CSCmonFnType monFunc, void* monData, CSCprofileType profiling ); RETURN VALUE If successful CSCmemInit() returns a newly created csc memlist; otherwise, when unsuccessful CSCmemInit() returns NULL. DESCRIPTION CSCmemInit() creates and returns a csc memlist. A csc memlist is needed to allocate and free memory using the csc memory subsystem. The csc memory subsystem records statistics on its allocate and free activities into csc memlists. The csc memory subsystem also uses the csc memlist to help detect memory leaks and other misuses. Memory allocated with a given csc memlist must be freed with the same csc memlist. NOTE No arguments are copied; the string pointed to by `name' (if not NULL) and the client data pointed to by `monData' (if not NULL) are *NOT* copied. The client is responsible for ensuring that the data are valid until the csc memlist itself is freed by CSCmemListFree(). `name' can be NULL, but it should point to a descriptive string. The string is printed when the csc memlist profile is printed. `tagFunc' can be NULL. When it is not NULL, it is used as a callback function during the printing of a csc memlist profile to retreive a (descriptive) string associated with the integer tag given when memory was allocated/freed. This helps to identified memory that has not been freed (leaked). `monFunc' and `monData': The csc memory subsystem makes no assumptions about the threading environment, or even if the environment is threaded or not. It is the caller's (client's) responsibility to provide mutual exclusion locking for the csc memory subsystem. This allows the csc memory subsystem to function in multiple environments. `monFunc' is used to provide mutual exclusion locking for thread safty. If a proper modFunc is provided, then multiple threads may share a given csc memlist to allocate and free memory. `monFunc' is a callback function used to enter and exit the critical regions when updating the csc memlist. `monFunc' is invoked with the the client's `monData'; the calback function should enforce locking (mutex). `monFunc' is invoked with CSC_IO_IN and `monData' when entering a critical region an it is invoked with CSC_IO_OUT and `monData' when exiting a critical region. `monData' is provided so that the client can have it point to the necessary mutex (and/or whatever) and the csc memory subsystem delivers it to the callback. In this way the client does not otherwise have to keep track of the mutex. If the environment is not threaded, and no mutex is needed, then `monFunc' should be NULL. `profiling' specifies whether alocate/free statistics should actually be generated and kept in the csc memlist. SEE ALSO CSCmemDone(3) CSCmemAlloc(3) CSCmemDup(3) CSCmemFree(3) CSCmemLookup(3) CSCmemValidate(3) CSCmemListFree(3) CSCmemListStat(3) CSCmemListPrintProfile(3) CSCmemListWriteProfile(3) ------------------------------------------------------------------------ CSCmemListFree(3) NAME CSCmemListFree - free all memory allocated in a memList SYNOPSYS #include "libcsc.h" int CSCmemListFree ( CSCmemListType const memList, int tagData ); RETURN VALUE CSC_OK ......... successful CSC_NOTFOUND ... memList has no allocated blocks CSC_BADARG ..... memList is NULL CSC_CORRUPT .... corruption is detected in memList and CSCmemListFree() is compiled with DEBUG DESCRIPTION CSCmemListFree() frees all the memory described by `memList'. This is memory allocations for client code that was allocated by using `memList' with functions like CSCmemAlloc(). The actual `memList' itself is not freed. CSCmemListFree() is a convenient mechanism to free many allocations of memory with a single function. `tagData' is provided for profiling `memList's. When profiling, the `memList' continues to contain a record of the allocation and free of the memory; the list doesn't really get smaller (the actual memory allocations for client code are of course freed). `tagData' is an arbitrary integer that the caller supplies for easier identification when using CSCmemListPrintProfile() or CSCmemListWriteProfile() on the `memList'. SEE ALSO CSCmemInit(3) CSCmemDone(3) CSCmemAlloc(3) CSCmemDup(3) CSCmemFree(3) CSCmemLookup(3) CSCmemValidate(3) CSCmemListStat(3) CSCmemListPrintProfile(3) CSCmemListWriteProfile(3) ------------------------------------------------------------------------ CSCmemListPrintProfile(3) NAME CSCmemListPrintProfile - write a memlist profile to standard output SYNOPSYS #include "libcsc.h" int CSCmemListPrintProfile ( CSCmemListType const memList, CSCprofileType showing ); RETURN VALUE CSC_OK ........ successful CSC_BADARG .... memList is NULL CSC_CORRUPT ... corruption is detected in memList and CSCmemListWriteProfile() is compiled with DEBUG DESCRIPTION CSCmemListPrintProfile() writes to standard output the information of the dynamically allocated memory blocks that are described in `memList'. CSCmemListPrintProfile() calls CSCmemListWriteProfile() to do the work; so, go read about CSCmemListWriteProfile(). SEE ALSO CSCmemInit(3) CSCmemDone(3) CSCmemAlloc(3) CSCmemDup(3) CSCmemFree(3) CSCmemLookup(3) CSCmemValidate(3) CSCmemListFree(3) CSCmemListStat(3) CSCmemListWriteProfile(3) ------------------------------------------------------------------------ CSCmemListStat(3) NAME CSCmemListStat - get information about a memList SYNOPSYS #include "libcsc.h" int CSCmemListStat ( CSCmemListType const memList, size_t* const allocCountPtr, size_t* const freeCountPtr, size_t* const maxMemAllocPtr, size_t* const curMemAllocPtr ); RETURN VALUE CSC_OK ............. successful CSC_NO_PROFILING ... memList is not profiling CSC_BADARG ......... memList is NULL CSC_CORRUPT ........ corruption is detected in memList and CSCmemListStat() is compiled with DEBUG DESCRIPTION CSCmemListStat() can return the allocate count, free count, current allocating, and highest allocation from `memList', if `memList' was specified when it was created by CSCmemInit() to be profiling. When profiling: If `allocCountPtr' is not NULL, then CSCmemListStat() writes to the size_t pointed to by `allocCountPtr' the total number of allocates. If `freeCountPtr' is not NULL, then CSCmemListStat() writes to the size_t pointed to by `freeCountPtr' the total number of frees. If `maxMemAllocPtr' is not NULL, then CSCmemListStat() writes to the size_t pointed to by `maxMemAllocPtr' the number of bytes ever allocated at one time. If `curMemAllocPtr' is not NULL, then CSCmemListStat() writes to the size_t pointed to by `curMemAllocPtr' the number of currently allocated bytes. CSCmemListStat() can be used to determine if `memList' is profiling by using NULL for all of `allocCountPtr', `freeCountPtr', `maxMemAllocPtr', and `curMemAllocPtr'. CSC_NO_PROFILING is returned if `memList' is not profiling and CSC_OK is returned if `memList' is profiling. SEE ALSO CSCmemInit(3) CSCmemDone(3) CSCmemAlloc(3) CSCmemDup(3) CSCmemFree(3) CSCmemLookup(3) CSCmemValidate(3) CSCmemListFree(3) CSCmemListPrintProfile(3) CSCmemListWriteProfile(3) ------------------------------------------------------------------------ CSCmemListWriteProfile(3) NAME CSCmemListWriteProfile - write a memlist profile to a file descriptor SYNOPSYS #include "libcsc.h" int CSCmemListWriteProfile ( CSCmemListType const memList, int fd, CSCprofileType showing ); RETURN VALUE CSC_OK ........ successful CSC_BADARG .... memList is NULL CSC_CORRUPT ... corruption is detected in memList and CSCmemListWriteProfile() is compiled with DEBUG DESCRIPTION CSCmemListWriteProfile() writes to `fd' the information of the dynamically allocated memory blocks that are described in `memList'. Use CSCmemListWriteProfile() and CSCmemListPrintProfile() to verify that there are no memory leaks. This information written by CSCmemListWriteProfile() begins with a header of the name, tag function, monitor function, and profiling as specified when `memList' was created by CSCmemInit(). If `memList' was specified when it was created by CSCmemInit() to be profiling, then the allocate count, free count, current allocating, and highest allocation are included in the header information. If `showing' is CSC_SHOW_ALL, then a list of allocationed/freeed blocks follows the header. The unfreed memory allocations are described by data address, size, and the allocate tag provided by the client code that called CSCmemAlloc(). If `memList' was specified to be profiling, then freed memory alocations remain in the list. In this case they will be included in this list of information but there is no data address and size, only an allocate tag and a free tag. If `showing' is CSC_SHOW_ALLOCATED, then only allocated blocks are shown. SEE ALSO CSCmemInit(3) CSCmemDone(3) CSCmemAlloc(3) CSCmemDup(3) CSCmemFree(3) CSCmemLookup(3) CSCmemValidate(3) CSCmemListFree(3) CSCmemListStat(3) CSCmemListPrintProfile(3) ------------------------------------------------------------------------ CSCmemLookup(3) NAME CSCmemLookup - lookup a memory pointer in memList SYNOPSYS #include "libcsc.h" int CSCmemLookup ( CSCmemListType const memList, const void* memPtr, size_t* const sizePtr, int* const tagPtr ); RETURN VALUE CSC_OK ......... successful, memPtr was found in memList CSC_NOTFOUND ... memPtr not found in memList, or memList has no allocated blocks CSC_BADARG ..... memList or memPtr is NULL CSC_CORRUPT .... corruption is detected in memList and CSCmemLookup() is compiled with DEBUG DESCRIPTION CSCmemLookup() looks up `memPtr' in `memList' to validate it, and if found returns its statistics: size of the data block pointer to by `memPtr' and the tag that was used to allocate the block of memory pointed to by `memPtr'. If `sizePtr' is not NULL, then the size of the allocated memory block pointed to by `memPtr' is written to the size_t pointed to by `sizePtr'. If `tagPtr' is not NULL, then the tag that was used to allocate the block of memory pointed to by `memPtr' is written to the int pointed to by `tagPtr'. Either, or both, of `sizePtr' and `tagPtr' can be NULL. If both are NULL, then CSCmemLookup() pretty much acts like CSCmemValidate(). SEE ALSO CSCmemInit(3) CSCmemDone(3) CSCmemAlloc(3) CSCmemDup(3) CSCmemFree(3) CSCmemValidate(3) CSCmemListFree(3) CSCmemListStat(3) CSCmemListPrintProfile(3) CSCmemListWriteProfile(3) ------------------------------------------------------------------------ CSCmemValidate(3) NAME CSCmemValidate - validate that a memory pointer is in memList SYNOPSYS #include "libcsc.h" int CSCmemValidate ( CSCmemListType const memList, const void* memPtr ); RETURN VALUE CSC_OK ......... successful, memPtr was found in memList CSC_NOTFOUND ... memPtr not found in memList, or memList has no allocated blocks CSC_BADARG ..... memList is or memPtr NULL CSC_CORRUPT .... corruption is detected in memList and CSCmemValidate() is compiled with DEBUG DESCRIPTION CSCmemValidate() looks up `memPtr' in `memList' to validate it. SEE ALSO CSCmemInit(3) CSCmemDone(3) CSCmemAlloc(3) CSCmemDup(3) CSCmemFree(3) CSCmemLookup(3) CSCmemListFree(3) CSCmemListStat(3) CSCmemListPrintProfile(3) CSCmemListWriteProfile(3) ------------------------------------------------------------------------ CSCnotificationBoardDel(3) NAME CSCnotificationBoardDel - completely remove a notification board SYNOPSYS #include "libcsc.h" int CSCnotificationBoardDel ( CSCnotificationBoardType const board ); RETURN VALUE CSCnotificationBoardDel(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSCnotificationBoardDel() deletes the notification `board' including all the notification entries it contains. SEE ALSO CSCnotificationBoardNew(3) CSCnotificationBoardPrint(3) CSCnotificationNew(3) CSCnotificationDel(3) CSCnotificationPost(3) CSCnotificationRegister(3) ------------------------------------------------------------------------ CSCnotificationBoardNew(3) NAME CSCnotificationBoardNew - create a new notification board SYNOPSYS #include "libcsc.h" CSCnotificationBoardType CSCnotificationBoardNew ( const char* name, CSCmonFnType monFunc, const void* monData, CSCprofileType profiling ); RETURN VALUE CSCnotificationBoardNew(), if successful, returns an opaque data type representing a new libcsc notification board, or NULL if otherwise not successful. DESCRIPTION CSCnotificationBoardNew() creates a new libcsc notification board. A notification board is simply something to hold an arbitrary number of notifications (like a cork note board). `profiling' can be CSC_DO_PROFILING or CSC_NO_PROFILING; it specifies whether alocate/free statistics should actually be generated and kept in the list. SEE ALSO CSCnotificationBoardDel(3) CSCnotificationBoardPrint(3) CSCnotificationNew(3) CSCnotificationDel(3) CSCnotificationPost(3) CSCnotificationRegister(3) ------------------------------------------------------------------------ CSCnotificationBoardPrint(3) NAME CSCnotificationBoardPrint - print a notification board in ASCII format SYNOPSYS #include "libcsc.h" void CSCnotificationBoardPrint ( CSCnotificationBoardType const board ); RETURN VALUE CSCnotificationBoardPrint() has no return value. DESCRIPTION CSCnotificationBoardPrint() prints to standard output the libcsc notification board represented by the opaque `board' in an ASCII format. BUGS There is no error check in this function. Lame. SEE ALSO CSCnotificationBoardNew(3) CSCnotificationBoardDel(3) CSCnotificationNew(3) CSCnotificationDel(3) CSCnotificationPost(3) CSCnotificationRegister(3) ------------------------------------------------------------------------ CSCnotificationDel(3) NAME CSCnotificationDel - delete a notification from a board SYNOPSYS #include "libcsc.h" int CSCnotificationDel ( CSCnotificationBoardType const board, const char* name ); RETURN VALUE CSCnotificationDel(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSCnotificationDel() looks in the notification `board' for the notification entry whose name matches `name' and deletes it. BUGS Any clients registered for the particular notification being deleted will NOT be notified. SEE ALSO CSCnotificationBoardNew(3) CSCnotificationBoardDel(3) CSCnotificationBoardPrint(3) CSCnotificationNew(3) CSCnotificationPost(3) CSCnotificationRegister(3) ------------------------------------------------------------------------ CSCnotificationNew(3) NAME CSCnotificationNew - create a new notification in a board SYNOPSYS #include "libcsc.h" int CSCnotificationNew ( CSCnotificationBoardType const board, const char* name, CSCgenFnType errfn ); RETURN VALUE CSCnotificationNew(), if successful, CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSCnotificationNew() creates a new notification entry and puts it into notification `board'. `name' points to the character string that names the new notification entry. `errfn' is a pointer to a libcsc CSCgenFnType function that is called when a call to `post' a notification, CSCnotificationPost() (which tries to distribute the notification), results in an an error. The prototype for `errfn' is: int (*CSCgenFnType) (int, int, void*); The client callback error function `errfn' is called with the current notification count and notification `name'; its return value is ignored: (void)((*errfn) (0, count, name); SEE ALSO CSCnotificationBoardNew(3) CSCnotificationBoardDel(3) CSCnotificationBoardPrint(3) CSCnotificationDel(3) CSCnotificationPost(3) CSCnotificationRegister(3) ------------------------------------------------------------------------ CSCnotificationPost(3) NAME CSCnotificationPost - post to a notification in a board SYNOPSYS #include "libcsc.h" int CSCnotificationPost ( CSCnotificationBoardType const board, const char* name ); RETURN VALUE CSCnotificationPost(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSCnotificationPost() dispatches all client functions registered for particular notification `name' in notification `board'. As the dispatched client functions are called they should return CSC_OK or CSC_NOTOUND. If CSC_NOTFOUND is returned by a client function, then no more client functions registered for the notification are called for the particular notification action and and the notification's error function, pointed to by errfn, is called. The error function, pointed to by errfn, is associated with the notification entry when the notification entry is created. The error function's return value is ignored. The client functions are called in the order of their priority, which they specify with the tag value when they register. Client functions are libcsc CSCgenFnType types; their prototype is: int (*CSCgenFnType) (int, int, void*); The client functions are called with a notification count, client-specified integer tag (used as the priority specifying the order in which the client functions are called), and client-specified data (with which they register): (*fn) (count, tag, data); SEE ALSO CSCnotificationBoardNew(3) CSCnotificationBoardDel(3) CSCnotificationBoardPrint(3) CSCnotificationNew(3) CSCnotificationDel(3) CSCnotificationRegister(3) ------------------------------------------------------------------------ CSCnotificationRegister(3) NAME CSCnotificationRegister - register client function to a notification SYNOPSYS #include "libcsc.h" int CSCnotificationRegister ( CSCnotificationBoardType const board, const char* notifName, const char* clientName, CSCgenFnType fn, const CSCboolean* runFlag, int tag, const void* data ); RETURN VALUE CSCnotificationRegister(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSCnotificationRegister() registers the client function pointed to by `fn' with the notification entry named by `notifName' in the notification board associated with `board'. Client functions are libcsc CSCgenFnType types; their prototype is: int (*CSCgenFnType) (int, int, void*); The client functions are called with a notification count, client-specified integer tag, and client-specified data (with which they register): (*fn) (count, tag, data); Client functions should return CSC_OK or CSC_NOTOUND. If CSC_NOTFOUND is returned by a client function, then no more client functions registered for the notification are called for the particular notification action, and and the notification's error function, pointed to by errfn, is called. The error function, pointed to by errfn, is associated with the notification entry when the notification entry is created. The error function's return value is ignored. `clientName' is used only for debug messages and notification board printing. When the notification named `notifName' is posted to, the function pointed to by `fn' is called. `tag' and `data' are returned to the client as arguments to the client function `fn'. All client functions registered to a notification are called in order of their priority. `tag' is used as the priority; all the client functions registered to a notification are called in the numerical value order of their tag. The client can dynamically control the calling of its registered function; if the value at `runFlag' is CSC_FALSE when the notification is posted to, then the registered client function will not be called. SEE ALSO CSCnotificationBoardNew(3) CSCnotificationBoardDel(3) CSCnotificationBoardPrint(3) CSCnotificationNew(3) CSCnotificationDel(3) CSCnotificationPost(3) ------------------------------------------------------------------------ CSCsockConnectUDP(3) NAME CSCsockConnectUDP - initiate a socket connection SYNOPSYS #include "libcsc.h" int CSCsockConnectUDP ( int* const socketPtr, const char* host, const char* service, CSCgenFnType errorCallback ); RETURN VALUE CSC_OK .......... successful, and the integer pointed to by socketPtr will be updated with the new socket descriptor CSC_NOTFOUND .... can't make sense of host CSC_NOSVC ....... can't make sense of service CSC_NOPROT ...... can't make any sense out of the UDP protocol CSC_NOSOCK ...... can't allocate a new socket or can't set a socket option CSC_BADARG ...... socketPtr or service is NULL or connectCount is zero DESCRIPTION CSCsockConnectUDP() attempts to create a PF_INET (IPv4) protocol socket and make a UDP (SOCK_DGRAM) connection to another socket. The other socket to which to connect is expected to be on `host' and `service', where `host' is the hostname or IP address, and `service' is the service or port number. If `service' specifies port number, then the integer value must fit in an unsigned 16 bit variable (0 <= sevice <= 65535). For example: host service ---- ------- "batman" "telnet" "spidergirl" "5200" "198.168.0.2" "finger" "198.168.0.2" "5200" Error conditions are announced via `errorCallback', if it is not NULL. The `errorCallback' function is called with the CSCsockConnectUDP() return value, errno, and a string describing the error e.g., (*errorCallback) (CSC_NOSOCK, errno, "can't create socket"); BUGS There's no "connection" in UDP! CSCsockConnectUDP() probably shouldn't call connect() to make a connection. SEE ALSO CSCsockConnectTCP(3) CSCsockPassiveTCP(3) CSCsockPassiveUDP(3) ------------------------------------------------------------------------ CSCsockPassiveTCP(3) NAME CSCsockPassiveTCP - listen for connections on a socket SYNOPSYS #include "libcsc.h" int CSCsockPassiveTCP ( int* const socketPtr, const char* service, int connectCount, CSCgenFnType errorCallback ); RETURN VALUE CSC_OK .......... successful, and the integer pointed to by socketPtr will be updated with the new socket descriptor CSC_NOSVC ....... can't make sense of service CSC_NOPROT ...... can't make any sense out of the UDP protocol CSC_NOSOCK ...... can't allocate a new socket or can't set a socket option CSC_NOBIND ...... can't bind socket to service CSC_NOLISTEN .... can't listen to socket CSC_BADARG ...... socketPtr or service is NULL or connectCount is zero DESCRIPTION CSCsockPassiveTCP() attempts to create a PF_INET (IPv4) protocol socket and prepares it to accept TCP (SOCK_STREAM) connections. No accept() is actually tried, this must be done after calling CSCsockPassiveTCP(). If successful, CSCsockPassiveTCP() creates a socket that is prepared to accept a connection from any IP. The `service' argument is a string that represents the the service (see /etc/services) or port number. If `service' specifies port number, then the integer value must fit in an unsigned 16 bit variable (0 <= sevice <= 65535). For example: service ------- "echo" "5200" "fsp" "7200" The socket is set with the SO_REUSEADDR option to enable quick reuse of the same port. `connectCount' is the connection backlog (the number of allowed concurrent connections). Error conditions are announced via `errorCallback', if it is not NULL. The `errorCallback' function is called with the CSCsockPassiveUDP() return value, errno, and a string describing the error e.g., (*errorCallback) (CSC_NOSOCK, errno, "can't create socket"); BUGS Cannot select a desired host from which to accept a connection. SEE ALSO CSCsockConnectTCP(3) CSCsockConnectUDP(3) CSCsockPassiveUDP(3) ------------------------------------------------------------------------ CSCsockPassiveUDP(3) NAME CSCsockPassiveUDP - listen for connections on a socket SYNOPSYS #include "libcsc.h" int CSCsockPassiveUDP ( int* const socketPtr, const char* service, int connectCount, CSCgenFnType errorCallback ); RETURN VALUE CSC_OK .......... successful, and the integer pointed to by socketPtr will be updated with the new socket descriptor CSC_NOSVC ....... can't make sense of service CSC_NOPROT ...... can't make any sense out of the UDP protocol CSC_NOSOCK ...... can't allocate a new socket or can't set a socket option CSC_NOBIND ...... can't bind socket to service CSC_NOLISTEN .... can't listen to socket CSC_BADARG ...... socketPtr or service is NULL or connectCount is zero DESCRIPTION CSCsockPassiveUDP() attempts to create a PF_INET (IPv4) protocol socket and prepares it to accept UDP (SOCK_DGRAM) connections. If successful, CSCsockPassiveUDP() creates a socket that is prepared to accept a datagrams from any IP. The `service' argument is a string that represents the the service (see /etc/services) or port number. If `service' specifies port number, then the integer value must fit in an unsigned 16 bit variable (0 <= sevice <= 65535). For example: service ------- "echo" "5200" "fsp" "7200" The socket is set with the SO_REUSEADDR option to enable quick reuse of the same port. `connectCount' is the connection backlog (the number of allowed concurrent connections). Error conditions are announced via `errorCallback', if it is not NULL. The `errorCallback' function is called with the CSCsockPassiveUDP() return value, errno, and a string describing the error e.g., (*errorCallback) (CSC_NOSOCK, errno, "can't create socket"); BUGS There's no "connection" in UDP! This function should be re-coded to remove the TCPisms. I think this function has never been used. SEE ALSO CSCsockConnectTCP(3) CSCsockConnectUDP(3) CSCsockPassiveTCP(3) ------------------------------------------------------------------------ CSCstatStr(3) NAME CSCstatStr - get string describing libcsc function return value SYNOPSYS #include "libcsc.h" const char* CSCstatStr (int status); DESCRIPTION Most libcsc functions return an integer status; this integer status is passed as the `status' argument to CSCstatStr(). CSCstatStr() returns a pointer to a constant ASCII-Z string containing the text describing `status'. SEE ALSO CSCcflags(3) CSCldflags(3) CSClibs(3) CSCversion(3) CSCcredits(3) CSCchkup(3) ------------------------------------------------------------------------ CSCstringBasename(3) NAME CSCstringBasename - strip directory from a filename SYNOPSYS #include "libcsc.h" char* CSCstringBasename ( char** const pathPtrPtr ); RETURN VALUE CSCstringBinary() returns a pointer to the filename component of the pathname at *pathPtrPtr, if successful. Otherwise, CSCstringBinary() returns NULL, particularly if pathPtrPtr, or *pathPtrPtr is NULL. DESCRIPTION CSCstringBinary() finds the first character after the last '/' character in the pathname pointed to by *pathPtrPtr. The last '/' character in the original string is replace will a NULL character. If the original pathname pointed to by *pathPtrPtr contains no '/' character, then CSCstringBinary() returns *pathPtrPtr, and sets *pathPtrPtr to be a pointer to the string "." (the current directory). EXAMPLE char* pathname = "just.a.file.name"; file = CSCstringBasename (&pathname); // Now we have: // file = "just.a.file.name" // pathname = "." char* pathname = "path/file"; file = CSCstringBasename (&pathname); // Now we have: // file = "file" ----v // pathname = "path\0file" BUGS If the original string has a '/' character, then that character gets set to '\0'; don't try this on components of argv and other strings that might not be writable. SEE ALSO CSCstringOctal(3) CSCstringBinary(3) ------------------------------------------------------------------------ CSCstringBinary(3) NAME CSCstringBinary - format an ASCII string to represent a binary number SYNOPSYS #include "libcsc.h" char* CSCstringBinary ( char* const bufPtr, int32 item ); RETURN VALUE CSCstringBinary() always returns bufPtr. DESCRIPTION If `bufPtr' is not NULL, then the integer value of `item', in binary, is written to bufPtr with a preceding "0b" and is represented in 32 bits with the preceding two "0b" characters and terminating '\0' for a total of 35 characters. EXAMPLE char* buf[35]; // no smaller! and bigger is a waste. int32 i = 72; (void)CSCstringBinary (buf, i); // // Now: buf = "0b0000000001001000" BUGS Beware buffer overflows; they are your responsibility. SEE ALSO CSCstringOctal(3) CSCstringBasename(3) ------------------------------------------------------------------------ CSCstringOctal(3) NAME CSCstringOctal - format an ASCII string to represent an octal number SYNOPSYS #include "libcsc.h" char* CSCstringOctal ( char* const bufPtr, int32 item ); RETURN VALUE CSCstringOctal() always returns bufPtr. DESCRIPTION If `bufPtr' is not NULL, then the integer value of `item', in octal, is written to bufPtr with a preceding "0o" and is represented in 11 octets with the preceding two "0o" characters and terminating '\0' for a total of 14 characters. EXAMPLE char* buf[14]; // no smaller! and bigger is a waste. int32 i = 72; (void)CSCstringOctal (buf, i); // // Now: buf = "0o00000000110" BUGS Beware buffer overflows; they are your responsibility. SEE ALSO CSCstringBinary(3) CSCstringBasename(3) ------------------------------------------------------------------------ CSCsymbolDel(3) NAME CSCsymbolDel - remove a libcsc symbol table SYNOPSYS #include "libcsc.h" int CSCsymbolDel ( CSCsymbolType** const symPtrPtr, CSCmemListType const memList, int memTag ); RETURN VALUE CSC_OK ....... successful CSC_BADARG ... symPtrPtr or memList is NULL CSC_ERROR .... other errors DESCRIPTION CSCsymbolDel() deletes the symbol whose pointer is pointed to by `symPtrPtr'. If the symbol was created by CSCsymbolFloatInit(), CSCsymbolIntInit(), CSCsymbolPtrInit(), or otherwise does not have a dynamically allocated name, then there will be some complaints (crashes? heap corruption?) when the name field is freed. HINT If the symbol's valueFlag field is set to 1, 2 or 3, then the name field is deallocated. If the symbol's valueFlag field is set to 3, then the value.pointer field is also deallocated. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) ------------------------------------------------------------------------ CSCsymbolDup(3) NAME CSCsymbolDup - dynamically allocate and duplicate a symbol SYNOPSYS #include "libcsc.h" CSCsymbolType* CSCsymbolDup ( const CSCsymbolType* const symPtr, CSCmemListType const memList, int memTag ); RETURN VALUE CSCsymbolDup(), if successful, returns a pointer to the newly created symbol, otherwise NULL is returned. DESCRIPTION CSCsymbolDup() dynamically allocates a symbol structure and copies the symbol pointed to by `symPtr' into the new symbol. The symbol's name is also dynamically allocated and copied. To free the newly created symbol's memory, the name field and the symbol structure itself must be freed; use the appropriate CSCsymbol*Del() function. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolFloatDel(3) NAME CSCsymbolFloatDel - delete a floating point symbol SYNOPSYS #include "libcsc.h" int CSCsymbolFloatDel ( CSCsymbolType** const symPtrPtr, CSCmemListType const memList, int memTag ); RETURN VALUE CSC_OK ....... successful CSC_BADARG ... symPtrPtr or memList is NULL CSC_ERROR .... other errors DESCRIPTION CSCsymbolFloatDel() removes the floating point symbol whose pointer is pointed to by `symPtrPtr'. BUGS The name field of the symbol structure is a character pointer and CSCsymbolFloatDel() tries to deallocate it; therefore, don't create a symbol with a statically allocated name. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolFloatInit(3) NAME CSCsymbolFloatInit - initialize a floating point symbol SYNOPSYS #include "libcsc.h" int CSCsymbolFloatInit ( CSCsymbolType* const symbol, const char* const symName, long symType, float symVal ); RETURN VALUE CSC_OK ........ successful CSC_BADARG .... symbol or symName is equal to NULL DESCRIPTION CSCsymbolFloatInit() initializes the symbol pointed to by `symbol' with `symName', `symType', and `symVal'. Client code probably should use the same `symType' value for all floating point symbols, and `symName' probably should be the ASCII string equivalent of `symVal'. BUGS The pointer `symName' is copied into the symbol structure; therefore, if `symName' is subsequently freed, then the newly initialized symbol will have an aliasing error (pointer to freed memory). And remember: CSCsymbolFloatDel() will try to deallocate the name, so it won't be happy if the name was not dynamically allocated. HINT The symbol's valueFlag field is set to 2. SEE ALSO CSCsymbolIntInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolFloatNew(3) NAME CSCsymbolFloatNew - allocate and initialize a floating point symbol SYNOPSYS #include "libcsc.h" CSCsymbolType* CSCsymbolFloatNew ( const char* const symName, long symType, float symVal, CSCmemListType const memList, int memTag ); RETURN VALUE CSCsymbolFloatNew() returns a pointer to the newly allocated symbol, if successful; otherwise, NULL is returned. DESCRIPTION CSCsymbolFloatNew() dynamically allocates a new symbol structure and fills it in with `symName', `symType', and `symVal'. Client code probably should use the same `symType' value for all floating point symbols, and `symName' probably should be the ASCII string equivalent of `symVal'. HINTS Memory for the new symbol's name is allocated and `symName' is copied in to it, so client code can immediately free `symName' upon returning from CSCsymbolFloatNew(). The symbol's valueFlag field is set to 2. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolFloatWrite(3) NAME CSCsymbolFloatWrite - write a floating point symbol in ASCII format SYNOPSYS #include "libcsc.h" int CSCsymbolFloatWrite ( const int fd, const CSCsymbolType* const symPtr ); RETURN VALUE CSC_OK ....... always DESCRIPTION CSCsymbolFloatWrite() writes to fd the fields of the symbol in an ASCII format. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolIntDel(3) NAME CSCsymbolIntDel - delete a integer symbol SYNOPSYS #include "libcsc.h" int CSCsymbolIntDel ( CSCsymbolType** const symPtrPtr, CSCmemListType const memList, int memTag ); RETURN VALUE CSC_OK ....... successful CSC_BADARG ... symPtrPtr or memList is NULL CSC_ERROR .... other errors DESCRIPTION CSCsymbolIntDel() removes the integer symbol whose pointer is pointed to by `symPtrPtr'. BUGS The name field of the symbol structure is a character pointer and CSCsymbolIntDel() tries to deallocate it; therefore, don't create a symbol with a statically allocated name. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolIntInit(3) NAME CSCsymbolIntInit - initialize a integer symbol SYNOPSYS #include "libcsc.h" int CSCsymbolIntInit ( CSCsymbolType* const symbol, const char* const symName, long symType, int symVal ); RETURN VALUE CSC_OK ........ successful CSC_BADARG .... symbol or symName is equal to NULL DESCRIPTION CSCsymbolIntInit() initializes the symbol pointed to by `symbol' with `symName', `symType', and `symVal'. Client code probably should use the same `symType' value for all integer symbols, and `symName' probably should be the ASCII string equivalent of `symVal'. BUGS The pointer `symName' is copied into the symbol structure; therefore, if `symName' is subsequently freed, then the newly initialized symbol will have an aliasing error (pointer to freed memory). And remember: CSCsymbolIntDel() will try to deallocate the name, so it won't be happy if the name was not dynamically allocated. HINT The symbol's valueFlag field is set to 1. SEE ALSO CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolIntNew(3) NAME CSCsymbolIntNew - allocate and initialize a integer symbol SYNOPSYS #include "libcsc.h" CSCsymbolType* CSCsymbolIntNew ( const char* const symName, long symType, int symVal, CSCmemListType const memList, int memTag ); RETURN VALUE CSCsymbolIntNew() returns a pointer to the newly allocated symbol, if successful; otherwise, NULL is returned. DESCRIPTION CSCsymbolIntNew() dynamically allocates a new symbol structure and fills it in with `symName', `symType', and `symVal'. Client code probably should use the same `symType' value for all integer symbols, and `symName' probably should be the ASCII string equivalent of `symVal'. HINTS Memory for the new symbol's name is allocated and `symName' is copied in to it, so client code can immediately free `symName' upon returning from CSCsymbolIntNew(). The symbol's valueFlag field is set to 1. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolIntWrite(3) NAME CSCsymbolIntWrite - write a integer symbol in ASCII format SYNOPSYS #include "libcsc.h" int CSCsymbolIntWrite ( const int fd, const CSCsymbolType* const symPtr ); RETURN VALUE CSC_OK ....... always DESCRIPTION CSCsymbolIntWrite() writes to fd the fields of the symbol in an ASCII format. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolPtrDel(3) NAME CSCsymbolPtrDel - delete a pointer symbol SYNOPSYS #include "libcsc.h" int CSCsymbolPtrDel ( CSCsymbolType** const symPtrPtr, CSCmemListType const memList, int memTag ); RETURN VALUE CSC_OK ....... successful CSC_BADARG ... symPtrPtr or memList is NULL CSC_ERROR .... other errors DESCRIPTION CSCsymbolPtrDel() removes the pointer symbol whose pointer is pointed to by `symPtrPtr'. BUGS The name and value fields of the symbol structure are pointers and CSCsymbolPtrDel() tries to deallocate them; therefore, don't create a symbol with a statically allocated name or pointer. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolPtrInit(3) NAME CSCsymbolPtrInit - initialize a pointer symbol SYNOPSYS #include "libcsc.h" int CSCsymbolPtrInit ( CSCsymbolType* const symbol, const char* const symName, long symType, const void* symVal, size_t symValSize ); RETURN VALUE CSC_OK ........ successful CSC_BADARG .... symbol, symName, or symVal is equal to NULL DESCRIPTION CSCsymbolPtrInit() initializes the symbol pointed to by `symbol' with `symName', `symType', and `symVal' for `symValSize'. Client code probably should use the same `symType' value for all pointer symbols. BUGS The pointers `symName' and `symval' are copied into the symbol structure; therefore, if `symName' or `symVal' is subsequently freed, then the newly initialized symbol will have an aliasing error (pointer to freed memory). And remember: CSCsymbolPtrDel() will try to deallocate the name and pointer, so it won't be happy if they were not dynamically allocated. HINT The symbol's valueFlag field is set to 3. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolPtrNew(3) NAME CSCsymbolPtrNew - allocate and initialize a pointer symbol SYNOPSYS #include "libcsc.h" CSCsymbolType* CSCsymbolPtrNew ( const char* const symName, long symType, const void* symVal, size_t symValSize, CSCmemListType const memList, int memTag ); RETURN VALUE CSCsymbolPtrNew() returns a pointer to the newly allocated symbol, if successful; otherwise, NULL is returned. DESCRIPTION CSCsymbolPtrNew() dynamically allocates a new symbol structure and fills it in with `symName', `symType', and `symVal' for `symValSize'. Client code probably should use the same `symType' value for all pointer symbols. HINTS Memory for the new `symName' and `symval' are allocated and they are copied in to it, so client code can immediately free `symName' and `symVal' upon returning from CSCsymbolPtrNew(). The symbol's valueFlag field is set to 3. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolPtrWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymbolPtrWrite(3) NAME CSCsymbolPtrWrite - write a pointer symbol in ASCII format SYNOPSYS #include "libcsc.h" int CSCsymbolPtrWrite ( const int fd, const CSCsymbolType* const symPtr ); RETURN VALUE CSC_OK ....... always DESCRIPTION CSCsymbolPtrWrite() writes to fd the fields of the symbol in an ASCII format. SEE ALSO CSCsymbolIntInit(3) CSCsymbolFloatInit(3) CSCsymbolPtrInit(3) CSCsymbolIntNew(3) CSCsymbolFloatNew(3) CSCsymbolPtrNew(3) CSCsymbolIntDel(3) CSCsymbolFloatDel(3) CSCsymbolPtrDel(3) CSCsymbolIntWrite(3) CSCsymbolFloatWrite(3) CSCsymbolDup(3) CSCsymbolDel(3) ------------------------------------------------------------------------ CSCsymtabDel(3) NAME CSCsymtabDel - remove a libcsc symbol table SYNOPSYS #include "libcsc.h" int CSCsymtabDel ( CSCsymTableType const symTab ); RETURN VALUE CSCsymtabDel(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION The libcsc symbol table represented by the opaque `symTab' is completely removed. BUGS Symbols not created by CSCsymbolFloatNew(), CSCsymbolIntNew(), and CSCsymbolPtrNew() may cause problems. (The name and value.pointer data of the symbol should be dynamically allocated, and the valueFlag field needs to be set the way CSCsymbolFloatNew(), CSCsymbolIntNew(), and CSCsymbolPtrNew() set it.) SEE ALSO CSCsymtabNew(3) CSCsymtabStat(3) CSCsymtabEntryPut(3) CSCsymtabEntryGet(3) CSCsymtabEntryDel(3) CSCsymtabEntryNext(3) ------------------------------------------------------------------------ CSCsymtabEntryDel(3) NAME CSCsymtabEntryDel - remove a symbol from a libcsc symbol table SYNOPSYS #include "libcsc.h" int CSCsymtabEntryDel ( CSCsymTableType const symTab, char* const symName ); RETURN VALUE CSCsymtabEntryDel(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSCsymtabEntryDel() removes the symbol entry specified by `symName' from `symTab'. The symbol in `symTab' whose name field contains `symName' is removed. BUGS Symbols not created by CSCsymbolFloatNew(), CSCsymbolIntNew(), and CSCsymbolPtrNew() may cause problems. (The name and value.pointer data of the symbol should be dynamically allocated, and the valueFlag field needs to be set the way CSCsymbolFloatNew(), CSCsymbolIntNew(), and CSCsymbolPtrNew() set it.) SEE ALSO CSCsymtabNew(3) CSCsymtabDel(3) CSCsymtabStat(3) CSCsymtabEntryPut(3) CSCsymtabEntryGet(3) CSCsymtabEntryNext(3) ------------------------------------------------------------------------ CSCsymtabEntryGet(3) NAME CSCsymtabEntryGet - get a symbol in a libcsc symbol table SYNOPSYS #include "libcsc.h" CSCsymbolType* CSCsymtabEntryGet ( CSCsymTableType const symTab, char* const symName, CSCmemListType const memLst ); RETURN VALUE CSCsymtabEntryGet(), if successful, returns a pointer to a CSCsymbolType, or NULL if otherwise unsuccessful. DESCRIPTION CSCsymtabEntryGet() returns a pointer to a duplicate symbol from `symTab' whose name field matches `symName'. If `memLst' is not NULL the duplicated symbol is dynamically allocated with CSCmemDup(), and should be removed with CSCmemFree() (with "tagData" of zero) to avoid leaking memory. If `memLst' is NULL the duplicated symbol is dynamically allocated with malloc() and should be removed with free() to avoid leaking memory. SEE ALSO CSCsymtabNew(3) CSCsymtabDel(3) CSCsymtabStat(3) CSCsymtabEntryPut(3) CSCsymtabEntryDel(3) CSCsymtabEntryNext(3) ------------------------------------------------------------------------ CSCsymtabEntryNext(3) NAME CSCsymtabEntryNext - find next entry in a libcsc symbol table SYNOPSYS #include "libcsc.h" void* CSCsymtabEntryNext ( CSCsymTableType const symTab, void* const lhPtr ); RETURN VALUE CSCsymtabEntryNext(), if successful, returns an opaque symbol table entry. If not successful, CSCsymtabEntryNext() returns NULL. DESCRIPTION CSCsymtabEntryNext() uses the libcsc symbol table specified by the opaque `symTab' and returns a pointer to the next consecutive entry following the entry pointed to by `lhPtr'. This next consecutive entry is the entry physically following the entry pointed to by `lhPtr'. If `lhPtr' is NULL, then the first item in the table is returned. If `symTab' is a table with no entries, or there are no more entries following the entry pointed to by `lhPtr', then NULL is returned. BUGS There is no legitimate way for client code to know what to do with the void pointer returned from this function. The secret is the returned value is a CSChashEntryType with its dataPtr field being a pointer to the symbol, but that might (very much not likely) change. SEE ALSO CSCsymtabNew(3) CSCsymtabDel(3) CSCsymtabStat(3) CSCsymtabEntryPut(3) CSCsymtabEntryGet(3) CSCsymtabEntryDel(3) ------------------------------------------------------------------------ CSCsymtabEntryPut(3) NAME CSCsymtabEntryPut - add a symbol to a libcsc symbol table SYNOPSYS #include "libcsc.h" int CSCsymtabEntryPut ( CSCsymTableType const symTab, CSCsymbolType* const symbol ); RETURN VALUE CSCsymtabEntryPut(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSCsymtabEntryPut() puts `symbol' into the symbol table specified by `symTab'. NOTE Its best to put only symbols created by CSCsymbolFloatNew(), CSCsymbolIntNew(), and CSCsymbolPtrNew() because the symbol table delete functions expect the symbols to be created the way these function do, with the name and value.pointer data being dynamically allocated, and the valueFlag field being correctly set. SEE ALSO CSCsymtabNew(3) CSCsymtabDel(3) CSCsymtabStat(3) CSCsymtabEntryGet(3) CSCsymtabEntryDel(3) CSCsymtabEntryNext(3) ------------------------------------------------------------------------ CSCsymtabNew(3) NAME CSCsymtabNew - create a new libcsc hash table SYNOPSYS #include "libcsc.h" CSCsymTableType CSCsymtabNew ( const char* const name, size_t size, const char** keyWords, int keyWordSpec, CSCmonFnType monFunc, const void* monData, CSCprofileType profiling ); RETURN VALUE CSCsymtabNew(), if successful, returns an opaque data type representing a new libcsc symbol table, or NULL if otherwise not successful. DESCRIPTION CSCsymtabNew() creates a new libcsc symbol table of `size' entries, and initialized with a set of keywords. `name' points to an arbitrary string that is used as the name of the new libcsc symbol table. If `size' is zero, then a default size is used. Since the symbol table is implemented as a hash table, the number of entries can be larger than size. If `keyWords' is NULL, then no keywords are loaded. Otherwise, keyWords is an array of character pointers; a symbol is created and put into the new table for each keyword. A list of keywords is terminated by a keyword of zero length, not a NULL keyword pointer. `keyWordType' is the value used for the keyword symbols' type field. SEE ALSO CSCsymtabDel(3) CSCsymtabStat(3) CSCsymtabEntryPut(3) CSCsymtabEntryGet(3) CSCsymtabEntryDel(3) CSCsymtabEntryNext(3) ------------------------------------------------------------------------ CSCsymtabStat(3) NAME CSCsymtabStat - retrieve statistics for a libcsc symbol table SYNOPSYS #include "libcsc.h" int CSCsymtabStat ( CSCsymTableType const symTab, size_t* const sizePtr ); RETURN VALUE CSCsymtabStat(), if successful, returns RTS_OK; otherwise, RTS_NOTFOUND, RTS_BADARG, and RTS_ERROR can be returned corresponding to NULL pointers, bad function arguments, and internal data errors, respectively. DESCRIPTION CSCsymtabStat() queries the libcsc symbol table specified by the opaque `symTab'. If `sizePtr' is not NULL, then the count of symbols in `symTab' is written to the size_t that is pointed to by `sizePtr'. SEE ALSO CSCsymtabNew(3) CSCsymtabDel(3) CSCsymtabEntryPut(3) CSCsymtabEntryGet(3) CSCsymtabEntryDel(3) CSCsymtabEntryNext(3) ------------------------------------------------------------------------ CSCsysInstallSignal(3) NAME CSCsysInstallSignal - fairly portable signal installer SYNOPSYS #include "libcsc.h" CSCsigFnType CSCsysInstallSignal ( const int signo, const CSCsigFnType func, const CSCsigModeType mode ); RETURN VALUE The return value from CSCsysInstallSignal() is a function pointer to a signal handler. If CSCsysInstallSignal() is NOT successful, then the return value is SIG_ERR cast as a signal handler function. If CSCsysInstallSignal() is successful, then the return value is a function pointer to the previously installed handler cast as a signal handler function; this might be NULL in the typical case that there was no previous signal handler. DESCRIPTION CSCsysInstallSignal() is a reliable version of signal() using POSIX sigaction(). `signo' is the signal number of the signal for which the signal handler function `func' is installed. `mode' is CSC_SIG_INTERRUPT or CSC_SIG_RESTART; it is used to control behavior, specifically for slow system calls: mode behavior ---- -------- CSC_SIG_INTERRUPT slow system calls are interrupted CSC_SIG_RESTART slow system calls are not interrupted An illustration of slow system call and signal interrupt is a program that creates children and has a signal handler for SIGCHLD. If this program blocks on something like an accept() on a TCP socket connection and a child process terminates, then the registered SIGCHLD signal handler runs; but, the process unblocks and returns from the accept() with no connection (errno should be EINTR). This can be avoided by using CSCsysInstallSignal() to install the SIGCHLD signal handler function `func' and specifying CSC_SIG_RESTART for `mode'. SEE ALSO CSCsysLimitsGet(3) CSCsysUsleep(3) ------------------------------------------------------------------------ CSCsysLimitsGet(3) NAME CSCsysLimitsGet - find some system limits SYNOPSYS #include "libcsc.h" int CSCsysLimitsGet ( int* const fileOpenMaxPtr, int* const fileNameLengthPtr, int* const filePathLengthPtr ); RETURN VALUE RTS_OK ........ successful CSC_BADARG .... fileOpenMaxPtr, or fileNameLengthPtr, or filePathLengthPtr is NULL CSC_ERROR ..... error getting limit from system call DESCRIPTION CSCsysLimitsGet() makes some system calls and writes the integer information to the addresses specified in the arguments. `fileOpenMaxPtr' must be a non-NULL pointer to an integer. If the call to CSCsysLimitsGet() is successful, the integer value will be the maximum number of open files allowed per process. `fileNameLenghtPtr' must be a non-NULL pointer to an integer. If the call to CSCsysLimitsGet() is successful, the integer value will be the maximum files name length allowed by the system. `filePathLengthPtr' must be a non-NULL pointer to an integer. If the call to CSCsysLimitsGet() is successful, the integer value will be the maximum path length allowed by the system. SEE ALSO CSCsysInstallSignal(3) CSCsysUsleep(3) ------------------------------------------------------------------------ CSCsysUsleep(3) NAME CSCsysUsleep - sleep some microseconds (rounded to kernel capability) SYNOPSYS #include "libcsc.h" void CSCsysUsleep ( const size_t microseconds ); RETURN VALUE CSCsysUsleep() has no return value. DESCRIPTION The calling process/task will block for microseconds. The actual time blocked will be descretized to the granularity implemented by the kernel. SEE ALSO CSCsysInstallSignal(3) CSCsysLimitsGet(3) ------------------------------------------------------------------------ CSCtimerClear(3) NAME CSCtimerClear - clear marks in timer SYNOPSYS #include "libcsc.h" int CSCtimerClear ( CSCtimerType const timer ); RETURN VALUE CSC_OK ........ successful CSC_BADARG .... timer is NULL CSC_CORRUPT ... corruption is detected in timer and CSCtimerClear() is compiled with DEBUG DESCRIPTION CSCtimerClear() clears marks (and all the stats) in `timer'. SEE ALSO PRtimerInit(3) PRtimerDone(3) PRtimerMark(3) PRtimerDiff(3) PRtimerStat(3) ------------------------------------------------------------------------ CSCtimerDiff(3) NAME CSCtimerStat - create and get current timer's time SYNOPSYS #include "libcsc.h" int CSCtimerDiff ( CSCtimerType const timer, double* const diffPtr ); RETURN VALUE CSC_OK ........ successful CSC_ERROR ..... an error occurs trying to get system time or there was no previous call to PRtimerMark() with the timer CSC_BADARG .... timer is NULL CSC_CORRUPT ... corruption is detected in timer and CSCtimerDiff() is compiled with DEBUG DESCRIPTION CSCtimerDiff() creates a time from the caller's previous call to CSCtimerMark() with `timer' and the call to this function. The difference is stored in a double as seconds. A previous call to PRtimerMark() must have been made with `timer'. If the `diffPtr' argument is not NULL, then CSCtimerDiff() writes to the double pointed to by `diffPtr' the difference between the marks taken with `timer'. SEE ALSO PRtimerInit(3) PRtimerDone(3) PRtimerClear(3) PRtimerMark(3) PRtimerStat(3) ------------------------------------------------------------------------ CSCtimerDone(3) NAME CSCtimerDone - delete a timer SYNOPSYS #include "libcsc.h" int CSCtimerDone ( CSCtimerType const timer ); RETURN VALUE CSC_OK ........ successful CSC_BADARG .... timer is NULL CSC_CORRUPT ... corruption is detected in timer and CSCtimerDone() is compiled with DEBUG DESCRIPTION CSCtimerDone() completely removes `timer'. Do not try to use `timer' again. At least until it is reset by assigning it the results of a subsequent call to PRtimerInit(); SEE ALSO PRtimerInit(3) PRtimerClear(3) PRtimerMark(3) PRtimerDiff(3) PRtimerStat(3) ------------------------------------------------------------------------ CSCtimerInit(3) NAME CSCtimerInit - create a timer SYNOPSYS #include "libcsc.h" CSCtimerType CSCtimerInit (void) RETURN VALUE CSCtimerInit() returns a new timer. DESCRIPTION CSCtimerInit() creates timer for the caller's subsequent calls to CSCtimerMark() and CSCtimerDiff(). SEE ALSO PRtimerDone(3) PRtimerClear(3) PRtimerMark(3) PRtimerDiff(3) PRtimerStat(3) ------------------------------------------------------------------------ CSCtimerMark(3) NAME CSCtimerMark - create a mark in a timer SYNOPSYS #include "libcsc.h" int CSCtimerMark ( CSCtimerType const timer ); RETURN VALUE CSC_OK ........ successful CSC_ERROR ..... an error occurs trying to get system time CSC_BADARG .... timer is NULL CSC_CORRUPT ... corruption is detected in timer and CSCtimerMark() is compiled with DEBUG DESCRIPTION CSCtimerMark() creates a mark in `timer' for the caller's subsequent call to CSCtimerDiff() with `timer'. Given the some `timer', CSCtimerDiff() will create the time value of the number of seconds that passed since the call to this function CSCtimerMark(). SEE ALSO PRtimerInit(3) PRtimerDone(3) PRtimerClear(3) PRtimerDiff(3) PRtimerStat(3) ------------------------------------------------------------------------ CSCtimerStat(3) NAME CSCtimerStat - get current timer's time SYNOPSYS #include "libcsc.h" int CSCtimerStat ( CSCtimerType const timer, double* const diffPtr ); RETURN VALUE CSC_OK ........ successful CSC_ERROR ..... at least one of the two marks has not been taken with timer CSC_BADARG .... timer is NULL CSC_CORRUPT ... corruption is detected in timer and CSCtimerStat() is compiled with DEBUG DESCRIPTION CSCtimerStat() writes to the double pointed to by `diffPtr' the difference between the marks taken with `timer'. The difference is in seconds. Marks are taken with `timer' by using functions CSCtimerMark() and CSCtimerDiff(). The difference in seconds between CSCtimerMark() and CSCtimerDiff() is kept in `timer' as a double. The `timer's difference between marks is created by CSCtimerDiff(); CSCtimerStat() merely returns the saved value. SEE ALSO PRtimerInit(3) PRtimerDone(3) PRtimerClear(3) PRtimerMark(3) PRtimerDiff(3) ------------------------------------------------------------------------ CSCurand(3) NAME CSCurand - uniform random number generator SYNOPSYS #include "libcsc.h" int CSCurand ( int y, double* dptr ); RETURN VALUE urand() returns a random int. DESCRIPTION Urand is a Uniform/Universal RANDom number generator. The integer argument y should be initialized to some arbitrary non-zero number prior to the first call to CSCurand. Function CSCurand takes the form: f(x) = a(x) + c(modulo m) m is 2 to the power of t for t-bit integers. X, a, and c are themselves integers in the same range. Some choices of a and c are good; urand chooses values suggested by Knuth (1969). The scale factor that is used for converting y to a floating point value in the interval (0,1) is s = (double) 0.5 / halfm. CSCurand is taken from George E. Forsythe, Michael A. Malcolm, and Cleve B. Moler, "Computer Methods for Mathematical Programming" (Englewood Cliffs: Prentice Hall, 1977), 246. CSCurand is based on theory and suggestions given in Donald E. Knuth "Seminumerical Algorithms," The Art of Computer Programming, vol. 2 (Reading Mass.: Addison-Wesley 1969). BUGS Using CSCurand() always seems too difficult. SEE ALSO CSC2x(3) ------------------------------------------------------------------------ CSCversion(3) NAME CSCversion - get string containing the libcsc version SYNOPSYS #include "libcsc.h" const char* CSCversion (void); DESCRIPTION CSCversion() returns a pointer to a constant ASCII-Z string containing the libcsc version. SEE ALSO CSCstatStr(3) CSCcflags(3) CSCldflags(3) CSClibs(3) CSCcredits(3) CSCchkup(3) ------------------------------------------------ APPENDIX C LICENSE ======================= GNU Free Documentation License Version 1.1, March 2000 Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: * A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. * B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). * C. State on the Title page the name of the publisher of the Modified Version, as the publisher. * D. Preserve all the copyright notices of the Document. * E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. * F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. * G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. * H. Include an unaltered copy of this License. * I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. * J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. * K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. * L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. * M. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version. * N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. How to use this License for your documents To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License". If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.