1 2FILE NAME 3 4 $RCSfile: reference.manual,v $ 5 $Revision: 1.5 $ 6 $Date: 2003/03/24 05:11:22 $ 7 8PROGRAM INFORMATION 9 10 Developed by: libcsc project 11 Developer: Douglas R. Jerome, drj, <jerome@globalcrossing.net> 12 13FILE DESCRIPTION 14 15 Reference manual for libcsc version 0.8X.X. 16 17CHANGE LOG 18 19 06nov02 drj Replaced text for CSClistPop() and CSClistNodeNext()/ 20 21 12may02 drj Changed libcsc version in title from 0.81.0 to 0.8X.X. 22 23 02may02 drj Added file header. Fixed libcsc version in title. 24 25 26 27 28 REFERENCE MANUAL 29 for 30 LIBCSC VERSION 0.8X.X 31 32 33 34 35 Programming 36 with 37 libcsc 38 39 40 41 42 Copyright (c) 2002 Douglas R. Jerome 43 Peoria, Arizona USA 44 45 Douglas Jerome 46 ------------ 47 djerome@users.sourceforge.net 48 jerome@globalcrossing.net 49 50 51 52 53 --------------------------------------------------------------------- 54 Permission is granted to copy, distribute and/or modify this document 55 under the terms of the GNU Free Documentation License, Version 1.1 or 56 any later version published by the Free Software Foundation; with no 57 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 58 Texts. A copy of the license is included in the section entitled 59 "GNU Free Documentation License". 60 --------------------------------------------------------------------- 61 62 63 64 65 ------------------------------------------------ 66 67 68 69 70 Table of Contents 71Paragraph Page 72 731.0 SCOPE .................................................................. X 742.0 OVERVIEW ............................................................... X 753.0 SUBSYSTEMS ............................................................. X 76 77Appendices 78 79A SUBSYSTEM REFERENCE ...................................................... X 80B FUNCTION REFERENCE ....................................................... X 81C LICENSE .................................................................. X 82 83 84 85 86 ------------------------------------------------ 87 88 89 90 91 ===== 921.0 SCOPE 93 ===== 94 95 -------------- 961.1 Identification 97 -------------- 98 99This document is the reference manual for the C language programming library 100named "libcsc". See the title page of this document for the exact date and 101revision of this document and applicable version of libcsc. 102 103 --------------- 1041.2 System Overview 105 --------------- 106 107libcsc is a library of C functions implementing several general purpose 108programming abstractions e.g., balanced binary tree, hash table, list, etc. 109Much of libcsc is appropriate for use in embedded systems. 110 111libcsc is distributed under the GNU Library Public License and is freely 112available at: 113 114 o http://hackerlabs.sourceforge.net 115 116 o ftp://hackerlabs.sourceforge.net/pub/hackerlabs 117 118Here is a sample command line ftp session, fetching a version of libcsc. 119 120% ftp hackerlabs.sourceforge.net 121Connected to hackerlabs.sourceforge.net. 122220 orbital.i.sourceforge.net FTP server (Version wu-2.5.0(1) Tue Sep 21 16:48:12 EDT 1999) ready. 123Name (hackerlabs.sourceforge.net:jerome): anonymous 124331 Guest login ok, send your complete e-mail address as password. 125Password: djerome@users.sourceforge.net 126230- 127230- 128230-****************************************************** 129230-* Welcome to ftp.sourceforge.net * 130230-****************************************************** 131230- 132230-If you find that this server is slow please try our 133230-much faster httpd server @ http://sourceforge.net 134230- 135230- 136230- 137230- 138230 Guest login ok, access restrictions apply. 139Remote system type is UNIX. 140Using binary mode to transfer files. 141ftp> cd pub/hackerlabs 142250 CWD command successful. 143ftp> get libcsc-0.4.2.tar.gz 144local: libcsc-0.4.2.tar.gz remote: libcsc-0.4.2.tar.gz 145200 PORT command successful. 146150 Opening BINARY mode data connection for libcsc-0.4.2.tar.gz (114895 bytes). 147226 Transfer complete. 148114895 bytes received in 24.8 secs (4.5 Kbytes/sec) 149ftp> quit 150221-You have transferred 114895 bytes in 1 files. 151221-Total traffic for this session was 117273 bytes in 2 transfers. 152221-Thank you for using the FTP service on orbital.i.sourceforge.net. 153221 Goodbye. 154% 155 156The file is a compressed tar (tape archive) file. To extract the files, once 157you have the compressed archive, type: 158 159 % gunzip -c libcsc-0.4.2.tar.gz | tar xf - 160 161LIBCSC IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. THERE ARE NO 162REPRESENTATIONS ABOUT THE SUITABILITY OF THIS SOFTWARE FOR ANY PURPOSE. 163DOUGLAS R. JEROME SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY THE USERS OF 164THIS SOFTWARE. 165 166 ----------------- 1671.3 Document Overview 168 ----------------- 169 170Chapter 1.0 _SCOPE_ 171 describes this document, introduces what libcsc is and the logistics of 172 finding and downloading libcsc. 173 174Chapter 2.0 _OVERVIEW_ 175 describes concepts and structure implementing libcsc. 176 177Chapter 3.0 _SUBSYSTEMS_ 178 provides a list of the libcsc software subsystems. 179 180Appendix A _SUBSYSTEM REFERENCE_ 181 provides a an overview description of each libcsc software subsystem. 182 183Appendix B _FUNCTION REFERENCE_ 184 is a detailed description of each function in libcsc. 185 186Appendix C _LICENSE_ 187 is the GNU Free Documentation License, the license under which this 188 document is distributed. 189 190 --------------- 1911.4 libcsc Glossary 192 --------------- 193 194API - Application Program Interface This generally refers to the 195 functions and global data comprising an interface to 196 something; in this case, the libcsc subsystems. 197 198c-switch - Conditional compilation; implemented with #ifdef or #if. 199 200client code - This is the "user" code that includes libcsc header files and 201 makes libcsc function calls. 202 203embedded - A computer or software execution environment that is actually 204 a part of something else, like a telephone. There may not be 205 anything like a Unix operating system in there. 206 207ISO - International Standards Organization (I think) 208 209instrument - Instrumented code is code that has extra debug/trace output. 210 The libcsc source code is instrumented. By defining macros 211 DEBUG and/or TRACE at compile time, extra output is generated 212 by the libcsc code. 213 214opaque - A variable type, or data structure, that client code has no 215 internal access. This is usually a void pointer for the 216 client code, and it is passed to susbsystem functions which 217 use and update the internal fields of the data structure/type. 218 219STDC - Most people call this "ANSI C". There is an international 220Standard C ISO standard that is essentially the ANSI standard, probably 221 written in internationalized English. 222 223subsystem - A collection of similar functions grouped together in a 224 single .c file, typically implementing an abstract data type 225 such as a hash table. 226 227target - Kernel (operating system) for which libcsc is compiled. You 228 do the compilation. 229 230TBS - To Be Specified This means someone has been too lazy to 231 document it. 232 233 234 235 236 ------------------------------------------------ 237 238 239 240 241 ======== 2422.0 OVERVIEW 243 ======== 244 245 ---------------- 2462.1 Software License 247 ---------------- 248 249libcsc is copyright (c) 1998 - 2002 by Douglas R. Jerome; the software is 250protected as an unpublished work under the U.S. Copyright Act of 1976. All 251rights reserved by Douglas R. Jerome. 252 253libcsc is free software; you can redistribute it and/or modify it under the 254terms of the GNU Library General Public License as published by the Free 255Software Foundation; either version 2, or (at your option) any later version. 256 257libcsc is distributed in the hope that it will be useful, but WITHOUT ANY 258WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 259PARTICULAR PURPOSE. See the GNU Library General Public License for more 260details. 261 262You should have received a copy of the GNU Library General Public License along 263with libcsc; see the file COPYRIGHT. If not, write to the Free Software 264Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. 265 266I don't really care what you do with the libcsc software; I just want some 267credit for the work that I've done and ask that something like the following 268message be included in all derived works: 269 270 Portions developed by: Douglas R. Jerome <jerome@globalcrossing.net> 271 272 --------- 2732.2 Structure 274 --------- 275 276[ This section is TBS. ] 277 278 ----- 2792.3 Usage 280 ----- 281 282DEBUG 283----- 284 285libcsc can be built with the macro DEBUG defined; it will be on the make 286command line (specified with -DDEBUG) e.g., 287 288 make CDEBUGFLAGS=-DDEBUG 289 290libcsc source code is heavily c-switched on DEBUG e.g., this code fragment: 291 292 . 293 . 294 . 295#ifdef DEBUG 296 if (ptr == NULL) 297 printf ("barf in %s at line %s\n", __FILE__, __LINE__); 298#endif 299 . 300 . 301 . 302 303When you build libcsc, use DEBUG until you know there are no bugs in the client 304code (or libcsc). It will keep monsters away, your boss will give you a raise, 305people will love you, and you will be happier in general. 306 307assertions 308---------- 309 310Define DEBUG in your client code and use the libcsc assertion macros, from 311libcsc_debug.h, everywhere in your client code. 312 313return values 314------------- 315 316As a general rule, libcsc functions return 0 indicating success, and return -1 317OR A SMALL POSITIVE NUMBER indicating failure; exceptions are some functions 318that return a pointer wherein a return value of NULL indicates failure. 319 320All return values, excluding pointers, have a symbolic definition, implemented 321by a #define in the libcsc.h header file. CSCstatStr() is a function that 322prints a (descriptive) message string associate with these return values. 323 324 --------------------------- 3252.4 Notes on libcsc Compilation 326 --------------------------- 327 328libcsc is intended to: BUILD ON BUILD FOR 329 --------------------------------- 330 Linux ................. Linux 331 Solaris ............... Solaris 332 Linux, Solaris ........ vxWorks (cross-compile) 333 334embedded cross-compile 335---------------------- 336 337Most of libcsc is intended to be able to be built for embedded environments. 338 339Unfortunately, to cross-compile for vxWorks, you need to make your own makefile 340for the src directory, name it something like "Makefile.src.embedded", and do 341something like this: 342 343 rm Makefile 344 ln -s Makefile.src.embedded Makefile 345 make 346 347Not all files will successfully cross-compile. 348 349unix compile 350------------ 351 352Make with Makefile.src.unix; you should be able to simply run make because 353there should be a symbolic link from Makefile to Makefile.src.unix. 354 355make options 356------------ 357 358RECOMMENDED Always build with DEBUG, until your application/system is 359 debugged. 360 361You can control the DEBUG c-switches in the libcsc code; it is conveniently 362specified on the make command line with the CDEBUGFLAGS macro, like this: 363 364 make "CDEBUGFLAGS=-DDEBUG" # make with DEBUG 365 366To build with debugger information (for use with GDB), or to build with a high 367level of optimization, one can conveniently use the CC_PARAMS macro on the make 368command line, like this: 369 370 make "CC_PARAMS=-g" # for GDB 371 make "CC_PARAMS=-O3" # for optimization 372 373These can be mixed: 374 375 make "CC_PARAMS=-g" "CDEBUGFLAGS=-DDEBUG" # make for GDB and with DEBUG 376 377 ------------------------ 3782.5 Notes on the Source Code 379 ------------------------ 380 381libcsc directory structure: 382 383 directory usage 384 ================== =============== 385 <libcsc dir> / 386 / doc - documentation 387 / include - .h files 388 / lib - object code 389 / src - .c files 390 / t - example/test client code 391 392libcsc is completely written in C. It contains functions implementing general 393subsystems. Some subsystem are abstract data types, and some subsystems are 394simply a collection of similar functions. 395 396The libcsc code is developed with strict Standard C (ANSI/ISO) compliance 397enforced by compiler switches. libcsc compilation command lines, in the 398makefiles, contain Standard C compliance switches. If this is a problem, then 399spank yourself ask "wtf am I doing with a non-Standard C compilation system?" 400 401The csc_sock subsystem in libcsc uses the BSD socket subsystem and won't 402completely build without it. Without your compilation and runtime system 403having a BSD socket subsystem you'll probably get a lib/libcsc.a file when you 404build libcsc, but it won't have the csc_sock subsystem. 405 406 407 408 409 ------------------------------------------------ 410 411 412 413 4143.0 SUBSYSTEMS 415 ========== 416 417Subsystem Overview 418------------------ 419 420csc_config - libcsc specific checks ................................ libcsc.h 421csc_file(P) - File Access and Location Subsystem .................... libcsc.h 422csc_hash - Hash Table Subsystem .................................. libcsc.h 423csc_io - Miscellaneous I/O Functions ........................... libcsc.h 424csc_list - List (stack, queue, linked list) Subsystem ............ libcsc.h 425csc_math - Miscellaneous Math Functions .......................... libcsc.h 426csc_mem - Dynamically Allocated Memory Subsystem ................ libcsc.h 427csc_notify - Notification (callback) Subsystem ..................... libcsc.h 428csc_sock(B) - BSD Network Socket Subsystem .......................... libcsc.h 429csc_string - Miscellaneous String Functions ........................ libcsc.h 430csc_symbol - Symbol (individual, not as a table) Subsystem ......... libcsc.h 431csc_symtab - Symbol Table Subsystem ................................ libcsc.h 432csc_sys(P) - Miscellaneous System Functions ........................ libcsc.h 433csc_timer(B) - Timer Subsystem ....................................... libcsc.h 434csc_tree - Balanced Binary Tree Subsystem ........................ libcsc.h 435 436(B) - 4.3+BSD The subsystem names ending with "(B)" make use of 4.3+BSD 437 conventions. These subsystems may not compile for an embedded 438 environment. 439 440(P) - POSIX The subsystem names ending with "(P)" make use of unix 441 conventions and POSIX compliance. Don't expect these 442 subsystems to compile for an embedded environment. 443 444 445 446 447 ================================================================ 448 APPENDICES 449 ================================================================ 450 451 452 453 454APPENDIX A SUBSYSTEM REFERENCE 455=================================== 456 457 458------------------------------------------------------------------------ 459csc_config(l) 460 461NAME 462 csc_config 463 464DESCRIPTION 465 Configuration and General Function Subsystem 466 467FUNCTIONS 468 CSCstatStr - get string describing libcsc function return value 469 CSCcflags - get string containing compiler command-line options 470 CSCldflags - get string containing compiler command-line options 471 CSClibs - get string containing compiler command-line options 472 CSCversion - get string containing the libcsc version 473 CSCcredits - get string containing the libcsc credits 474 CSCchkup - check scalar data sizes assumed by libcsc 475 476 477------------------------------------------------------------------------ 478csc_file(l) 479 480NAME 481 csc_file 482 483DESCRIPTION 484 File Subsystem 485 486FUNCTIONS 487 CSCfileReadLock - read-lock a region in a file 488 CSCfileWriteLock - write-lock a region in a file 489 CSCfileUnlock - unlock a region in a file 490 CSCfileGetHomeDir - find home directory pathname 491 CSCfileGetUserHomeDir - find home directory pathname of specific user 492 CSCfileBaseName - strip directory from pathname 493 CSCfilePathName - strip last component (file) from pathname 494 CSCfileExpandPath - expand ~ and environment variables in pathname 495 CSCfileOpen - create a file in a path that doesn't (yet) exist 496 497 498------------------------------------------------------------------------ 499csc_hash(l) 500 501NAME 502 csc_hash 503 504DESCRIPTION 505 Hash table Subsystem 506 507FUNCTIONS 508 CSChashNew - create a new libcsc hash table 509 CSChashDel - remove a libcsc hash table 510 CSChashStat - query statistics of a libcsc hash table 511 CSChashEntryPut - put an entry into a libcsc hash table 512 CSChashEntryGet - get an item from a libcsc hash table 513 CSChashEntryDel - remove an entry from a libcsc hash table 514 CSChashEntryNext - find next entry in a libcsc hash table 515 CSChashEntryStat - query the fields of a libcsc hash table entry 516 CSChashRead - read an ASCII format libcsc hash table 517 CSChashWrite - write a libcsc hash table in an ASCII format 518 CSChashDump - write a formatted dump of a libcsc hash table 519 520 521------------------------------------------------------------------------ 522csc_io(l) 523 524NAME 525 csc_io 526 527DESCRIPTION 528 I/O Subsystem 529 530FUNCTIONS 531 CSCioInfoPrint - formatted write to stdout 532 CSCioWarnPrint - formatted write to stdout 533 CSCioErrorPrint - formatted write to stderr 534 CSCioSoftwareError - print a parameterized software error message 535 CSCioRead - read a specific number of bytes 536 CSCioReadLine - read bytes that are terminated by a newline 537 CSCioBufWrite - write an ASCII buffer 538 CSCioBufRead - read an ASCII buffer 539 540 541------------------------------------------------------------------------ 542csc_list(l) 543 544NAME 545 csc_list 546 547DESCRIPTION 548 List Subsystem 549 550 The csc library's list subsystem; there are functions for managing 551 arbitrary data in lists. These lists can act like queues, stacks, or 552 just linked lists. 553 554FUNCTIONS 555 CSClistNew - create a new libcsc list 556 CSClistDel - remove a libcsc list 557 CSClistRead - read an ASCII format libcsc list 558 CSClistWrite - write a libcsc list in an ASCII format 559 CSClistSetCFunc - set a libcsc list entry data compare function 560 CSClistStat - retrieve libcsc list statistics 561 CSClistPush - create a new entry and push it onto a libcsc list 562 CSClistPop - pop an entry from a libcsc list and retrieve its data 563 CSClistPeek - retrieve data from entry at libcsc list head or tail 564 CSClistNodeNext - find next entry (node) in a libcsc list 565 CSClistNodeFindByValue - find libcsc list entry by data value 566 CSClistNodeFindByReference - find libcsc list entry (node) by reference 567 CSClistNodeStat - retrieve data fields from a libcsc list entry (node) 568 CSClistNodeValidate - verify an entry (node) is really in a libcsc list 569 CSClistNodeDel - remove an entry (node) from a libcsc list 570 571 572------------------------------------------------------------------------ 573csc_math(l) 574 575NAME 576 csc_math 577 578DESCRIPTION 579 Miscellaneous math functions. 580 581FUNCTIONS 582 CSC2x - 2 to a the power of x, 0 <= x <= 30 583 CSCurand - uniform random number generator 584 585 586------------------------------------------------------------------------ 587csc_mem(l) 588 589NAME 590 csc_mem 591 592DESCRIPTION 593 Memory (Dynamic Allocation) Subsystem 594 595FUNCTIONS 596 CSCmemInit - initialize a csc memlist for subsequent memory allocations 597 CSCmemDone - cleanup and remove a memList (free all its memory) 598 CSCmemAlloc - allocate memory (and keep thrack of it in memList) 599 CSCmemDup - duplicate (dynamically allocate and copy) memory 600 CSCmemFree - free dynamically allocated memory 601 CSCmemLookup - lookup a memory pointer in memList 602 CSCmemValidate - validate that a memory pointer is in memList 603 CSCmemListFree - free all memory allocated in a memList 604 CSCmemListStat - get information about a memList 605 CSCmemListPrintProfile - write a memlist profile to standard output 606 CSCmemListWriteProfile - write a memlist profile to a file descriptor 607 608 609------------------------------------------------------------------------ 610csc_notify(l) 611 612NAME 613 csc_notify 614 615DESCRIPTION 616 Notification System (callback) Subsystem 617 618 Create a notification board, add some notifications to it, then 619 regisiter some functions, each with some private data (pointer is 620 useful) on some the the notifications. When a notification is posted, 621 the registered functions will be called, each with their corresponding 622 private data. 623 624FUNCTIONS 625 CSCnotificationBoardNew - create a new notification board 626 CSCnotificationBoardDel - completely remove a notification board 627 CSCnotificationBoardPrint - print a notification board in ASCII format 628 CSCnotificationNew - create a new notification in a board 629 CSCnotificationDel - delete a notification from a board 630 CSCnotificationPost - post to a notification in a board 631 CSCnotificationRegister - register client function to a notification 632 633 634------------------------------------------------------------------------ 635csc_sock(l) 636 637NAME 638 csc_sock 639 640DESCRIPTION 641 BSD Network Socket Subsystem 642 643FUNCTIONS 644 CSCsockConnectTCP - initiate a socket connection 645 CSCsockConnectUDP - initiate a socket connection 646 CSCsockPassiveTCP - listen for connections on a socket 647 CSCsockPassiveUCP - listen for connections on a socket 648 649 650------------------------------------------------------------------------ 651csc_string(l) 652 653NAME 654 csc_string 655 656DESCRIPTION 657 String Subsystem 658 659FUNCTIONS 660 CSCstringOctal - format an ASCII string to represent an octal number 661 CSCstringBinary - format an ASCII string to represent a binary number 662 CSCstringBasename - strip directory from a filename 663 664 665------------------------------------------------------------------------ 666csc_symbol(l) 667 668NAME 669 csc_symbol 670 671DESCRIPTION 672 Symbol Subsystem 673 674FUNCTIONS 675 CSCsymbolIntInit - initialize a integer symbol 676 CSCsymbolFloatInit - initialize a floating point symbol 677 CSCsymbolPtrInit - initialize a pointer symbol 678 CSCsymbolIntNew - allocate and initialize a integer symbol 679 CSCsymbolFloatNew - allocate and initialize a floating point symbol 680 CSCsymbolPtrNew - allocate and initialize a pointer symbol 681 CSCsymbolIntDel - delete a integer symbol 682 CSCsymbolFloatDel - delete a floating point symbol 683 CSCsymbolPtrDel - delete a pointer symbol 684 CSCsymbolIntWrite - write a integer symbol in ASCII format 685 CSCsymbolFloatWrite - write a floating point symbol in ASCII format 686 CSCsymbolPtrWrite - write a pointer symbol in ASCII format 687 CSCsymbolDup - dynamically allocate and duplicate a symbol 688 CSCsymbolDel - remove a libcsc symbol table 689 690 691------------------------------------------------------------------------ 692csc_symtab(l) 693 694NAME 695 csc_symtab 696 697DESCRIPTION 698 Symbol Table Subsystem 699 700FUNCTIONS 701 CSCsymtabNew - create a new libcsc hash table 702 CSCsymtabDel - remove a libcsc symbol table 703 CSCsymtabStat - retrieve statistics for a libcsc symbol table 704 CSCsymtabEntryPut - add a symbol to a libcsc symbol table 705 CSCsymtabEntryGet - get a symbol in a libcsc symbol table 706 CSCsymtabEntryDel - remove a symbol from a libcsc symbol table 707 CSCsymtabEntryNext - find next entry in a libcsc symbol table 708 709 710------------------------------------------------------------------------ 711csc_sys(l) 712 713NAME 714 csc_sys 715 716DESCRIPTION 717 System Subsystem 718 719FUNCTIONS 720 CSCsysLimitsGet - find some system limits 721 CSCsysInstallSignal - fairly portable signal installer 722 CSCsysUsleep - sleep some microseconds 723 724 725------------------------------------------------------------------------ 726csc_timer(l) 727 728NAME 729 csc_timer 730 731DESCRIPTION 732 Timer Subsystem 733 734FUNCTIONS 735 CSCtimerInit - create a timer 736 CSCtimerDone - delete a timer 737 CSCtimerClear - clear marks in timer 738 CSCtimerMark - create a mark in a timer 739 CSCtimerStat - create and get current timer's time 740 CSCtimerStat - get current timer's time 741 742 743------------------------------------------------------------------------ 744csc_tree(l) 745 746NAME 747 csc_tree 748 749DESCRIPTION 750 Balanced Binary Tree Subsystem 751 752 The CSCbinTree functions provide an interface to a balanced binary tree 753 subsystem. The tree is an opaque data type, and client code never has 754 direct access to the nodes. Note that you can't remove nodes, but the 755 tree can be deleted. 756 757 The CSCbinTreeNode functions provide individual node manipulation 758 capability. Trees can be built with the CSCbinTreeNodeJoin function, 759 which returns a pointer to the upper node. These trees are not likely 760 to be balanced. 761 762 Don't try mixing the CSCbinTree and CSCbinTreeNode functions on the 763 same tree. 764 765FUNCTIONS 766 tree 767 ---- 768 CSCbinTreeNew - create an empty libcsc balanced binary tree 769 CSCbinTreeDel - delete a libcsc balanced binary tree 770 CSCbinTreeInsert - insert a node into a libcsc balanced binary tree 771 CSCbinTreeTagOrderedInsert - put node into libcsc balanced binary tree 772 CSCbinTreeTraverse - traverse a libcsc balanced binary tree 773 CSCbinTreeUserSearch - arbitrary search of libcsc balanced binary tree 774 CSCbinTreeTagSearch - search a balanced binary tree for node with tag 775 CSCbinTreeStat - retrieve libcsc balanced binary tree statistics 776 CSCbinTreePrint - print a libcsc balanced binary tree 777 778 node 779 ---- 780 CSCbinTreeNodeNew - create a new empty libcsc binary tree node 781 CSCbinTreeNodeDel - deallocate a libcsc binary tree node 782 CSCbinTreeNodeJoin - join libcsc binary tree nodes 783 CSCbinTreeNodeBreak - break libcsc binary tree at a node 784 CSCbinTreeNodeTraverse - traverse a libcsc binary tree 785 CSCbinTreeNodeUserSearch - arbitrary libcsc binary tree traversal 786 CSCbinTreeNodeTagSearch - search a libcsc binary tree for a given tag 787 CSCbinTreeNodeStat - retrieve fields from a libcsc binary tree node 788 CSCbinTreeNodePrint - print the values of a libcsc binary tree node 789 790 791 792 793 ------------------------------------------------ 794 795 796 797 798APPENDIX B FUNCTION REFERENCE 799================================== 800 801 802------------------------------------------------------------------------ 803CSC2x(3) 804 805NAME 806 CSC2x - 2 to a the power of x, 0 <= x <= 30 807 808SYNOPSYS 809 #include "libcsc.h" 810 811 int CSC2x ( 812 int exponent 813 ); 814 815RETURN VALUE 816DESCRIPTION 817 CSC2x() returns 2 to the power of exponent, unless exponent is less 818 than 0 or greater than 30, in which case CSC2x() returns -1. 819 820 CSC2x() uses a table, so it is extremly fast. 821 822SEE ALSO 823 CSCurand(3) 824 825 826------------------------------------------------------------------------ 827CSCbinTreeDel(3) 828 829NAME 830 CSCbinTreeDel - delete a libcsc balanced binary tree 831 832SYNOPSYS 833 #include "libcsc.h" 834 835 int CSCbinTreeDel ( 836 CSCbinTreeType const tree, 837 CSCgenFnType cbFn 838 ); 839 840RETURN VALUE 841 CSC_OK ......... if successful, and the opaque data structure 842 represented by `tree' will be deallocated. 843 844 CSC_NOTFOUND ... if not successful. 845 846 CSC_BADARG ..... if libcsc was compiled with the DEBUG macro and 847 `tree' or `cbFn' is NULL. 848 849 CSC_CORRUPT .... if libcsc was compiled with the DEBUG macro and 850 CSCbinTreeDel() detects something munged up in the 851 tree or in some internal data. 852 853DESCRIPTION 854 CSCbinTreeDel() delete the balanced binary tree and the opaque 855 CSCbinTreeType data structure represented by `tree'. Probably the only 856 way to get a valid CSCbinTreeType data structure in the first place is 857 by calling CSCbinTreeNew(). 858 859 `cbFn' is a pointer to a libcsc CSCgenFnType function that is called for 860 EACH NODE in the tree, before each node is deallocated. The prototype 861 for CSCgenFnType is: 862 863 int (*CSCgenFnType) (int, int, void*); 864 865 The client callback function `cbFn' is called with the client defined 866 node data: 867 868 (*cbFn) (tag, dataSize, dataPtr); 869 870 This gives the client an opportunity to process the client node data 871 (such as CSCmemFree() any client CSCmemAlloc()'d node data) before the 872 node is deallocated. 873 874BUGS 875 When CSCbinTreeDel() fails to deallocate internal nodes, in some 876 conditions, CSC_OK may still be returned. 877 878SEE ALSO 879 CSCbinTreeNew(3) 880 CSCbinTreeInsert(3) 881 CSCbinTreeTagOrderedInsert(3) 882 CSCbinTreeTraverse(3) 883 CSCbinTreeUserSearch(3) 884 CSCbinTreeTagSearch(3) 885 CSCbinTreeStat(3) 886 CSCbinTreePrint(3) 887 CSCbinTreeNodeNew(3) 888 CSCbinTreeNodeDel(3) 889 CSCbinTreeNodeJoin(3) 890 CSCbinTreeNodeBreak(3) 891 CSCbinTreeNodeTraverse(3) 892 CSCbinTreeNodeUserSearch(3) 893 CSCbinTreeNodeTagSearch(3) 894 CSCbinTreeNodeStat(3) 895 CSCbinTreeNodePrint(3) 896 897 898------------------------------------------------------------------------ 899CSCbinTreeInsert(3) 900 901NAME 902 CSCbinTreeInsert - insert a node into a libcsc balanced binary tree 903 904SYNOPSYS 905 #include "libcsc.h" 906 907 int CSCbinTreeInsert ( 908 CSCbinTreeType const tree, 909 CSCbinTreeNodeType const node, 910 CSCcmpFnType cmpfn 911 ); 912 913RETURN VALUE 914 CSC_OK ........ if successful. 915 916 CSC_DUPKEY .... if `node' already exists in `tree'; this is defined 917 by the value of tree nodes' tags and is discerned by 918 the client callback function pointed to by `cmpfn'. 919 920 CSC_BADARG .... if libcsc was compiled with the DEBUG macro and 921 `tree', `node', or `cmpfn' is NULL. 922 923 CSC_CORRUPT ... if libcsc was compiled with the DEBUG macro and 924 CSCbinTreeInsert() detects something munged up in the 925 tree or in some internal data. 926 927DESCRIPTION 928 CSCbinTreeInsert() inserts `node' into the libcsc balanced binary tree 929 `tree', and then maintains the balance. 930 931 DANGER Take care to never insert a node that was joined with another 932 with CSCbinTreeNodeJoin() because it lacks balance information 933 and will completely whack a balanced tree. 934 935 `cmpfn' is a pointer to a libcsc CSCcmpFnType function that is called 936 for each node in the tree, until the node pointed to by node is 937 inserted. The prototype for `cmpfn' is: 938 939 int (*cmpfn) (void*, void*); 940 941 The client callback function `cmpfn' is called to compare the tag 942 field values of the node at node with a node, P, in the tree (note 943 the actual arguments are the addresses of the tag fields): 944 945 (*cmpfuncptr) ((void*)&node->tag, (void*)&P->tag); 946 947 This gives the client control over the insertion order. The 948 CSCcmpFnType function should return only the values -1, 0, and 1: 949 950 -1 .... indicates less than (new node goes into left subtree). 951 0 .... indicates a duplicate. 952 1 .... indicates more than (new node goes into right subtree). 953 954 The tag field of libcsc balanced binary tree nodes is a long, but its 955 semantics are entirely up to the client. 956 957 Insertion metrics, count comparisons and subtree rotations, can be 958 gotten with CSCbinTreeStat(). 959 960CREDITS 961 The balanced tree insertion algorithm is directly taken from Donald E. 962 Knuth, "Sorting and Searching," The Art of Computer Programming, vol. 3 963 (Reading Mass.: Addison-Wesley 1973). 964 965SEE ALSO 966 CSCbinTreeNew(3) 967 CSCbinTreeDel(3) 968 CSCbinTreeTagOrderedInsert(3) 969 CSCbinTreeTraverse(3) 970 CSCbinTreeUserSearch(3) 971 CSCbinTreeTagSearch(3) 972 CSCbinTreeStat(3) 973 CSCbinTreePrint(3) 974 CSCbinTreeNodeNew(3) 975 CSCbinTreeNodeDel(3) 976 CSCbinTreeNodeJoin(3) 977 CSCbinTreeNodeBreak(3) 978 CSCbinTreeNodeTraverse(3) 979 CSCbinTreeNodeUserSearch(3) 980 CSCbinTreeNodeTagSearch(3) 981 CSCbinTreeNodeStat(3) 982 CSCbinTreeNodePrint(3) 983 984 985------------------------------------------------------------------------ 986CSCbinTreeNew(3) 987 988NAME 989 CSCbinTreeNew - create an empty libcsc balanced binary tree 990 991SYNOPSYS 992 #include "libcsc.h" 993 994 CSCbinTreeType CSCbinTreeNew ( 995 const char* namePtr, 996 CSCmonFnType monFunc, 997 const void* monData, 998 CSCprofileType profiling 999 ); 1000 1001RETURN VALUE 1002 CSCbinTreeNew(), if successful, returns an opaque data type that 1003 represents the newly created libcsc balanced binary tree, or NULL if 1004 otherwise unsuccessful. 1005 1006DESCRIPTION 1007 CSCbinTreeNew() creates and initializes a libcsc balanced binary tree 1008 and returns a CSCbinTreeType; the data structure is opaque. 1009 1010 DANGER Take care to never insert into a balanced binary tree a node 1011 that was joined with another by using CSCbinTreeNodeJoin() 1012 because it lacks balance information and will completely whack 1013 a balanced tree. 1014 1015 DANGER Never, never, never use CSCbinTreeNodeBreak() on a node in a 1016 libcsc balanced binary tree. 1017 1018 In general: do not try mixing the CSCbinTree and CSCbinTreeNode 1019 functions on the same tree. 1020 1021SEE ALSO 1022 CSCbinTreeDel(3) 1023 CSCbinTreeInsert(3) 1024 CSCbinTreeTagOrderedInsert(3) 1025 CSCbinTreeTraverse(3) 1026 CSCbinTreeUserSearch(3) 1027 CSCbinTreeTagSearch(3) 1028 CSCbinTreeStat(3) 1029 CSCbinTreePrint(3) 1030 CSCbinTreeNodeNew(3) 1031 CSCbinTreeNodeDel(3) 1032 CSCbinTreeNodeJoin(3) 1033 CSCbinTreeNodeBreak(3) 1034 CSCbinTreeNodeTraverse(3) 1035 CSCbinTreeNodeUserSearch(3) 1036 CSCbinTreeNodeTagSearch(3) 1037 CSCbinTreeNodeStat(3) 1038 CSCbinTreeNodePrint(3) 1039 1040 1041------------------------------------------------------------------------ 1042CSCbinTreeNodeBreak(3) 1043 1044NAME 1045 CSCbinTreeNodeBreak - break libcsc binary tree at a node 1046 1047SYNOPSYS 1048 #include "libcsc.h" 1049 1050 int CSCbinTreeNodeBreak ( 1051 CSCbinTreeNodeType const node, 1052 CSCbinTreeNodeType* const leftPtr, 1053 CSCbinTreeNodeType* const rightPtr 1054 ); 1055 1056RETURN VALUE 1057 CSCbinTreeNodeBreak() returns CSC_OK, unless node is NULL, in which 1058 case CSC_BADARG is returned. 1059 1060DESCRIPTION 1061 CSCbinTreeNodeBreak() takes `node' and optionally replaces its left 1062 and/or right node pointers with NULL and writes its original left and/or 1063 right node pointers to the CSCbinTreeNodeTypethat are pointed to by 1064 `leftPtr' and `rightPtr'. 1065 1066 NEVER, EVER do this to a node in a libcsc balanced binary tree. Only 1067 use CSCbinTreeNodeBreak() on nodes in trees that are built with 1068 CSCbinTreeNodeJoin(). 1069 1070 If `leftPtr' is not NULL, then `node''s left node is written to the 1071 CSCbinTreeNodeType pointed to by `leftPtr'. 1072 1073 If `rightPtr' is not NULL, then `node''s right node is written to the 1074 CSCbinTreeNodeType pointed to by `rightPtr'. 1075 1076 Remember .....> Either of the left and/or right nodes that may be 1077 returned via `leftPtr' and `rightPtr' may be NULL; 1078 certainly this is the case when node is a leaf node. 1079 1080BUGS 1081 Odd But True Department: If `leftPtr' and `rightPtr' are both NULL then 1082 no action is taken and CSC_OK is returned. 1083 1084SEE ALSO 1085 CSCbinTreeNew(3) 1086 CSCbinTreeDel(3) 1087 CSCbinTreeInsert(3) 1088 CSCbinTreeTagOrderedInsert(3) 1089 CSCbinTreeTraverse(3) 1090 CSCbinTreeUserSearch(3) 1091 CSCbinTreeTagSearch(3) 1092 CSCbinTreeStat(3) 1093 CSCbinTreePrint(3) 1094 CSCbinTreeNodeNew(3) 1095 CSCbinTreeNodeDel(3) 1096 CSCbinTreeNodeJoin(3) 1097 CSCbinTreeNodeTraverse(3) 1098 CSCbinTreeNodeUserSearch(3) 1099 CSCbinTreeNodeTagSearch(3) 1100 CSCbinTreeNodeStat(3) 1101 CSCbinTreeNodePrint(3) 1102 1103 1104------------------------------------------------------------------------ 1105CSCbinTreeNodeDel(3) 1106 1107NAME 1108 CSCbinTreeNodeDel - deallocate a libcsc binary tree node 1109 1110SYNOPSYS 1111 #include "libcsc.h" 1112 1113 int CSCbinTreeNodeDel ( 1114 CSCbinTreeNodeType const node 1115 ); 1116 1117RETURN VALUE 1118 CSC_OK ......... if successful. 1119 1120 CSC_NOTFOUND ... if not successful. 1121 1122 CSC_BADARG ..... if libcsc was compiled with the DEBUG macro and node is 1123 NULL. 1124 1125 CSC_CORRUPT .... if libcsc was compiled with the DEBUG macro and some 1126 internal tree data is munged up. 1127 1128DESCRIPTION 1129 CSCbinTreeNodeDel() deallocates `node'. 1130 1131 NEVER, EVER do this to a node in a libcsc balanced binary tree. Only 1132 use CSCbinTreeNodeDel() on nodes removed from tree that are built with 1133 CSCbinTreeNodeJoin(). Nodes in a libcsc balanced binary trees cannot 1134 be removed. :/ 1135 1136 The node data should be retreived with CSCbinTreeNodeStat() and removed, 1137 or otherwise cleaned up, before calling this function. 1138 1139SEE ALSO 1140 CSCbinTreeNew(3) 1141 CSCbinTreeDel(3) 1142 CSCbinTreeInsert(3) 1143 CSCbinTreeTagOrderedInsert(3) 1144 CSCbinTreeTraverse(3) 1145 CSCbinTreeUserSearch(3) 1146 CSCbinTreeTagSearch(3) 1147 CSCbinTreeStat(3) 1148 CSCbinTreePrint(3) 1149 CSCbinTreeNodeNew(3) 1150 CSCbinTreeNodeJoin(3) 1151 CSCbinTreeNodeBreak(3) 1152 CSCbinTreeNodeTraverse(3) 1153 CSCbinTreeNodeUserSearch(3) 1154 CSCbinTreeNodeTagSearch(3) 1155 CSCbinTreeNodeStat(3) 1156 CSCbinTreeNodePrint(3) 1157 1158 1159------------------------------------------------------------------------ 1160CSCbinTreeNodeJoin(3) 1161 1162NAME 1163 CSCbinTreeNodeJoin - join libcsc binary tree nodes 1164 1165SYNOPSYS 1166 #include "libcsc.h" 1167 1168 int CSCbinTreeNodeJoin ( 1169 CSCbinTreeNodeType const node, 1170 CSCbinTreeNodeType const left, 1171 CSCbinTreeNodeType const right 1172 ); 1173 1174RETURN VALUE 1175 CSCbinTreeNodeJoin() returns CSC_OK unless node is NULL, in which case 1176 CSC_BADARG is returned. If libcsc is compiled with the DEBUG macro and 1177 some internal tree data is munged, then rtsBinTreeNodeJoin() returns 1178 CSC_CORRUPT. 1179 1180DESCRIPTION 1181 CSCbinTreeNodeJoin() simply assigns `left' to the left node pointer of 1182 `node', and assigns `right' to the right pointer of `node'. 1183 1184 Use CSCbinTreeNodeJoin() to create your own libcsc binary trees that 1185 are distinct and separate from libcsc balanced binary trees that are 1186 created with CSCbinTreeNew() and CSCbinTreeInsert(). 1187 1188 It is completely acceptable for `left' and/or `right' to be NULL. 1189 1190 Beware, if the the `left' and/or `right' node pointer of the node is 1191 already in use, then it will be lost. Don't create dangling trees. 1192 1193SEE ALSO 1194 CSCbinTreeNew(3) 1195 CSCbinTreeDel(3) 1196 CSCbinTreeInsert(3) 1197 CSCbinTreeTagOrderedInsert(3) 1198 CSCbinTreeTraverse(3) 1199 CSCbinTreeUserSearch(3) 1200 CSCbinTreeTagSearch(3) 1201 CSCbinTreeStat(3) 1202 CSCbinTreePrint(3) 1203 CSCbinTreeNodeNew(3) 1204 CSCbinTreeNodeDel(3) 1205 CSCbinTreeNodeBreak(3) 1206 CSCbinTreeNodeTraverse(3) 1207 CSCbinTreeNodeUserSearch(3) 1208 CSCbinTreeNodeTagSearch(3) 1209 CSCbinTreeNodeStat(3) 1210 CSCbinTreeNodePrint(3) 1211 1212 1213------------------------------------------------------------------------ 1214CSCbinTreeNodeNew(3) 1215 1216NAME 1217 CSCbinTreeNodeNew - create a new empty libcsc binary tree node 1218 1219SYNOPSYS 1220 #include "libcsc.h" 1221 1222 CSCbinTreeNodeType CSCbinTreeNodeNew ( 1223 CSCdataCntrlType push, 1224 long tag, 1225 const void* const dataPtr, 1226 size_t dataSize 1227 ); 1228 1229RETURN VALUE 1230 CSCbinTreeNodeNew(), if successful, returns a CSCbinTreeNodeType for the 1231 newly created libcsc binary tree node, or NULL if otherwise not 1232 successful. 1233 1234DESCRIPTION 1235 CSCbinTreeNodeNew() creates a new libcsc binary tree node that is 1236 appropriate for use: 1237 1238 1) with CSCbinTreeInsert() on libcsc balanced binary trees that 1239 are created with CSCbinTreeNew() 1240 1241 2) for joining together with CSCbinTreeNodeJoin() 1242 1243 The new node's `tag' is used by client callback compare functions when 1244 libcsc balanced binary tree nodes are inserted, searched, or traversed. 1245 1246 `push' is one of 1247 1248 CSC_DATA_DUP the data pointed to by `dataPtr', for `dataSize' 1249 bytes, is duplicated and put into the new node. 1250 1251 CSC_DATA_NODUP `dataPtr' and `dataSize' are directly put into 1252 the new node. This new node will retain the 1253 reference to the data at `dataPtr'; therefore, 1254 it should be clear that if that data is changed 1255 (or deallocated!) then it is the data that this 1256 new node points to that is affected. 1257 1258SEE ALSO 1259 CSCbinTreeNew(3) 1260 CSCbinTreeDel(3) 1261 CSCbinTreeInsert(3) 1262 CSCbinTreeTagOrderedInsert(3) 1263 CSCbinTreeTraverse(3) 1264 CSCbinTreeUserSearch(3) 1265 CSCbinTreeTagSearch(3) 1266 CSCbinTreeStat(3) 1267 CSCbinTreePrint(3) 1268 CSCbinTreeNodeDel(3) 1269 CSCbinTreeNodeJoin(3) 1270 CSCbinTreeNodeBreak(3) 1271 CSCbinTreeNodeTraverse(3) 1272 CSCbinTreeNodeUserSearch(3) 1273 CSCbinTreeNodeTagSearch(3) 1274 CSCbinTreeNodeStat(3) 1275 CSCbinTreeNodePrint(3) 1276 1277 1278------------------------------------------------------------------------ 1279CSCbinTreeNodePrint(3) 1280 1281NAME 1282 CSCbinTreeNodePrint - print the values of a libcsc binary tree node 1283 1284SYNOPSYS 1285 #include "libcsc.h" 1286 1287 int CSCbinTreeNodePrint ( 1288 CSCbinTreeNodeType const node 1289 ); 1290 1291RETURN VALUE 1292 CSCbinTreeNodePrint() returns CSC_OK. If libcsc was compiled with the 1293 DEBUG macro and node is NULL, then CSCbinTreeNodePrint() returns 1294 CSC_BADARG. If libcsc was compiled with the DEBUG macro and some 1295 internal tree data is munged up then CSCbinTreeNodePrint() returns 1296 CSC_CORRUPT. 1297 1298DESCRIPTION 1299 CSCbinTreeNodePrint() writes to standard output the values of the 1300 balance, tag, and data size fields of node. 1301 1302SEE ALSO 1303 CSCbinTreeNew(3) 1304 CSCbinTreeDel(3) 1305 CSCbinTreeInsert(3) 1306 CSCbinTreeTagOrderedInsert(3) 1307 CSCbinTreeTraverse(3) 1308 CSCbinTreeUserSearch(3) 1309 CSCbinTreeTagSearch(3) 1310 CSCbinTreeStat(3) 1311 CSCbinTreePrint(3) 1312 CSCbinTreeNodeNew(3) 1313 CSCbinTreeNodeDel(3) 1314 CSCbinTreeNodeJoin(3) 1315 CSCbinTreeNodeBreak(3) 1316 CSCbinTreeNodeTraverse(3) 1317 CSCbinTreeNodeUserSearch(3) 1318 CSCbinTreeNodeTagSearch(3) 1319 CSCbinTreeNodeStat(3) 1320 1321 1322------------------------------------------------------------------------ 1323CSCbinTreeNodeStat(3) 1324 1325NAME 1326 CSCbinTreeNodeStat - retrieve fields from a libcsc binary tree node 1327 1328SYNOPSYS 1329 #include "libcsc.h" 1330 1331 int CSCbinTreeNodeStat ( 1332 CSCbinTreeNodeType const node, 1333 CSCdataCntrlType* const pushPtr, 1334 long* const tagPtr, 1335 size_t* const sizePtr, 1336 void** const dataPtrPtr 1337 ); 1338 1339RETURN VALUE 1340 CSCbinTreeNodeStat() returns CSC_OK. If libcsc was compiled with the 1341 DEBUG macro and node is NULL, then CSCbinTreeNodeStat() returns 1342 CSC_BADARG. If libcsc was compiled with the DEBUG macro and some 1343 internal tree data is munged up then CSCbinTreeNodeStat() returns 1344 CSC_CORRUPT. 1345 1346DESCRIPTION 1347 CSCbinTreeNodeStat() is used to get values of various fields from the 1348 given libcsc binary tree node `node'. 1349 1350 if `pushPtr' is not NULL, then the value of the push field of `node' is 1351 written to the CSCdataCntrlType pointed to by `pushPtr'. 1352 1353 if `tagPtr' is not NULL, then the value of the tag field of `node' is 1354 written to the long pointed to by `tagPtr'. 1355 1356 if `sizePtr' is not NULL, then the value of the data size field of 1357 `node' is written to the size_t pointed to by `sizePtr'. 1358 1359 if `dataPtrPtr' is not NULL, then the value of the data pointer field 1360 `node' is written to the void pointer pointed to by `dataPtrPtr'. 1361 1362 If tagPtr, sizePtr, and dataPtrPtr are all NULL, then this function 1363 does nothing interesting. 1364 1365SEE ALSO 1366 CSCbinTreeNew(3) 1367 CSCbinTreeDel(3) 1368 CSCbinTreeInsert(3) 1369 CSCbinTreeTagOrderedInsert(3) 1370 CSCbinTreeTraverse(3) 1371 CSCbinTreeUserSearch(3) 1372 CSCbinTreeTagSearch(3) 1373 CSCbinTreeStat(3) 1374 CSCbinTreePrint(3) 1375 CSCbinTreeNodeNew(3) 1376 CSCbinTreeNodeDel(3) 1377 CSCbinTreeNodeJoin(3) 1378 CSCbinTreeNodeBreak(3) 1379 CSCbinTreeNodeTraverse(3) 1380 CSCbinTreeNodeUserSearch(3) 1381 CSCbinTreeNodeTagSearch(3) 1382 CSCbinTreeNodePrint(3) 1383 1384 1385------------------------------------------------------------------------ 1386CSCbinTreeNodeTagSearch(3) 1387 1388NAME 1389 CSCbinTreeNodeTagSearch - search a libcsc binary tree for a given tag 1390 1391SYNOPSYS 1392 #include "libcsc.h" 1393 1394 CSCbinTreeNodeType CSCbinTreeNodeTagSearch ( 1395 CSCbinTreeNodeType const node, 1396 long tag 1397 ); 1398 1399RETURN VALUE 1400 CSCbinTreeNodeTagSearch(), if successful, returns a CSCbinTreeNodeType 1401 that is the node whose tag-field value is equal to tag, or NULL if 1402 otherwise not successful. 1403 1404DESCRIPTION 1405 CSCbinTreeNodeTagSearch() searches `node', and recursively all of its 1406 children, for a node with a tag-field that is equal to `tag'. 1407 1408 A recursive postfix tree traversal algorithm is used. 1409 1410SEE ALSO 1411 CSCbinTreeNew(3) 1412 CSCbinTreeDel(3) 1413 CSCbinTreeInsert(3) 1414 CSCbinTreeTagOrderedInsert(3) 1415 CSCbinTreeTraverse(3) 1416 CSCbinTreeUserSearch(3) 1417 CSCbinTreeTagSearch(3) 1418 CSCbinTreeStat(3) 1419 CSCbinTreePrint(3) 1420 CSCbinTreeNodeNew(3) 1421 CSCbinTreeNodeDel(3) 1422 CSCbinTreeNodeJoin(3) 1423 CSCbinTreeNodeBreak(3) 1424 CSCbinTreeNodeTraverse(3) 1425 CSCbinTreeNodeUserSearch(3) 1426 CSCbinTreeNodeStat(3) 1427 CSCbinTreeNodePrint(3) 1428 1429 1430------------------------------------------------------------------------ 1431CSCbinTreeNodeTraverse(3) 1432 1433NAME 1434 CSCbinTreeNodeTraverse - traverse a libcsc binary tree 1435 1436 1437SYNOPSYS 1438 #include "libcsc.h" 1439 1440 int CSCbinTreeNodeTraverse ( 1441 const char* const method, 1442 CSCbinTreeNodeType const node, 1443 CSCcmpFnType clientFn, 1444 const void* const clientData 1445 ); 1446 1447RETURN VALUE 1448 CSCbinTreeNodeTraverse() returns CSC_OK on a successful traversal with 1449 the desired node being found, or CSC_NOTFOUND on a successful traversal 1450 with the desired node being not found. 1451 1452 If libcsc was compiled with the DEBUG macro and some internal tree data 1453 is munged up then rtsBinTreeNodeTraverse() returns CSC_CORRUPT. 1454 1455 If libcsc was compiled with the DEBUG macro and invalid arguments are 1456 detected, then rtsBinTreeNodeTraverse() returns CSC_BADARG. 1457 1458DESCRIPTION 1459 CSCbinTreeNodeTraverse() traverses a libcsc binary tree beginning with 1460 `node'. `method' is a string that specifies the search algorithm (case 1461 IS important): 1462 1463 method 1464 ------ 1465 1466 "PREFIX" 1467 "INFIX" 1468 "POSTFIX" 1469 1470 If `clientFn' is not NULL, then it is a pointer to a libcsc CSCcmpFnType 1471 function that is called for EACH NODE in the tree. The prototype for 1472 clientFn is: 1473 1474 int (*clientFn) (void*, void*); 1475 1476 The client callback function `clientFn' is called with the client 1477 supplied data and a node pointer (on which the client then needs to use 1478 CSCbinTreeNodeQuery()): 1479 1480 stat = (*clientFn) ((void*)&node, (void*)clientData); 1481 1482 This gives the client an opportunity to terminate the traversal by 1483 returning CSC_OK; otherwise, the function pointed to by `clientFn' 1484 should return CSC_NOTFOUND. 1485 1486 If `clientFn' returns any value besides CSC_NOTFOUND, then the tree 1487 traversal is terminated, and the return value from 1488 CSCbinTreeNodeTraverse() will be the value returned from `clientFn'. 1489 In this case, if libcsc was compiled with the DEBUG macro, then there 1490 will be an assertion if the return value is not CSC_OK or CSC_NOTFOUND, 1491 but no other processing is affected. 1492 1493 If `clientFn' is NULL, then the libcsc binary tree is traversed 1494 according to `method', but nothing interesting happens. 1495 1496SEE ALSO 1497 CSCbinTreeNew(3) 1498 CSCbinTreeDel(3) 1499 CSCbinTreeInsert(3) 1500 CSCbinTreeTagOrderedInsert(3) 1501 CSCbinTreeTraverse(3) 1502 CSCbinTreeUserSearch(3) 1503 CSCbinTreeTagSearch(3) 1504 CSCbinTreeStat(3) 1505 CSCbinTreePrint(3) 1506 CSCbinTreeNodeNew(3) 1507 CSCbinTreeNodeDel(3) 1508 CSCbinTreeNodeJoin(3) 1509 CSCbinTreeNodeBreak(3) 1510 CSCbinTreeNodeUserSearch(3) 1511 CSCbinTreeNodeTagSearch(3) 1512 CSCbinTreeNodeStat(3) 1513 CSCbinTreeNodePrint(3) 1514 1515 1516------------------------------------------------------------------------ 1517CSCbinTreeNodeUserSearch(3) 1518 1519NAME 1520 CSCbinTreeNodeUserSearch - arbitrary libcsc binary tree traversal 1521 1522SYNOPSYS 1523 #include "libcsc.h" 1524 1525 CSCbinTreeNodeType CSCbinTreeNodeUserSearch ( 1526 CSCbinTreeNodeType const node, 1527 CSCcmpFnType clientFn, 1528 const void* const clientData 1529 ); 1530 1531RETURN VALUE 1532 CSCbinTreeNodeUserSearch(), if successful, returns a CSCbinTreeNodeType 1533 that is the desired libcsc binary tree node; otherwise NULL is returned 1534 if not successful. 1535 1536DESCRIPTION 1537 CSCbinTreeNodeUserSearch() traverses the libcsc binary tree beginning 1538 with `node'. The tree traversal algorithm and traversal termination are 1539 controlled by the client callback function `clientFn'. 1540 1541 `clientFn' is a libcsc CSCcmpFnType function that is called for each 1542 node in the tree. The prototype for clientFn is: 1543 1544 int (*clientFn) (void*, void*); 1545 1546 `clientFn' is called with the client supplied data and a node pointer 1547 (on which the client then needs to use CSCbinTreeNodeQuery()): 1548 1549 switchValue = (*clientFn) ((void*)&node, (void*)clientData); 1550 1551 This gives the client control over tree traversal. `clientFn' should 1552 return only the values -1, 0, and 1: 1553 1554 -1 .... traversal continues on left node. 1555 0 .... terminate traversal. 1556 1 .... traversal continues on right node. 1557 1558 This function probably makes sense only with oddly shaped binary trees 1559 constructed with CSCbinTreeNodeJoin(). 1560 1561BUGS 1562 If `clientFn' is NULL, and libcsc was NOT compiled with the DEBUG macro, 1563 then CSCbinTreeNodeUserSearch() probably dies a horrible segfault death. 1564 1565SEE ALSO 1566 CSCbinTreeNew(3) 1567 CSCbinTreeDel(3) 1568 CSCbinTreeInsert(3) 1569 CSCbinTreeTagOrderedInsert(3) 1570 CSCbinTreeTraverse(3) 1571 CSCbinTreeUserSearch(3) 1572 CSCbinTreeTagSearch(3) 1573 CSCbinTreeStat(3) 1574 CSCbinTreePrint(3) 1575 CSCbinTreeNodeNew(3) 1576 CSCbinTreeNodeDel(3) 1577 CSCbinTreeNodeJoin(3) 1578 CSCbinTreeNodeBreak(3) 1579 CSCbinTreeNodeTraverse(3) 1580 CSCbinTreeNodeTagSearch(3) 1581 CSCbinTreeNodeStat(3) 1582 CSCbinTreeNodePrint(3) 1583 1584 1585------------------------------------------------------------------------ 1586CSCbinTreePrint(3) 1587 1588NAME 1589 CSCbinTreePrint - print a libcsc balanced binary tree 1590 1591SYNOPSYS 1592 #include "libcsc.h" 1593 1594 int CSCbinTreePrint ( 1595 CSCbinTreeType const tree 1596 ); 1597 1598RETURN VALUE 1599 CSCbinTreePrint() returns CSC_OK. 1600 1601 If libcsc was compiled with the DEBUG macro and tree is NULL, then 1602 CSCbinTreePrint() returns CSC_BADARG. 1603 1604 If libcsc was compiled with the DEBUG macro and some internal tree data 1605 is munged up, then CSCbinTreePrint() returns CSC_CORRUPT. 1606 1607DESCRIPTION 1608 CSCbinTreePrint() writes to standard output these statistics for the 1609 libcsc balanced binary tree `tree': 1610 1611 statistic 1612 --------- 1613 count ......... total number of nodes in the tree. 1614 height ........ maximum current height of the tree. 1615 compares ...... number of compares from most recent insert. 1616 rotates ....... number of rotations from most recent insert. 1617 1618 After the overall tree statistics, various fields of all the nodes in 1619 tree are written, to standard output, via an internal call to 1620 CSCbinTreeNodePrint(). For each node, the value of the left and right 1621 node's tag field is printed for tracability. 1622 1623 A prefix binary tree traversal algorithm is used. 1624 1625SEE ALSO 1626 CSCbinTreeNew(3) 1627 CSCbinTreeDel(3) 1628 CSCbinTreeInsert(3) 1629 CSCbinTreeTagOrderedInsert(3) 1630 CSCbinTreeTraverse(3) 1631 CSCbinTreeUserSearch(3) 1632 CSCbinTreeTagSearch(3) 1633 CSCbinTreeStat(3) 1634 CSCbinTreeNodeNew(3) 1635 CSCbinTreeNodeDel(3) 1636 CSCbinTreeNodeJoin(3) 1637 CSCbinTreeNodeBreak(3) 1638 CSCbinTreeNodeTraverse(3) 1639 CSCbinTreeNodeUserSearch(3) 1640 CSCbinTreeNodeTagSearch(3) 1641 CSCbinTreeNodeStat(3) 1642 CSCbinTreeNodePrint(3) 1643 1644 1645------------------------------------------------------------------------ 1646CSCbinTreeStat(3) 1647 1648NAME 1649 CSCbinTreeStat - retrieve libcsc balanced binary tree statistics 1650 1651SYNOPSYS 1652 #include "libcsc.h" 1653 1654 int CSCbinTreeStat ( 1655 CSCbinTreeType const tree, 1656 size_t* const countPtr, 1657 size_t* const heightPtr, 1658 size_t* const comparesPtr, 1659 size_t* const rotatesPtr 1660 ); 1661 1662RETURN VALUE 1663 CSCbinTreeStat() returns CSC_OK. 1664 1665 If libcsc was compiled with the DEBUG macro and tree is NULL, then 1666 CSCbinTreeStat() returns CSC_BADARG. 1667 1668 If libcsc was compiled with the DEBUG macro and some internal tree data 1669 is munged up, then CSCbinTreeStat() returns CSC_CORRUPT. 1670 1671DESCRIPTION 1672 CSCbinTreeStat() retrieves these statistics from the libcsc balanced 1673 binary tree `tree': 1674 1675 statistic 1676 --------- 1677 count ......... total number of nodes in the tree. 1678 height ........ maximum current height of the tree. 1679 compares ...... number of compares from most recent insert. 1680 rotates ....... number of rotations from most recent insert. 1681 1682 If `countPtr' is not NULL, then the total number of nodes in the tree is 1683 written to the size_t pointed to by `countPtr'. 1684 1685 If `heightPtr' is not NULL, then the maximum current height of the tree 1686 is written to the size_t pointed to by `heightPtr'. 1687 1688 If `comparesPtr' is not NULL, then the number of compares from most 1689 recent insert is written to the size_t pointed to by `comparesPtr'. 1690 1691 If `rotatesPtr' is not NULL, then the number of rotations from most 1692 recent insert is written to the size_t pointed to by `rotatesPtr'. 1693 1694 If `countPtr', `heightPtr', `comparesPtr', and `rotatesPtr' are all 1695 NULL, then this function does nothing interesting. 1696 1697SEE ALSO 1698 CSCbinTreeNew(3) 1699 CSCbinTreeDel(3) 1700 CSCbinTreeInsert(3) 1701 CSCbinTreeTagOrderedInsert(3) 1702 CSCbinTreeTraverse(3) 1703 CSCbinTreeUserSearch(3) 1704 CSCbinTreeTagSearch(3) 1705 CSCbinTreePrint(3) 1706 CSCbinTreeNodeNew(3) 1707 CSCbinTreeNodeDel(3) 1708 CSCbinTreeNodeJoin(3) 1709 CSCbinTreeNodeBreak(3) 1710 CSCbinTreeNodeTraverse(3) 1711 CSCbinTreeNodeUserSearch(3) 1712 CSCbinTreeNodeTagSearch(3) 1713 CSCbinTreeNodeStat(3) 1714 CSCbinTreeNodePrint(3) 1715 1716 1717------------------------------------------------------------------------ 1718CSCbinTreeTagOrderedInsert(3) 1719 1720NAME 1721 CSCbinTreeTagOrderedInsert - put node into libcsc balanced binary tree 1722 1723SYNOPSYS 1724 #include "libcsc.h" 1725 1726 int CSCbinTreeTagOrderedInsert ( 1727 CSCbinTreeType const tree, 1728 CSCbinTreeNodeType const node 1729 ); 1730 1731RETURN VALUE 1732 CSC_OK ........ if successful. 1733 1734 CSC_DUPKEY .... if `node' already exists in `tree' (this is defined 1735 by the value of the nodes' tags). 1736 1737 CSC_BADARG .... if libcsc was compiled with the DEBUG macro and `tree' 1738 or `node' is NULL. 1739 1740 CSC_CORRUPT ... if libcsc was compiled with the DEBUG macro and 1741 CSCbinTreeTagOrderedInsert() detects something munged 1742 up in the tree or in some internal data. 1743 1744DESCRIPTION 1745 CSCbinTreeTagOrderedInsert() inserts `node' into the libcsc balanced 1746 binary tree `tree', and then CSCbinTreeTagOrderedInsert() maintains the 1747 balance. 1748 1749 The insertion order is strictly based upon the tag field values of node 1750 and the tag field values of the nodes in the libcsc balanced binary 1751 tree. 1752 1753 DANGER Take care to never insert a node that was joined with another 1754 by using CSCbinTreeNodeJoin() because it lacks balance 1755 information and will completely whack a balanced tree. 1756 1757 This function internally calls CSCbinTreeInsert() with its own internal 1758 tag comparison function. 1759 1760 Insertion metrics, count comparisons and subtree rotations, can be 1761 gotten with CSCbinTreeStat(). 1762 1763CREDITS 1764 The balanced tree insertion algorithm is directly taken from Donald E. 1765 Knuth, "Sorting and Searching," The Art of Computer Programming, vol. 3 1766 (Reading Mass.: Addison-Wesley 1973). 1767 1768SEE ALSO 1769 CSCbinTreeNew(3) 1770 CSCbinTreeDel(3) 1771 CSCbinTreeInsert(3) 1772 CSCbinTreeTraverse(3) 1773 CSCbinTreeUserSearch(3) 1774 CSCbinTreeTagSearch(3) 1775 CSCbinTreeStat(3) 1776 CSCbinTreePrint(3) 1777 CSCbinTreeNodeNew(3) 1778 CSCbinTreeNodeDel(3) 1779 CSCbinTreeNodeJoin(3) 1780 CSCbinTreeNodeBreak(3) 1781 CSCbinTreeNodeTraverse(3) 1782 CSCbinTreeNodeUserSearch(3) 1783 CSCbinTreeNodeTagSearch(3) 1784 CSCbinTreeNodeStat(3) 1785 CSCbinTreeNodePrint(3) 1786 1787 1788------------------------------------------------------------------------ 1789CSCbinTreeTagSearch(3) 1790 1791NAME 1792 CSCbinTreeTagSearch - search a balanced binary tree for node with tag 1793 1794SYNOPSYS 1795 #include "libcsc.h" 1796 1797 CSCbinTreeNodeType CSCbinTreeTagSearch ( 1798 CSCbinTreeType const tree, 1799 long tag 1800 ); 1801 1802RETURN VALUE 1803 CSCbinTreeTagSearch(), if successful, returns a CSCbinTreeNodeType that 1804 is a libcsc balanced binary tree node whose tag-field value is equal to 1805 `tag', or NULL if otherwise not successful. 1806 1807DESCRIPTION 1808 CSCbinTreeTagSearch() searches the libcsc balanced binary tree `tree' 1809 for a node with a tag-field that is equal to `tag'. 1810 1811 A recursive postfix tree traversal algorithm is used. 1812 1813SEE ALSO 1814 CSCbinTreeNew(3) 1815 CSCbinTreeDel(3) 1816 CSCbinTreeInsert(3) 1817 CSCbinTreeTagOrderedInsert(3) 1818 CSCbinTreeTraverse(3) 1819 CSCbinTreeUserSearch(3) 1820 CSCbinTreeStat(3) 1821 CSCbinTreePrint(3) 1822 CSCbinTreeNodeNew(3) 1823 CSCbinTreeNodeDel(3) 1824 CSCbinTreeNodeJoin(3) 1825 CSCbinTreeNodeBreak(3) 1826 CSCbinTreeNodeTraverse(3) 1827 CSCbinTreeNodeUserSearch(3) 1828 CSCbinTreeNodeTagSearch(3) 1829 CSCbinTreeNodeStat(3) 1830 CSCbinTreeNodePrint(3) 1831 1832 1833------------------------------------------------------------------------ 1834CSCbinTreeTraverse(3) 1835 1836NAME 1837 CSCbinTreeTraverse - traverse a libcsc balanced binary tree 1838 1839SYNOPSYS 1840 #include "libcsc.h" 1841 1842 int CSCbinTreeTraverse ( 1843 const char* const method, 1844 CSCbinTreeType const tree, 1845 CSCcmpFnType clientFn, 1846 const void* const clientData 1847 ); 1848 1849RETURN VALUE 1850 CSC_OK ......... on a successful traversal with the desired node being 1851 found. 1852 1853 CSC_NOTFOUND ... on a successful traversal with the desired node being 1854 not found. 1855 1856 CSC_BADARG ..... if libcsc was compiled with the DEBUG macro and 1857 `method', `tree', or `clientFn' is NULL. 1858 1859 CSC_CORRUPT .... if libcsc was compiled with the DEBUG macro and 1860 CSCbinTreeTraverse() detects something munged up in' 1861 the tree or in some internal data. 1862 1863DESCRIPTION 1864 CSCbinTreeTraverse() traverses the libcsc balanced binary tree `tree'. 1865 `method' is a string that specifies the search algorithm (case IS 1866 important): 1867 1868 method 1869 ------ 1870 1871 "PREFIX" 1872 "INFIX" 1873 "POSTFIX" 1874 1875 `clientFn' is a pointer to a libcsc CSCcmpFnType function that is 1876 called for EACH NODE in the tree. The prototype for CSCcmpFnType is: 1877 1878 int (*CSCcmpFnType) (void*, void*); 1879 1880 The client callback function `clientFn' is called with the client 1881 supplied data and a node pointer (on which the client then needs to use 1882 rtsBinTreeNodeQuery()): 1883 1884 stat = (*clientFn) ((void*)&node, (void*)clientData); 1885 1886 This gives the client an opportunity to terminate the traversal by 1887 `clientFn' returning CSC_OK (indicating a match); otherwise, `clientFn' 1888 should return CSC_NOTFOUND. 1889 1890 If `clientFn' returns any value besides CSC_NOTFOUND then the traversal 1891 is terminated, and the return value from CSCbinTreeTraverse() will be 1892 the value returned from `clientFn'. In this case, if libcsc was 1893 compiled with the DEBUG macro, then there will be an assertion if the 1894 return value is not CSC_OK or CSC_NOTFOUND, but no other processing is 1895 affected. 1896 1897 If clientFn is NULL, then the libcsc balanced binary tree is traversed 1898 according to method, but nothing interesting happens; except if libcsc 1899 was compiled with the DEBUG macro, in which case the tree will be 1900 sanity checked. 1901 1902SEE ALSO 1903 CSCbinTreeNew(3) 1904 CSCbinTreeDel(3) 1905 CSCbinTreeInsert(3) 1906 CSCbinTreeTagOrderedInsert(3) 1907 CSCbinTreeUserSearch(3) 1908 CSCbinTreeTagSearch(3) 1909 CSCbinTreeStat(3) 1910 CSCbinTreePrint(3) 1911 CSCbinTreeNodeNew(3) 1912 CSCbinTreeNodeDel(3) 1913 CSCbinTreeNodeJoin(3) 1914 CSCbinTreeNodeBreak(3) 1915 CSCbinTreeNodeTraverse(3) 1916 CSCbinTreeNodeUserSearch(3) 1917 CSCbinTreeNodeTagSearch(3) 1918 CSCbinTreeNodeStat(3) 1919 CSCbinTreeNodePrint(3) 1920 1921 1922------------------------------------------------------------------------ 1923CSCbinTreeUserSearch(3) 1924 1925NAME 1926 CSCbinTreeUserSearch - arbitrary search of libcsc balanced binary tree 1927 1928SYNOPSYS 1929 #include "libcsc.h" 1930 1931 CSCbinTreeNodeType CSCbinTreeUserSearch ( 1932 CSCbinTreeType const tree, 1933 CSCcmpFnType clientFn, 1934 const void* const clientData 1935 ); 1936 1937RETURN VALUE 1938 CSCbinTreeUserSearch(), if successful, returns a CSCbinTreeNodeType 1939 that is a node from the libcsc balanced binary tree `tree'. 1940 CSCbinTreeUserSearch() returns NULL, if not successful. 1941 1942DESCRIPTION 1943 CSCbinTreeUserSearch() traverses the libcsc balanced binary tree `tree'. 1944 The tree traversal algorithm and traversal termination are controlled by 1945 the client callback function `clientFn'. 1946 1947 `clientFn' is a pointer to a libcsc CSCcmpFnType function that is called 1948 for each node in `tree'. The prototype for clientFn is: 1949 1950 int (*clientFn) (void*, void*); 1951 1952 The client callback function `clientFn' is called with the client 1953 supplied data `clientData' and a node pointer (on which the client then 1954 needs to use CSCbinTreeNodeStat()): 1955 1956 switchValue = (*clientFn) ((void*)&node, (void*)clientData); 1957 1958 This gives the client control over tree traversal. `clientFn' should 1959 return only the values -1, 0, and 1: 1960 1961 -1 .... traversal continues on left node. 1962 0 .... terminate traversal. 1963 1 .... traversal continues on right node. 1964 1965BUGS 1966 This function probably makes no sense. 1967 1968 If `clientFn' is NULL, and libcsc was NOT compiled with the DEBUG macro, 1969 then CSCbinTreeUserSearch() probably dies a horrible segfault death. 1970 1971SEE ALSO 1972 CSCbinTreeNew(3) 1973 CSCbinTreeDel(3) 1974 CSCbinTreeInsert(3) 1975 CSCbinTreeTagOrderedInsert(3) 1976 CSCbinTreeTraverse(3) 1977 CSCbinTreeTagSearch(3) 1978 CSCbinTreeStat(3) 1979 CSCbinTreePrint(3) 1980 CSCbinTreeNodeNew(3) 1981 CSCbinTreeNodeDel(3) 1982 CSCbinTreeNodeJoin(3) 1983 CSCbinTreeNodeBreak(3) 1984 CSCbinTreeNodeTraverse(3) 1985 CSCbinTreeNodeUserSearch(3) 1986 CSCbinTreeNodeTagSearch(3) 1987 CSCbinTreeNodeStat(3) 1988 CSCbinTreeNodePrint(3) 1989 1990 1991------------------------------------------------------------------------ 1992CSCcflags(3) 1993 1994NAME 1995 CSCcflags - get string containing compiler command-line options 1996 1997SYNOPSYS 1998 #include "libcsc.h" 1999 2000 const char* CSCcflags (void); 2001 2002DESCRIPTION 2003 CSCldflags() returns a pointer to a constant ASCII-Z string containing 2004 the compiler specfic (cc) command-line options. 2005 2006SEE ALSO 2007 CSCstatStr(3) 2008 CSCldflags(3) 2009 CSClibs(3) 2010 CSCversion(3) 2011 CSCcredits(3) 2012 CSCchkup(3) 2013 2014 2015------------------------------------------------------------------------ 2016CSCchkup(3) 2017 2018NAME 2019 CSCchkup - check scalar data sizes assumed by libcsc 2020 2021SYNOPSYS 2022 #include "libcsc.h" 2023 2024 void CSCchkup (void); 2025 2026RETURN VALUE 2027 CSCchkup() returns no value. 2028 2029DESCRIPTION 2030 CSCchkup is a diagnostic function that checks libcsc assumptions made 2031 about scalar data sizes e.g., sizeof(int) is 4. 2032 2033SEE ALSO 2034 CSCstatStr(3) 2035 CSCcflags(3) 2036 CSCldflags(3) 2037 CSClibs(3) 2038 CSCversion(3) 2039 CSCcredits(3) 2040 2041 2042------------------------------------------------------------------------ 2043CSCcredits(3) 2044 2045NAME 2046 CSCcredits - get string containing the libcsc credits 2047 2048SYNOPSYS 2049 #include "libcsc.h" 2050 2051 const char* CSCcredits (void); 2052 2053DESCRIPTION 2054 CSCcredits() returns a pointer to a constant ASCII-Z string containing 2055 the names of the major libcsc developers. 2056 2057SEE ALSO 2058 CSCstatStr(3) 2059 CSCcflags(3) 2060 CSCldflags(3) 2061 CSClibs(3) 2062 CSCversion(3) 2063 CSCchkup(3) 2064 2065 2066------------------------------------------------------------------------ 2067CSCfileBaseName(3) 2068 2069NAME 2070 CSCfileBaseName - strip directory from pathname 2071 2072SYNOPSYS 2073 #include "libcsc.h" 2074 2075 char* CSCfileBaseName ( 2076 const char* const path, 2077 CSCmemListType const memList, 2078 int memTag 2079 ); 2080 2081RETURN VALUE 2082 CSCfileBaseName() returns a pointer to a new string that begins with the 2083 first character in path after the last occurence of a '/' character. 2084 2085 CSCfileBaseName() returns a pointer to path if the path string does not 2086 contain a '/' character. 2087 2088 CSCfileBaseName() returns NULL if `path' or `memList' argument is NULL. 2089 2090DESCRIPTION 2091 If CSCfileBaseName() is successful, it returns a pointer to a new string 2092 that is allocated by CSCmemAlloc(); the string must be freed with 2093 CSCmemFree() to avoid a memory leak. 2094 2095SEE ALSO 2096 CSCfilePathName(3) 2097 2098 2099------------------------------------------------------------------------ 2100CSCfileExpandPath(3) 2101 2102NAME 2103 CSCfileExpandPath - expand ~ and environment variables in pathname 2104 2105SYNOPSYS 2106 #include "libcsc.h" 2107 2108 char* cscFileExpandPath ( 2109 const char* const path, 2110 const size_t pathMax, 2111 CSCmemListType const memList, 2112 int memTag 2113 ); 2114 2115RETURN VALUE 2116 CSCfileExpandPath() returns a pointer to a newly allocated string, if 2117 successful; otherwise, it returns NULL on failure. 2118 2119DESCRIPTION 2120 CSCfileExpandPath() expands the `~' character and environment variables 2121 in the string in the path argument. The new expanded string must be a 2122 length less than or equal to pathMax, including the terminating NULL 2123 character. 2124 2125 If successful, cscFileExpandPath() returns a pointer to a new string 2126 that is allocated by rtsMemAlloc(); the string must be freed with 2127 CSCmemFree() to avoid a memory leak. 2128 2129SEE ALSO 2130 2131 2132------------------------------------------------------------------------ 2133CSCfileGetHomeDir(3) 2134 2135NAME 2136 CSCfileGetHomeDir - find home directory pathname 2137 2138SYNOPSYS 2139 #include "libcsc.h" 2140 2141 char* CSCfileGetHomeDir ( 2142 const size_t pathSize, 2143 CSCmemListType const memList, 2144 int memTag 2145 ); 2146 2147RETURN VALUE 2148 CSCfileGetHomeDir() returns a pointer to the home directory associated 2149 with the user ID of the process, if successful; otherwise, NULL is 2150 returned. 2151 2152DESCRIPTION 2153 The returned home directory string should be a length less than or 2154 equal to `pathSize', including the terminating NULL character; if not, 2155 then an unterminated string containing `pathSize' characters is 2156 returned. 2157 2158 If successful, CSCfileGetHomeDir() returns a pointer to a new string 2159 that is allocated by CSCmemAlloc(); the string must be freed with 2160 CSCmemFree() to avoid a memory leak. 2161 2162SEE ALSO 2163 CSCfileGetUserHomeDir(3) 2164 2165 2166------------------------------------------------------------------------ 2167CSCfileGetUserHomeDir(3) 2168 2169NAME 2170 CSCfileGetUserHomeDir - find home directory pathname of specific user 2171 2172SYNOPSYS 2173 #include "libcsc.h" 2174 2175 char* cscFileGetUserHomeDir ( 2176 const char* const userName, 2177 const size_t pathSize, 2178 CSCmemListType const memList, 2179 int memTag 2180 ); 2181 2182RETURN VALUE 2183 CSCfileGetUserHomeDir() returns a pointer to the home directory 2184 associated with the specific user name userName, if successful; 2185 otherwise, NULL is returned. 2186 2187DESCRIPTION 2188 The returned home directory string should be a length less than or 2189 equal to `pathSize', including the terminating NULL character; if not, 2190 then an unterminated string containing `pathSize' characters is 2191 returned. 2192 2193 If successful, CSCfileGetUserHomeDir() returns a pointer to a new 2194 string that is allocated by CSCmemAlloc(); the string must be freed 2195 with CSCmemFree() to avoid a memory leak. 2196 2197SEE ALSO 2198 CSCfileGetHomeDir(3) 2199 2200 2201------------------------------------------------------------------------ 2202CSCfileOpen(3) 2203 2204NAME 2205 CSCfileOpen - create a file in a path that doesn't (yet) exist 2206 2207SYNOPSYS 2208 #include "libcsc.h" 2209 2210 FILE* CSCfileOpen ( 2211 const char* const path, 2212 const int mask, 2213 const size_t pathMax, 2214 CSCmemListType const memList, 2215 int memTag 2216 ); 2217 2218RETURN VALUE 2219 CSCfileOpen() returns a new file, open for writing, if successful. On 2220 failure, CSCfileOpen() returns NULL. 2221 2222DESCRIPTION 2223 CSCfileOpen() opens a new file for writing, creating the path if 2224 necessary. 2225 2226SEE ALSO 2227 2228 2229------------------------------------------------------------------------ 2230CSCfilePathName(3) 2231 2232NAME 2233 CSCfilePathName - strip last component (file) from pathname 2234 2235SYNOPSYS 2236 #include "libcsc.h" 2237 2238 char* CSCfilePathName ( 2239 const char* const path, 2240 CSCmemListType const memList, 2241 int memTag 2242 ); 2243 2244RETURN VALUE 2245 CSCfilePathName() returns a pointer to a new string that begins with 2246 the first character in path and terminates with the last character 2247 preceding the last '/' character. 2248 2249 CSCfilePathName() returns NULL if it is not successful. 2250 2251DESCRIPTION 2252 If CSCfilePathName() is successful, it returns a pointer to a new 2253 string that is allocated by CSCmemAlloc(); the string must be freed 2254 with CSCmemFree() to avoid a memory leak. 2255 2256SEE ALSO 2257 CSCfileBaseName(3) 2258 2259 2260------------------------------------------------------------------------ 2261CSCfileReadLock(3) 2262 2263NAME 2264 CSCfileReadLock - read-lock a region in a file 2265 2266SYNOPSYS 2267 #include "libcsc.h" 2268 2269 int CSCfileReadLock ( 2270 int fd, 2271 off_t offset, 2272 int whence, 2273 off_t length 2274 ); 2275 2276RETURN VALUE 2277 CSCfileReadLock() returns 0 if successful, otherwise -1 and errno will 2278 be set to indicate the error. 2279 2280DESCRIPTION 2281 CSCfileReadLock() read locks a region of file associated with fd. The 2282 locked region in the file is at offset from beginning/end of the file 2283 depending upon the value of whence. The locked region is length bytes. 2284 2285 whence usage is as follows: 2286 2287 SEEK_SET 2288 The offset is set to offset bytes. 2289 2290 SEEK_CUR 2291 The offset is set to its current location plus off-set bytes. 2292 2293 SEEK_END 2294 The offset is set to the size of the file plus off-set bytes. 2295 2296SEE ALSO 2297 CSCfileWriteLock(3) 2298 CSCfileUnlock(3) 2299 2300 2301------------------------------------------------------------------------ 2302CSCfileUnlock(3) 2303 2304NAME 2305 CSCfileUnlock - unlock a region in a file 2306 2307SYNOPSYS 2308 #include "libcsc.h" 2309 2310 int CSCfileUnlock ( 2311 int fd, 2312 off_t offset, 2313 int whence, 2314 off_t length 2315 ); 2316 2317RETURN VALUE 2318 CSCfileUnlock() returns 0 if successful, otherwise -1 and errno will 2319 be set to indicate the error. 2320 2321DESCRIPTION 2322 CSCfileUnlock() unlocks a region of file associated with fd. The 2323 unlocked region in the file is at offset from beginning/end of the 2324 file depending upon the value of whence. The unlocked region is 2325 length bytes. 2326 2327 whence usage is as follows: 2328 2329 SEEK_SET 2330 The offset is set to offset bytes. 2331 2332 SEEK_CUR 2333 The offset is set to its current location plus off-set bytes. 2334 2335 SEEK_END 2336 The offset is set to the size of the file plus off-set bytes. 2337 2338SEE ALSO 2339 CSCfileReadLock(3) 2340 CSCfileWriteLock(3) 2341 2342 2343------------------------------------------------------------------------ 2344CSCfileWriteLock(3) 2345 2346NAME 2347 CSCfileWriteLock - write-lock a region in a file 2348 2349SYNOPSYS 2350 #include "libcsc.h" 2351 2352 int CSCfileWriteLock ( 2353 int fd, 2354 off_t offset, 2355 int whence, 2356 off_t length 2357 ); 2358 2359RETURN VALUE 2360 CSCfileWriteLock() returns 0 if successful, otherwise -1 and errno will 2361 be set to indicate the error. 2362 2363DESCRIPTION 2364 CSCfileWriteLock() read locks a region of file associated with fd. The 2365 locked region in the file is at offset from beginning/end of the file 2366 depending upon the value of whence. The locked region is length bytes. 2367 2368 whence usage is as follows: 2369 2370 SEEK_SET 2371 The offset is set to offset bytes. 2372 2373 SEEK_CUR 2374 The offset is set to its current location plus off-set bytes. 2375 2376 SEEK_END 2377 The offset is set to the size of the file plus off-set bytes. 2378 2379SEE ALSO 2380 CSCfileReadLock(3) 2381 CSCfileUnlock(3) 2382 2383 2384------------------------------------------------------------------------ 2385CSChashDel(3) 2386 2387NAME 2388 CSChashDel - remove a libcsc hash table 2389 2390SYNOPSYS 2391 #include "libcsc.h" 2392 2393 int CSChashDel ( 2394 CSChashTableType const hashTable 2395 ); 2396 2397RETURN VALUE 2398 CSChashDel(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, 2399 CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL 2400 pointers, bad function arguments, and internal data errors, 2401 respectively. 2402 2403DESCRIPTION 2404 The libcsc hash table represented by the opaque `hashTable' is 2405 completely removed. 2406 2407SEE ALSO 2408 CSChashNew(3) 2409 CSChashStat(3) 2410 CSChashEntryPut(3) 2411 CSChashEntryGet(3) 2412 CSChashEntryDel(3) 2413 CSChashEntryNext(3) 2414 CSChashEntryStat(3) 2415 CSChashRead(3) 2416 CSChashWrite(3) 2417 CSChashDump(3) 2418 2419 2420------------------------------------------------------------------------ 2421CSChashDump(3) 2422 2423NAME 2424 CSChashDump - write a formatted dump of a libcsc hash table 2425 2426SYNOPSYS 2427 #include "libcsc.h" 2428 2429 int CSChashDump ( 2430 int fd, 2431 CSChashTableType const hashTable 2432 ); 2433 2434RETURN VALUE 2435 CSChashDump() always returns CSC_OK. Lame. 2436 2437DESCRIPTION 2438 CSChashDump() writes to `fd' a formatted dump of the entire hash table 2439 represented by the opaque `hashTable'. 2440 2441 This formatted dump of the hash table is for visual inspection of the 2442 hash table. After a short header, each item's hash value, key, data 2443 size, and data dump is written. 2444 2445 Don't do this with large hash tables, even if they are sparsely 2446 populated; nobody would read it. 2447 2448SEE ALSO 2449 CSChashNew(3) 2450 CSChashDel(3) 2451 CSChashStat(3) 2452 CSChashEntryPut(3) 2453 CSChashEntryGet(3) 2454 CSChashEntryDel(3) 2455 CSChashEntryNext(3) 2456 CSChashEntryStat(3) 2457 CSChashRead(3) 2458 CSChashWrite(3) 2459 2460 2461------------------------------------------------------------------------ 2462CSChashEntryDel(3) 2463 2464NAME 2465 CSChashEntryDel - remove an entry from a libcsc hash table 2466 2467SYNOPSYS 2468 #include "lib.h" 2469 2470 int CSChashEntryDel ( 2471 CSChashTableType const hashTable, 2472 CSChashKeyUnion* const keyPtr 2473 ); 2474 2475RETURN VALUE 2476 CSChashEntryDel(), if successful, returns CSC_OK; otherwise, 2477 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 2478 to NULL pointers, bad function arguments, and internal data errors, 2479 respectively. 2480 2481DESCRIPTION 2482 The hash table entry with the key value that is pointed to by `keyPtr' 2483 is removed from the hash table represented by the opaque `hashTable'. 2484 2485 Of course, the type of the key pointed to by `keyPtr' must match the 2486 type of keys (CSC_HASH_INT32_KEY or CSC_HASH_ASCIIZ_KEY) used by 2487 `hashTable'. 2488 2489SEE ALSO 2490 CSChashNew(3) 2491 CSChashDel(3) 2492 CSChashStat(3) 2493 CSChashEntryPut(3) 2494 CSChashEntryGet(3) 2495 CSChashEntryNext(3) 2496 CSChashEntryStat(3) 2497 CSChashRead(3) 2498 CSChashWrite(3) 2499 CSChashDump(3) 2500 2501 2502------------------------------------------------------------------------ 2503CSChashEntryGet(3) 2504 2505NAME 2506 CSChashEntryGet - get an item from a libcsc hash table 2507 2508SYNOPSYS 2509 #include "libcsc.h" 2510 2511 int CSChashEntryGet ( 2512 CSChashTableType const hashTable, 2513 CSChashKeyUnion* const keyPtr, 2514 void** const itemPtrPtr, 2515 size_t* const itemSizePtr, 2516 CSCmemListType const memLst 2517 ); 2518 2519RETURN VALUE 2520 CSChashEntryGet(), if successful, returns CSC_OK; otherwise, 2521 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 2522 to NULL pointers, bad function arguments, and internal data errors, 2523 respectively. 2524 2525DESCRIPTION 2526 CSChashEntryGet() looks up the key pointed to by `keyPtr' in the libcsc 2527 hash table represented by the opaque `hashTable'. 2528 2529 If the item corresponding to the key is found in the table, then a copy 2530 of the the data is allocated with CSCmemDup(), or malloc() if `memLst' 2531 is NULL, and the pointer of the newly allocated data it is written to 2532 the void pointer that is pointed to by `itemPtrPtr', and its size in 2533 bytes is written to the size_t pointed to by `itemSizePtr'. 2534 2535 Since CSChashEntryGet(), if successful, allocates storage for the 2536 retrieved item. If `memLst' is not null then CSCmemDup() is used with 2537 the value of `memLst'; the data should be removed with CSCmemFree(), 2538 using "tagData" value of zero, to avoid leaking this memory. If `memLst' 2539 is NULL, then malloc() is use to allocate storage, and free() should be 2540 used to remove the data to avoid leaking this memory. 2541 2542SEE ALSO 2543 CSChashNew(3) 2544 CSChashDel(3) 2545 CSChashStat(3) 2546 CSChashEntryPut(3) 2547 CSChashEntryDel(3) 2548 CSChashEntryNext(3) 2549 CSChashEntryStat(3) 2550 CSChashRead(3) 2551 CSChashWrite(3) 2552 CSChashDump(3) 2553 2554 2555------------------------------------------------------------------------ 2556CSChashEntryNext(3) 2557 2558NAME 2559 CSChashEntryNext - find next entry in a libcsc hash table 2560 2561SYNOPSYS 2562 #include "libcsc.h" 2563 2564 CSChashEntryType CSChashEntryNext ( 2565 CSChashTableType const hashTable, 2566 CSChashEntryType const entry 2567 ); 2568 2569RETURN VALUE 2570 CSChashEntryNext(), if successful, returns an opaque libcsc hash table 2571 entry. If not successful, CSChashEntryNext() returns NULL. 2572 2573DESCRIPTION 2574 CSChashEntryNext() uses the libcsc hash table referred to by the opaque 2575 `hashTable' and returns the next consecutive entry following the entry 2576 indicated by the opaque `entry'. This next consecutive entry is the 2577 entry physically following `entry', its key may hash to the save value 2578 as `entry''s key, or it may be some larger hash value. 2579 2580 If `entry' is NULL, then the first item in the table is returned. 2581 2582 If `hashTable' is a table with no entries, or there are no more entries 2583 following entry, then NULL is returned. 2584 2585BUGS 2586 This function provides one of the few ways to get direct access to a 2587 libcsc hash table's internal data. Avoid using this function. 2588 2589SEE ALSO 2590 CSChashNew(3) 2591 CSChashDel(3) 2592 CSChashStat(3) 2593 CSChashEntryPut(3) 2594 CSChashEntryGet(3) 2595 CSChashEntryDel(3) 2596 CSChashEntryStat(3) 2597 CSChashRead(3) 2598 CSChashWrite(3) 2599 CSChashDump(3) 2600 2601 2602------------------------------------------------------------------------ 2603CSChashEntryPut(3) 2604 2605NAME 2606 CSChashEntryPut - put an entry into a libcsc hash table 2607 2608SYNOPSYS 2609 #include "libcsc.h" 2610 2611 int CSChashEntryPut ( 2612 CSChashTableType const hashTable, 2613 CSChashKeyUnion* const keyPtr, 2614 void* const itemPtr, 2615 size_t itemSize 2616 ); 2617 2618RETURN VALUE 2619 CSChashEntryPut(), if successful, returns CSC_OK. If the key is 2620 already in use in the table, then CSChashEntryPut() will return 2621 CSC_DUPKEY. Other values, CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can 2622 be returned corresponding to NULL pointers, bad function arguments, and 2623 internal data errors, respectively. 2624 2625DESCRIPTION 2626 CSChashEntryPut() puts the data pointed to by `itemPtr', whose key is 2627 pointed to by `keyPtr' and size in bytes is `itemSize', into the libcsc 2628 hash table represented by the opaque `hashTable'. 2629 2630 The data that goes into the table is a duplicate of `itemSize' bytes 2631 from the address `itemPtr'. To avoid duplicating static data, put a 2632 pointer of the client data into the table. If the item being put into 2633 the table contains a pointer, beware of aliasing errors if the pointer 2634 is to allocated memory that becomes deallocated while the item is in the 2635 table. 2636 2637 Of course, the type of the key pointed to by `keyPtr' must match the 2638 type of keys (CSC_HASH_INT32_KEY or CSC_HASH_ASCIIZ_KEY) used by 2639 `hashTable'. 2640 2641SEE ALSO 2642 CSChashNew(3) 2643 CSChashDel(3) 2644 CSChashStat(3) 2645 CSChashEntryGet(3) 2646 CSChashEntryDel(3) 2647 CSChashEntryNext(3) 2648 CSChashEntryStat(3) 2649 CSChashRead(3) 2650 CSChashWrite(3) 2651 CSChashDump(3) 2652 2653 2654------------------------------------------------------------------------ 2655CSChashEntryStat(3) 2656 2657NAME 2658 CSChashEntryStat - query the fields of a libcsc hash table entry 2659 2660SYNOPSYS 2661 #include "libcsc.h" 2662 2663 int CSChashEntryStat ( 2664 CSChashEntryType const entry, 2665 CSChashKeyUnion** const keyPtrPtr, 2666 void** const itemPtrPtr, 2667 size_t* const itemSizePtr 2668 ); 2669 2670RETURN VALUE 2671 If successful, CSChashEntryStat() returns CSC_OK. If entry is NULL, 2672 then CSC_BADARG is returned. If libcsc was compiled with the DEBUG 2673 macro and the libcsc hash entry at entry is munged up, then CSC_CORRUPT 2674 is returned. 2675 2676DESCRIPTION 2677 CSChashEntryStat() queries the libcsc hash table entry represented by 2678 the opaque `entry'. 2679 2680 If `keyPtrPtr' is not NULL, then the a pointer to `entry''s key is 2681 written to the CSChashKeyUnion pointer that is pointed to by 2682 `keyPtrPtr'. 2683 2684 If `itemPtrPtr' is not NULL, then `entry''s item pointer is written to 2685 the void pointer that is pointed to by `itemPtrPtr'. 2686 2687 If `itemSizePtr' is not NULL, then the size, in bytes, of `entry''s 2688 item is written to the size_t pointed to by `itemSizePtr'. 2689 2690BUGS 2691 This function provides one of the few ways to get direct access to a 2692 libcsc hash table's internal data. Avoid using this function. 2693 2694SEE ALSO 2695 CSChashNew(3) 2696 CSChashDel(3) 2697 CSChashStat(3) 2698 CSChashEntryPut(3) 2699 CSChashEntryGet(3) 2700 CSChashEntryDel(3) 2701 CSChashEntryNext(3) 2702 CSChashRead(3) 2703 CSChashWrite(3) 2704 CSChashDump(3) 2705 2706 2707------------------------------------------------------------------------ 2708CSChashNew(3) 2709 2710NAME 2711 CSChashNew - create a new libcsc hash table 2712 2713SYNOPSYS 2714 #include "libcsc.h" 2715 2716 CSChashTableType CSChashNew ( 2717 const char* const name, 2718 CSChashKeyType keySpec, 2719 size_t size, 2720 CSCmonFnType monFunc, 2721 const void* monData, 2722 CSCprofileType profiling 2723 ); 2724 2725RETURN VALUE 2726 CSChashNew(), if successful, returns an opaque data type representing 2727 a new libcsc hash table, or NULL if otherwise not successful. 2728 2729DESCRIPTION 2730 CSChashNew() creates a new libcsc hash table with several attributes: 2731 name, type of key, and number of hash locations. 2732 2733 `name' points to an arbitrary string that is used as the name of the 2734 new libcsc hash table. 2735 2736 `keySpec' specifies the type of keys used by the new hash table; it is 2737 one of: 2738 2739 CSC_HASH_ASCIIZ_KEY ... hash keys for this table will be ASCII 2740 NULL-terminated (ASCIIZ) strings. 2741 2742 CSC_HASH_INT32_KEY .... hash keys for this table will be 2743 integers of the type int32. 2744 2745 `size' specifies the number of hash locations, or buckets, in the new 2746 libcsc hash table. If size is zero, then the new libcsc hash table 2747 will begin life with four hash locations and will quadruple whenever the 2748 number of hash locations is some mysterious factor of the total number 2749 of hashed items (gets overfull). 2750 2751 `profiling' can be CSC_DO_PROFILING or CSC_NO_PROFILING; it specifies 2752 whether alocate/free, insertion/deletion, etc. statistics should 2753 actually be generated and kept in the hash table. 2754 2755SEE ALSO 2756 CSChashDel(3) 2757 CSChashStat(3) 2758 CSChashEntryPut(3) 2759 CSChashEntryGet(3) 2760 CSChashEntryDel(3) 2761 CSChashEntryNext(3) 2762 CSChashEntryStat(3) 2763 CSChashRead(3) 2764 CSChashWrite(3) 2765 CSChashDump(3) 2766 2767 2768------------------------------------------------------------------------ 2769CSChashRead(3) 2770 2771NAME 2772 CSChashRead - read an ASCII format libcsc hash table 2773 2774SYNOPSYS 2775 #include "libcsc.h" 2776 2777 int CSChashRead ( 2778 int fd, 2779 CSChashTableType* const hashTablePtr, 2780 CSCmonFnType monFunc, 2781 const void* monData, 2782 CSCprofileType profiling 2783 ); 2784 2785RETURN VALUE 2786 CSChashRead() always returns CSC_OK. Lame. 2787 2788DESCRIPTION 2789 CSChashRead() reads from `fd' a libcsc hash table in ASCII format that 2790 was written with CSChashWrite(). 2791 2792 `hashTablePtr' should point to a CSChashTableType that is set to NULL; a 2793 new libcsc hash table will be created. 2794 2795BUGS 2796 There is no error checking in this function. 2797 2798SEE ALSO 2799 CSChashNew(3) 2800 CSChashDel(3) 2801 CSChashStat(3) 2802 CSChashEntryPut(3) 2803 CSChashEntryGet(3) 2804 CSChashEntryDel(3) 2805 CSChashEntryNext(3) 2806 CSChashEntryStat(3) 2807 CSChashWrite(3) 2808 CSChashDump(3) 2809 2810 2811------------------------------------------------------------------------ 2812CSChashStat(3) 2813 2814NAME 2815 CSChashStat - query statistics of a libcsc hash table 2816 2817SYNOPSYS 2818 #include "libcsc.h" 2819 2820 int CSChashStat ( 2821 CSChashTableType const hashTable, 2822 CSChashStatType* const statStruct 2823 ); 2824 2825RETURN VALUE 2826 CSChashStat(), if successful, returns a pointer to a structure of 2827 queried data, or NULL if otherwise not successful. 2828 CSChashStat(), returns CSC_OK, or CSC_BADARG and CSC_CORRUPT can be 2829 returned corresponding to NULL pointers, bad function arguments, and 2830 internal data errors, respectively. 2831 2832DESCRIPTION 2833 CSChashStat() queries the libcsc hash table represented by the opaque 2834 `hashTable' and fills a CSChashStatType structure. The CSChashStatType 2835 structure is 2836 2837 typedef struct CSChashStatType 2838 { 2839 char name[80]; // name of hash table 2840 CSCprofileType profiling; // profiling flag 2841 size_t count; // count of items in table 2842 size_t nhash; // number of hash locations 2843 CSCboolean grows; // CSC_TRUE or CSC_FALSE 2844 size_t resizes; // num of resizes, if table grows 2845 size_t deletions; // num of deletions since resize 2846 size_t insertions; // num of insertions since resize 2847 size_t collisions; // num of collisions since resize 2848 } CSChashStatType; 2849 2850 Only up to seventy nine characters of the table name are retrieved. 2851 2852 If the table size was specified a zero when it was created with 2853 CSChashNew() then the table quadruples its hash locations as it gets 2854 full. In this case the grows flag will be CSC_TRUE, otherwise it will 2855 be CSC_FALSE. 2856 2857 If the table grows, then the deletions, insertions, and collisions 2858 fields of the CSChashStatType structure will represent those 2859 statistics only since the last time the table resized itself i.e., the 2860 deletions, insertions, and collisions are reset to zero when the table 2861 resizes itself. 2862 2863EXAMPLE 2864 CSChashTableType myTable; 2865 CSChashQueryType statStruct; 2866 int stat 2867 2868 . 2869 . 2870 . 2871 stat = CSChashStat (myTable, &statStruct); 2872 . 2873 // do something with the statistics 2874 . 2875 . 2876 . 2877 2878SEE ALSO 2879 CSChashNew(3) 2880 CSChashDel(3) 2881 CSChashEntryPut(3) 2882 CSChashEntryGet(3) 2883 CSChashEntryDel(3) 2884 CSChashEntryNext(3) 2885 CSChashEntryStat(3) 2886 CSChashRead(3) 2887 CSChashWrite(3) 2888 CSChashDump(3) 2889 2890 2891------------------------------------------------------------------------ 2892CSChashWrite(3) 2893 2894NAME 2895 CSChashWrite - write a libcsc hash table in an ASCII format 2896 2897SYNOPSYS 2898 #include "libcsc.h" 2899 2900 int CSChashWrite ( 2901 int fd, 2902 CSChashTableType const hashTable 2903 ); 2904 2905RETURN VALUE 2906 CSChashWrite() always returns CSC_OK. Lame. 2907 2908DESCRIPTION 2909 CSChashWrite() writes to `fd' the libcsc hash table represented by the 2910 opaque `hashTable' in an ASCII format. Small, simple tables will be 2911 human-readable by patient humans, but CSChashRead() will be happy to 2912 read it and create another duplicate libcsc hash table. In this way, 2913 libcsc hash tables can be transported between processes, in space or 2914 time. 2915 2916 Caution: client pointers stored in the table will be severe aliasing 2917 bugs when they are read by a different process. 2918 2919BUGS 2920 There is no error checking in this function. 2921 2922SEE ALSO 2923 CSChashNew(3) 2924 CSChashDel(3) 2925 CSChashStat(3) 2926 CSChashEntryPut(3) 2927 CSChashEntryGet(3) 2928 CSChashEntryDel(3) 2929 CSChashEntryNext(3) 2930 CSChashEntryStat(3) 2931 CSChashRead(3) 2932 CSChashDump(3) 2933 2934 2935------------------------------------------------------------------------ 2936CSCioBufRead(3) 2937 2938NAME 2939 CSCioBufRead - read an ASCII buffer 2940 2941SYNOPSYS 2942 #include "libcsc.h" 2943 2944 int CSCioBufRead ( 2945 int fd, 2946 void** const dataPtrPtr, 2947 size_t* const sizePtr, 2948 CSCmemListType const memList, 2949 int tagData 2950 ); 2951 2952RETURN VALUE 2953 CSC_OK ....... successful 2954 2955 CSC_BADARG ... fd is zero, or dataPtrPtr or sizePtr is NULL 2956 2957 CSC_ERROR .... read error; no bytes to read, or maybe an odd count of 2958 bytes where there was an expected even count 2959 2960 CSC_NOMEM .... can't allocate memory for the read buffer 2961 2962DESCRIPTION 2963 CSCioBufRead() reads from `fd' an ASCII representation of arbitrary 2964 bytes that are formatted as created by CSCioBufWrite(). The ASCII data 2965 is converted to binary data and stored in a single dynamically allocated 2966 memory block. 2967 2968 The void pointer that is pointed to by `dataPtrPtr' is updated with the 2969 pointer to newly allocated memory containing the bytes read from fd. 2970 2971 NOTE Since the buffer is dynamically allocated with CSCmemAlloc(), 2972 the caller must free *bufPtrPtr with CSCmemFree() or 2973 CSCmemListFree() to avoid a memory leak. 2974 2975 The size_t pointed to by `sizePtr' is updated to contain the number of 2976 bytes in the newly allocated buffer. 2977 2978 Use CSCioBufWrite() and CSCioBufRead() to store and retrieve arbitrary 2979 binary data in portable ASCII format. 2980 2981 `memList' and `tag' are as use with CSCmemAlloc(). 2982 2983EXAMPLE 2984 void* data; 2985 size_t size; 2986 2987 // Read from fd (no NULL character received): "4\n12FACE55\n" 2988 2989 stat = rtsIObufRead (fd, &data, &size); 2990 2991 // Now: *data = 0x12, 0xFA, 0xCE, 0x55 2992 // size = 4; 2993 2994SEE ALSO 2995 CSCioInfoPrint(3) 2996 CSCioWarnPrint(3) 2997 CSCioErrorPrint(3) 2998 CSCioSoftwareError(3) 2999 CSCioRead(3) 3000 CSCioReadLine(3) 3001 CSCioBufWrite(3) 3002 3003 3004------------------------------------------------------------------------ 3005CSCioBufWrite(3) 3006 3007NAME 3008 CSCioBufWrite - write an ASCII buffer 3009 3010SYNOPSYS 3011 #include "libcsc.h" 3012 3013 int CSCioBufWrite ( 3014 int fd, 3015 const void* dataPtr, 3016 size_t size 3017 ); 3018 3019RETURN VALUE 3020 CSC_OK ....... successful 3021 3022 CSC_BADARG ... fd is zero, dataPtr is NULL, or size is zero 3023 3024 CSC_ERROR .... write error 3025 3026DESCRIPTION 3027 CSCioBufWrite() converts the size_t value of `size' to an ASCII string 3028 and writes this to `fd', followed by a newline. Then, `size' bytes, 3029 starting at `dataPtr', are each converted to two ASCII characters (a 3030 standard "bin to hex" conversion) and written to `fd', followed by a 3031 newline. 3032 3033 Use CSCioBufWrite() and CSCioBufRead() to store and retrieve arbitrary 3034 binary data in portable ASCII format. 3035 3036EXAMPLE 3037 int data = 0x12FACE55; 3038 3039 stat = rtsIObufWrite (fd, &data, sizeof(int)); 3040 3041 // Written to fd (no NULL character sent): "4\n12FACE55\n" 3042 3043SEE ALSO 3044 CSCioInfoPrint(3) 3045 CSCioWarnPrint(3) 3046 CSCioErrorPrint(3) 3047 CSCioSoftwareError(3) 3048 CSCioRead(3) 3049 CSCioReadLine(3) 3050 CSCioBufRead(3) 3051 3052 3053------------------------------------------------------------------------ 3054CSCioErrorPrint(3) 3055 3056NAME 3057 CSCioErrorPrint - formatted write to stderr 3058 3059SYNOPSYS 3060 #include "libcsc.h" 3061 3062 void CSCioErrorPrint ( 3063 const char* cscPtr, 3064 const char* csuPtr, 3065 const char* fmtPtr, 3066 ); 3067 3068RETURN VALUE 3069 CSCioErrorPrint() returns no value. 3070 3071DESCRIPTION 3072 CSCioErrorPrint() is a front end, or wrapper, around fprintf() to 3073 standard error. Before printing the typical formatted string, 3074 CSCioErrorPrint() prints a string with `csc' and `csu': 3075 "<csc>-ERROR-<csu>: ". 3076 3077EXAMPLE 3078 stat = 55; 3079 (void)CSCioErrorPrint ("CSCio", "CSCioBufRead", "bad stat %d\n", stat); 3080 3081 // This will print to standard error: 3082 // "CSCio-ERROR-CSCioBufRead: bad stat 55\n" 3083 3084SEE ALSO 3085 CSCioInfoPrint(3) 3086 CSCioWarnPrint(3) 3087 CSCioSoftwareError(3) 3088 CSCioRead(3) 3089 CSCioReadLine(3) 3090 CSCioBufWrite(3) 3091 CSCioBufRead(3) 3092 3093 3094------------------------------------------------------------------------ 3095CSCioInfoPrint(3) 3096 3097NAME 3098 CSCioInfoPrint - formatted write to stdout 3099 3100SYNOPSYS 3101 #include "libcsc.h" 3102 3103 void CSCioInfoPrint ( 3104 const char* cscPtr, 3105 const char* csuPtr, 3106 const char* fmtPtr, 3107 ); 3108 3109RETURN VALUE 3110 CSCioInfoPrint() returns no value. 3111 3112DESCRIPTION 3113 CSCioInfoPrint() is a front end, or wrapper, around fprintf() to 3114 standard output. Before printing the typical formatted string, 3115 CSCioInfoPrint() prints a string with `csc' and `csu': 3116 "<csc>-INFO-<csu>: ". 3117 3118EXAMPLE 3119 stat = 55; 3120 (void)CSCioInfoPrint ("CSCio", "CSCioBufRead", "stat is %d\n", stat); 3121 3122 // This will print to standard output: 3123 // "CSCio-INFO-CSCioBufRead: stat is 55\n" 3124 3125SEE ALSO 3126 CSCioWarnPrint(3) 3127 CSCioErrorPrint(3) 3128 CSCioSoftwareError(3) 3129 CSCioRead(3) 3130 CSCioReadLine(3) 3131 CSCioBufWrite(3) 3132 CSCioBufRead(3) 3133 3134 3135------------------------------------------------------------------------ 3136CSCioRead(3) 3137 3138NAME 3139 CSCioRead - read a specific number of bytes 3140 3141SYNOPSYS 3142 #include "libcsc.h" 3143 3144 int CSCioRead ( 3145 int fd, 3146 char* const bufPtr, 3147 size_t size 3148 ); 3149 3150RETURN VALUE 3151 CSCioRead() returns the number of bytes read. On read error, zero is 3152 returned. if `fd' is zero, `bufPtr' is NULL, or `size' is zero, then 3153 -1 is returned. 3154 3155DESCRIPTION 3156 CSCioRead() reads `size' bytes from `fd' into `bufPtr' by calling the 3157 read() system call in a loop until `size' bytes is read, or until a 3158 read error. 3159 3160SEE ALSO 3161 CSCioInfoPrint(3) 3162 CSCioWarnPrint(3) 3163 CSCioErrorPrint(3) 3164 CSCioSoftwareError(3) 3165 CSCioReadLine(3) 3166 CSCioBufWrite(3) 3167 CSCioBufRead(3) 3168 3169 3170------------------------------------------------------------------------ 3171CSCioReadLine(3) 3172 3173NAME 3174 CSCioReadLine - read bytes that are terminated by a newline 3175 3176SYNOPSYS 3177 #include "libcsc.h" 3178 3179 int CSCioReadLine ( 3180 int fd, 3181 char** const bufPtrPtr, 3182 CSCmemListType const memList, 3183 int tagData 3184 ); 3185 3186RETURN VALUE 3187 CSCioReadLine(), when successful, returns the number of bytes read 3188 from `fd'. 3189 3190 CSCioReadLine() indicates error by returning -1. Errors are: `fd' is 3191 zero or `bufPtrPtr' is NULL, read error, or memory allocation error. 3192 3193DESCRIPTION 3194 CSCioReadLine() reads bytes from `fd' until a newline character is 3195 encountered. The bytes are stored in a single dynamically allocated 3196 buffer; the pointer to the buffer is returned to the caller by writing 3197 the pointer to *bufPtrPtr. 3198 3199 NOTE Since the buffer is dynamically allocated with CSCmemAlloc(), 3200 the caller must free *bufPtrPtr with CSCmemFree() or 3201 CSCmemListFree() to avoid a memory leak. 3202 3203 The terminating newline (maybe just LF or maybe CRLF) is in the returned 3204 data. 3205 3206 `memList' and `tag' are as use with CSCmemAlloc(). 3207 3208SEE ALSO 3209 CSCioInfoPrint(3) 3210 CSCioWarnPrint(3) 3211 CSCioErrorPrint(3) 3212 CSCioSoftwareError(3) 3213 CSCioRead(3) 3214 CSCioBufWrite(3) 3215 CSCioBufRead(3) 3216 3217 3218------------------------------------------------------------------------ 3219CSCioSoftwareError(3) 3220 3221NAME 3222 CSCioSoftwareError - print a parameterized software error message 3223 3224SYNOPSYS 3225 #include "libcsc.h" 3226 3227 void CSCioSoftwareError ( 3228 const char* identPtr, 3229 const char* csciPtr, 3230 const char* fmtPtr, 3231 ... 3232 ); 3233 3234RETURN VALUE 3235 CSCioSoftwareError() returns no value. 3236 3237DESCRIPTION 3238 CSCioSoftwareError() is a utility function that prints a software error 3239 message with `csciPtr' being the name of the program, `identPtr' being a 3240 version description. `fmtPtr' is a printf() style format string, the 3241 last arguments, if any, are format items. 3242 3243 The message will look something like this: 3244 3245<csci>-ERROR-softwareError: INTERNAL SOFTWARE ERROR. 3246<fmt+items> 3247 -- Please report this to the maintainer(s) of <csci>. 3248 -- Please include the command-line invocation of, the conditions under 3249 -- which this error happened, and the following version description: 3250 <ident> 3251 3252SEE ALSO 3253 CSCioInfoPrint(3) 3254 CSCioWarnPrint(3) 3255 CSCioErrorPrint(3) 3256 CSCioRead(3) 3257 CSCioReadLine(3) 3258 CSCioBufWrite(3) 3259 CSCioBufRead(3) 3260 3261 3262------------------------------------------------------------------------ 3263CSCioWarnPrint(3) 3264 3265NAME 3266 CSCioWarnPrint - formatted write to stdout 3267 3268SYNOPSYS 3269 #include "libcsc.h" 3270 3271 void CSCioWarnPrint ( 3272 const char* cscPtr, 3273 const char* csuPtr, 3274 const char* fmtPtr, 3275 ); 3276 3277RETURN VALUE 3278 CSCioWarnPrint() returns no value. 3279 3280DESCRIPTION 3281 CSCioWarnPrint() is a front end, or wrapper, around fprintf() to 3282 standard output. Before printing the typical formatted string, 3283 CSCioWarnPrint() prints a string with `csc' and `csu': 3284 "<csc>-WARN-<csu>: ". 3285 3286EXAMPLE 3287 stat = 55; 3288 (void)CSCioWarnPrint ("CSCio", "CSCioBufRead", "stat is %d\n", stat); 3289 3290 // This will print to standard output: 3291 // "CSCio-WARN-CSCioBufRead: stat is 55\n" 3292 3293SEE ALSO 3294 CSCioInfoPrint(3) 3295 CSCioErrorPrint(3) 3296 CSCioSoftwareError(3) 3297 CSCioRead(3) 3298 CSCioReadLine(3) 3299 CSCioBufWrite(3) 3300 CSCioBufRead(3) 3301 3302 3303------------------------------------------------------------------------ 3304CSCldflags(3) 3305 3306NAME 3307 CSCldflags - get string containing compiler command-line options 3308 3309SYNOPSYS 3310 #include "libcsc.h" 3311 3312 const char* CSCldflags (void); 3313 3314DESCRIPTION 3315 CSCldflags() returns a pointer to a constant ASCII-Z string containing 3316 the linker (ld) command-line options. 3317 3318SEE ALSO 3319 CSCstatStr(3) 3320 CSCcflags(3) 3321 CSClibs(3) 3322 CSCversion(3) 3323 CSCcredits(3) 3324 CSCchkup(3) 3325 3326 3327------------------------------------------------------------------------ 3328CSClibs(3) 3329 3330NAME 3331 CSClibs - get string containing compiler command-line options 3332 3333SYNOPSYS 3334 #include "libcsc.h" 3335 3336 const char* CSClibs (void); 3337 3338DESCRIPTION 3339 CSClibs() returns a pointer to a constant ASCII-Z string containing 3340 the the compiler command-line options that specify the libraries 3341 that libcsc is linked against. 3342 3343SEE ALSO 3344 CSCstatStr(3) 3345 CSCcflags(3) 3346 CSCldflags(3) 3347 CSCversion(3) 3348 CSCcredits(3) 3349 CSCchkup(3) 3350 3351 3352------------------------------------------------------------------------ 3353CSClistDel(3) 3354 3355NAME 3356 CSClistDel - remove a libcsc list 3357 3358SYNOPSYS 3359 #include "libcsc.h" 3360 3361 int CSClistDel ( 3362 CSClistType const list 3363 ); 3364 3365RETURN VALUE 3366 CSClistDel(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, 3367 CSC_BADARG, and CSC_ERROR can be returned corresponding to NULL 3368 pointers, bad function arguments, and internal data errors, 3369 respectively. 3370 3371DESCRIPTION 3372 CSClistDel() completely removes the libcsc list represented by the 3373 opaque `list'. 3374 3375SEE ALSO 3376 CSClistNew(3) 3377 CSClistRead(3) 3378 CSClistWrite(3) 3379 CSClistSetCFunc(3) 3380 CSClistStat(3) 3381 CSClistPush(3) 3382 CSClistPop(3) 3383 CSClistPeek(3) 3384 CSClistNodeNext(3) 3385 CSClistNodeFindByValue(3) 3386 CSClistNodeFindByReference(3) 3387 CSClistNodeStat(3) 3388 CSClistNodeValidate(3) 3389 CSClistNodeDel(3) 3390 3391 3392------------------------------------------------------------------------ 3393CSClistNew(3) 3394 3395NAME 3396 CSClistNew - create a new libcsc list 3397 3398SYNOPSYS 3399 #include "libcsc.h" 3400 3401 CSClistType CSClistNew ( 3402 const char* name, 3403 CSCmonFnType monFunc, 3404 const void* monData, 3405 CSCprofileType profiling 3406 ); 3407 3408RETURN VALUE 3409 CSClistNew(), if successful, returns an opaque CSClistType, or NULL 3410 if otherwise not successful. 3411 3412DESCRIPTION 3413 CSClistNew() creates a new list. 3414 3415 `profiling' can be CSC_DO_PROFILING or CSC_NO_PROFILING; it specifies 3416 whether alocate/free statistics should actually be generated and kept 3417 in the list. 3418 3419SEE ALSO 3420 CSClistDel(3) 3421 CSClistRead(3) 3422 CSClistWrite(3) 3423 CSClistSetCFunc(3) 3424 CSClistStat(3) 3425 CSClistPush(3) 3426 CSClistPop(3) 3427 CSClistPeek(3) 3428 CSClistNodeNext(3) 3429 CSClistNodeFindByValue(3) 3430 CSClistNodeFindByReference(3) 3431 CSClistNodeStat(3) 3432 CSClistNodeValidate(3) 3433 CSClistNodeDel(3) 3434 3435 3436------------------------------------------------------------------------ 3437CSClistNodeDel(3) 3438 3439NAME 3440 CSClistNodeDel - remove an entry (node) from a libcsc list 3441 3442SYNOPSYS 3443 #include "libcsc.h" 3444 3445 int CSClistNodeDel ( 3446 CSClistType const list, 3447 CSClistNodeType node 3448 ); 3449 3450RETURN VALUE 3451 CSClistNodeDel(), if successful, returns CSC_OK; otherwise, 3452 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 3453 to NULL pointers, bad function arguments, and internal data errors, 3454 respectively. 3455 3456DESCRIPTION 3457 The list entry (node)specified by the opaque `node' is removed from 3458 `list'. 3459 3460SEE ALSO 3461 CSClistNew(3) 3462 CSClistDel(3) 3463 CSClistRead(3) 3464 CSClistWrite(3) 3465 CSClistSetCFunc(3) 3466 CSClistStat(3) 3467 CSClistPush(3) 3468 CSClistPop(3) 3469 CSClistPeek(3) 3470 CSClistNodeNext(3) 3471 CSClistNodeFindByValue(3) 3472 CSClistNodeFindByReference(3) 3473 CSClistNodeStat(3) 3474 CSClistNodeValidate(3) 3475 3476 3477------------------------------------------------------------------------ 3478CSClistNodeFindByReference(3) 3479 3480NAME 3481 CSClistNodeFindByReference - find libcsc list entry (node) by reference 3482 3483SYNOPSYS 3484 #include "libcsc.h" 3485 3486 CSClistNodeType CSClistNodeFindByReference ( 3487 CSClistType const list, 3488 CSClistBiasType bias, 3489 const void* const itemPtr 3490 ); 3491 3492RETURN VALUE 3493 CSClistNodeFindByReference(), returns a CSClistNodeType if it is 3494 successful, or NULL if otherwise not successful. 3495 3496DESCRIPTION 3497 CSClistNodeFindByReference() searches `list' for an entry (node). The 3498 search is either from the head of `list' or the tail; this is specified 3499 by `bias', which is one of 3500 3501 CSC_LIST_HEAD Search from the most recently added entries. 3502 3503 CSC_LIST_TAIL Search from the oldest entry. 3504 3505 Beginning at the specified end (head or tail), each entry's (node's) 3506 data pointer is compared to `itemPtr'. CSClistNodeFindByReference() 3507 returns the first entry (node) whose data pointer is equal to `itemPtr'. 3508 3509SEE ALSO 3510 CSClistNew(3) 3511 CSClistDel(3) 3512 CSClistRead(3) 3513 CSClistWrite(3) 3514 CSClistSetCFunc(3) 3515 CSClistStat(3) 3516 CSClistPush(3) 3517 CSClistPop(3) 3518 CSClistPeek(3) 3519 CSClistNodeNext(3) 3520 CSClistNodeFindByValue(3) 3521 CSClistNodeStat(3) 3522 CSClistNodeValidate(3) 3523 CSClistNodeDel(3) 3524 3525 3526------------------------------------------------------------------------ 3527CSClistNodeFindByValue(3) 3528 3529NAME 3530 CSClistNodeFindByValue - find libcsc list entry by data value 3531 3532SYNOPSYS 3533 #include "libcsc.h" 3534 3535 CSClistNodeType CSClistNodeFindByValue ( 3536 CSClistType const list, 3537 CSClistBiasType bias, 3538 const void* const itemPtr 3539 ); 3540 3541RETURN VALUE 3542 CSClistNodeFindByValue(), returns a CSClistNodeType if it is 3543 successful, or NULL if otherwise not successful. 3544 3545DESCRIPTION 3546 CSClistNodeFindByValue() searches `list' for an entry (node). The 3547 search is either from the head of `list' or the tail; this is specified 3548 by `bias', which is one of 3549 3550 CSC_LIST_HEAD Search from the most recently added entries. 3551 3552 CSC_LIST_TAIL Search from the oldest entry. 3553 3554 Beginning at the specified end (head or tail), each entry's (node's) 3555 data is compared against the data at `itemPtr'. This compare is 3556 implemented by `list's client-specified compare function. If `list' 3557 does not have a client specified compare function, then 3558 CSClistNodeFindByValue() will fail and return NULL. 3559 3560 `list's client-specified compare function is used in this manner: 3561 3562 if ((*list->cfunc) ((void*)itemPtr, (void*)entry->dataPtr) == 0) 3563 return (entry); 3564 3565 If `list's client-specified compare function returns zero, then the 3566 search is terminated, and the first entry found containing the desired 3567 data is returned. 3568 3569SEE ALSO 3570 CSClistNew(3) 3571 CSClistDel(3) 3572 CSClistRead(3) 3573 CSClistWrite(3) 3574 CSClistSetCFunc(3) 3575 CSClistStat(3) 3576 CSClistPush(3) 3577 CSClistPop(3) 3578 CSClistPeek(3) 3579 CSClistNodeNext(3) 3580 CSClistNodeFindByReference(3) 3581 CSClistNodeStat(3) 3582 CSClistNodeValidate(3) 3583 CSClistNodeDel(3) 3584 3585 3586------------------------------------------------------------------------ 3587CSClistNodeNext(3) 3588 3589NAME 3590 CSClistNodeNext - find next entry (node) in a libcsc list 3591 3592SYNOPSYS 3593 #include "libcsc.h" 3594 3595 CSClistNodeType CSClistNodeNext ( 3596 CSClistType const list, 3597 CSClistBiasType bias, 3598 CSClistNodeType node 3599 ); 3600 3601RETURN VALUE 3602 CSClistNodeNext(), if successful, returns an opaque libcsc list node. 3603 If not successful, CSClistNodeNext() returns NULL. 3604 3605DESCRIPTION 3606 CSClistNodeNext() uses the libcsc list referred to by the opaque `list' 3607 and returns the next/previous consecutive entry following/preceding the 3608 entry indicated by the opaque `node'. 3609 3610 `bias' specifies whether the next or previous node is retreievd. Legal 3611 values for `bias' are CSC_LIST_HEAD and CSC_LIST_TAIL. 3612 3613 If `node' is NULL, then the first item (head or tail depending upon the 3614 value of `bias') in list is returned. 3615 3616 If `list' has no entries, or there are no more entries (nodes) following 3617 `node', then NULL is returned. 3618 3619SEE ALSO 3620 CSClistNew(3) 3621 CSClistDel(3) 3622 CSClistRead(3) 3623 CSClistWrite(3) 3624 CSClistSetCFunc(3) 3625 CSClistStat(3) 3626 CSClistPush(3) 3627 CSClistPop(3) 3628 CSClistPeek(3) 3629 CSClistNodeFindByValue(3) 3630 CSClistNodeFindByReference(3) 3631 CSClistNodeStat(3) 3632 CSClistNodeValidate(3) 3633 CSClistNodeDel(3) 3634 3635 3636------------------------------------------------------------------------ 3637CSClistNodeStat(3) 3638 3639NAME 3640 CSClistNodeStat - retrieve data fields from a libcsc list entry (node) 3641 3642SYNOPSYS 3643 #include "libcsc.h" 3644 3645 int CSClistNodeStat ( 3646 CSClistNodeType const node, 3647 void** const itemPtrPtr, 3648 size_t* const itemSizePtr 3649 ); 3650 3651RETURN VALUE 3652 CSClistNodeStat(), if successful, returns CSC_OK; otherwise, 3653 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 3654 to NULL pointers, bad function arguments, and internal data errors, 3655 respectively. 3656 3657DESCRIPTION 3658 CSClistNodeStat() retrieves the relevant values of a list entry (node). 3659 3660 If `itemPtrPtr' is not NULL, then entry's (node's) data pointer is 3661 written to the void pointer that is pointed to by `itemPtrPtr'. 3662 3663 If `itemSizePtr' is not NULL, then entry's (node's) data size is 3664 written to the size_t that is pointed to by `itemSizePtr'. 3665 3666 If both itemPtrPtr and itemSizePtr are NULL, then CSClistNodeStat() 3667 doesn't do anything very interesting. 3668 3669SEE ALSO 3670 CSClistNew(3) 3671 CSClistDel(3) 3672 CSClistRead(3) 3673 CSClistWrite(3) 3674 CSClistSetCFunc(3) 3675 CSClistStat(3) 3676 CSClistPush(3) 3677 CSClistPop(3) 3678 CSClistPeek(3) 3679 CSClistNodeNext(3) 3680 CSClistNodeFindByValue(3) 3681 CSClistNodeFindByReference(3) 3682 CSClistNodeValidate(3) 3683 CSClistNodeDel(3) 3684 3685 3686------------------------------------------------------------------------ 3687CSClistNodeValidate(3) 3688 3689NAME 3690 CSClistNodeValidate - verify an entry (node) is really in a libcsc list 3691 3692SYNOPSYS 3693 #include "libcsc.h" 3694 3695 int CSClistNodeValidate ( 3696 CSClistType const list, 3697 CSClistNodeType const node 3698 ); 3699 3700RETURN VALUE 3701 CSClistNodeValidate(), if successful, returns CSC_OK; otherwise, 3702 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 3703 to NULL pointers, bad function arguments, and internal data errors, 3704 respectively. 3705 3706DESCRIPTION 3707 CSClistNodeValidate() looks up `node' in `list' to validate that `node' 3708 is actually in `list'. 3709 3710SEE ALSO 3711 CSClistNew(3) 3712 CSClistDel(3) 3713 CSClistRead(3) 3714 CSClistWrite(3) 3715 CSClistSetCFunc(3) 3716 CSClistStat(3) 3717 CSClistPush(3) 3718 CSClistPop(3) 3719 CSClistPeek(3) 3720 CSClistNodeNext(3) 3721 CSClistNodeFindByValue(3) 3722 CSClistNodeFindByReference(3) 3723 CSClistNodeStat(3) 3724 CSClistNodeDel(3) 3725 3726 3727------------------------------------------------------------------------ 3728CSClistPeek(3) 3729 3730NAME 3731 CSClistPeek - retrieve data from entry at libcsc list head or tail 3732 3733SYNOPSYS 3734 #include "libcsc.h" 3735 3736 int CSClistPeek ( 3737 CSClistType const list, 3738 CSClistBiasType bias, 3739 void** const itemPtrPtr, 3740 size_t* const itemSizePtr 3741 ); 3742 3743RETURN VALUE 3744 CSClistPeek(), if successful, returns CSC_OK; otherwise, 3745 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 3746 to NULL pointers, bad function arguments, and internal data errors, 3747 respectively. 3748 3749DESCRIPTION 3750 CSClistPeek() peeks at the head (newest) or tail (oldest) entry in 3751 `list' and retrieves the data pointer and size. When bias is: 3752 3753 CSC_LIST_HEAD If `itemPtrPtr' is not NULL, then the data pointer from 3754 the list head (newest) entry is written to the void 3755 pointer that is pointed to by `itemPtrPtr'. 3756 3757 If `itemSizePtr' is not NULL, then the data size from 3758 the list head (newest) entry is written to the size_t 3759 that is pointed to by `itemSizePtr'. 3760 3761 CSC_LIST_TAIL If `itemPtrPtr' is not NULL, then the data pointer from 3762 the list tail (oldest) entry is written to the void 3763 pointer that is pointed to by `itemPtrPtr'. 3764 3765 If `itemSizePtr' is not NULL, then the data size from 3766 the list tail (oldest) entry is written to the size_t 3767 that is pointed to by `itemSizePtr'. 3768 3769 If both `itemPtrPtr' and `itemSizePtr' are NULL then CSClistPeek() 3770 doesn't do anything very interesting. 3771 3772SEE ALSO 3773 CSClistNew(3) 3774 CSClistDel(3) 3775 CSClistRead(3) 3776 CSClistWrite(3) 3777 CSClistSetCFunc(3) 3778 CSClistStat(3) 3779 CSClistPush(3) 3780 CSClistPop(3) 3781 CSClistNodeNext(3) 3782 CSClistNodeFindByValue(3) 3783 CSClistNodeFindByReference(3) 3784 CSClistNodeStat(3) 3785 CSClistNodeValidate(3) 3786 CSClistNodeDel(3) 3787 3788 3789------------------------------------------------------------------------ 3790CSClistPop(3) 3791 3792NAME 3793 CSClistPop - pop an entry from a libcsc list and retrieve its data 3794 3795SYNOPSYS 3796 #include "libcsc.h" 3797 3798 int CSClistPop ( 3799 CSClistType const list, 3800 CSClistBiasType bias, 3801 void** const itemPtrPtr, 3802 size_t* const itemSizePtr 3803 ); 3804 3805RETURN VALUE 3806 CSClistPop(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, 3807 CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL 3808 pointers, bad function arguments, and internal data errors, 3809 respectively. 3810 3811DESCRIPTION 3812 CSClistPop() pop the head (newest) or tail (oldest) entry from `list' 3813 depending upon the value of `bias'. Valid values of `bias': 3814 3815 CSC_LIST_HEAD pop the head (newest) entry. 3816 3817 CSC_LIST_TAIL pop the tail (oldest) entry. 3818 3819 The entry is removed from `list', and its data is retrieved. 3820 3821 If `itemPtrPtr' is not NULL, then the popped entry's data pointer is 3822 written to the void pointer that is pointed to by `itemPtrPtr'. 3823 3824 NOTE If the retreived data was pushed into the list with the push 3825 type of CSC_DATA_DUP, then the retreived data is dynamically 3826 allocated (with malloc(), calloc(), etc.) and the caller is 3827 responsible for freeing (with free()) the retreived data. 3828 3829 If `itemSizePtr' is not NULL, then the popped entry's data size is 3830 written to the size_t that is pointed to by `itemSizePtr'. 3831 3832SEE ALSO 3833 CSClistNew(3) 3834 CSClistDel(3) 3835 CSClistRead(3) 3836 CSClistWrite(3) 3837 CSClistSetCFunc(3) 3838 CSClistStat(3) 3839 CSClistPush(3) 3840 CSClistPeek(3) 3841 CSClistNodeNext(3) 3842 CSClistNodeFindByValue(3) 3843 CSClistNodeFindByReference(3) 3844 CSClistNodeStat(3) 3845 CSClistNodeValidate(3) 3846 CSClistNodeDel(3) 3847 3848 3849------------------------------------------------------------------------ 3850CSClistPush(3) 3851 3852NAME 3853 CSClistPush - create a new entry and push it onto a libcsc list 3854 3855SYNOPSYS 3856 #include "libcsc.h" 3857 3858 int CSClistPush ( 3859 CSClistType const list, 3860 CSCdataCntrlType push, 3861 const void* const itemPtr, 3862 size_t itemSize 3863 ); 3864 3865RETURN VALUE 3866 CSClistPush(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, 3867 CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL 3868 pointers, bad function arguments, and internal data errors, 3869 respectively. 3870 3871DESCRIPTION 3872 CSClistPush() creates a libcsc list entry from `itemPtr' and `itemSize', 3873 and pushes it onto the list pointed to by `list'. 3874 3875 `push' specifies how the client data pointed to by `itemPtr' is used: 3876 3877 CSC_DATA_NODUP The new list entry simply copies the data 3878 pointer, `itemPtr', itself. If the data pointed 3879 to by `itemPtr' is dynamically allocated and is 3880 dellocated while the list entry has a pointer 3881 to it, then there will be an aliasing error and 3882 goblins will eat you. 3883 3884 CSC_DATA_DUP The data pointed to by `itemPtr' is copied for 3885 `itemSize' bytes into a new dynamically 3886 allocated storage. The client code is 3887 responsible for deallocating the storage when 3888 the entry is popped from the list or there will 3889 be a memory leak, and you will have to tell your 3890 mother what you've done. 3891 3892 Be careful of mixing push types CSC_DATA_NODUP and CSC_DATA_DUP in the 3893 same list; there may be no way for clients to later tell these entries 3894 apart from each other. 3895 3896 CSClistDel() and CSClistNodeDel() should correctly deallocate data for 3897 entries with CSC_DATA_DUP push types. 3898 3899SEE ALSO 3900 CSClistNew(3) 3901 CSClistDel(3) 3902 CSClistRead(3) 3903 CSClistWrite(3) 3904 CSClistSetCFunc(3) 3905 CSClistStat(3) 3906 CSClistPop(3) 3907 CSClistPeek(3) 3908 CSClistNodeNext(3) 3909 CSClistNodeFindByValue(3) 3910 CSClistNodeFindByReference(3) 3911 CSClistNodeStat(3) 3912 CSClistNodeValidate(3) 3913 CSClistNodeDel(3) 3914 3915 3916------------------------------------------------------------------------ 3917CSClistRead(3) 3918 3919NAME 3920 CSClistRead - read an ASCII format libcsc list 3921 3922SYNOPSYS 3923 #include "libcsc.h" 3924 3925 int CSClistRead ( 3926 int fd, 3927 CSClistType const list 3928 ); 3929 3930RETURN VALUE 3931 CSClistRead(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, 3932 CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL 3933 pointers, bad function arguments, and internal data errors, 3934 respectively. 3935 3936DESCRIPTION 3937 CSClistRead() reads from fd a libcsc list in ASCII format that was 3938 written with CSClistWrite(). 3939 3940 `list' should be a CSClistType that is set to NULL; a new libcsc 3941 list will be created. 3942 3943SEE ALSO 3944 CSClistNew(3) 3945 CSClistDel(3) 3946 CSClistWrite(3) 3947 CSClistSetCFunc(3) 3948 CSClistStat(3) 3949 CSClistPush(3) 3950 CSClistPop(3) 3951 CSClistPeek(3) 3952 CSClistNodeNext(3) 3953 CSClistNodeFindByValue(3) 3954 CSClistNodeFindByReference(3) 3955 CSClistNodeStat(3) 3956 CSClistNodeValidate(3) 3957 CSClistNodeDel(3) 3958 3959 3960------------------------------------------------------------------------ 3961CSClistSetCFunc(3) 3962 3963NAME 3964 CSClistSetCFunc - set a libcsc list entry data compare function 3965 3966SYNOPSYS 3967 #include "libcsc.h" 3968 3969 int CSClistSetCFunc ( 3970 CSClistType const list, 3971 CSCcmpFnType funcptr 3972 ); 3973 3974RETURN VALUE 3975 CSClistSetCFunc(), if successful, returns CSC_OK; otherwise, 3976 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 3977 to NULL pointers, bad function arguments, and internal data errors, 3978 respectively. 3979 3980DESCRIPTION 3981 CSClistSetCFunc() sets the client-specified compare function `list'. 3982 3983 The client-specified compare function is used by the libcsc list find 3984 functions CSClistNodeFindByValue() and CSClistNodeFindByReference(). 3985 3986 `funcptr' is a function pointer pointer for a libcsc CSCcmpFnType 3987 function that is called from the libcsc list find functions 3988 CSClistNodeFindByValue() and CSClistNodeFindByReference(). The 3989 prototype for `funcptr' is: 3990 3991 int (*CSCcmpFnType) (void*, void*); 3992 3993 The client callback function `funcptr, is called with client supplied 3994 data and a list entry data pointer. 3995 3996SEE ALSO 3997 CSClistNew(3) 3998 CSClistDel(3) 3999 CSClistRead(3) 4000 CSClistWrite(3) 4001 CSClistStat(3) 4002 CSClistPush(3) 4003 CSClistPop(3) 4004 CSClistPeek(3) 4005 CSClistNodeNext(3) 4006 CSClistNodeFindByValue(3) 4007 CSClistNodeFindByReference(3) 4008 CSClistNodeStat(3) 4009 CSClistNodeValidate(3) 4010 CSClistNodeDel(3) 4011 4012 4013------------------------------------------------------------------------ 4014CSClistStat(3) 4015 4016NAME 4017 CSClistStat - retrieve libcsc list statistics 4018 4019SYNOPSYS 4020 #include "libcsc.h" 4021 4022 int CSClistStat ( 4023 CSClistType const list, 4024 size_t* const pushCountPtr, 4025 size_t* const popCountPtr, 4026 size_t* const maxAllocPtr, 4027 size_t* const curAllocPtr 4028 ); 4029 4030RETURN VALUE 4031 CSClistStat(), if successful, returns CSC_OK; otherwise, 4032 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 4033 to NULL pointers, bad function arguments, and internal data errors, 4034 respectively. 4035 4036DESCRIPTION 4037 CSClistStat() returns some statistics from `list'. 4038 4039 If `pushCountPtr' is not NULL, then CSClistStat() writes the total of 4040 libcsc list pushes to the size_t that is pointed to by `pushCountPtr'. 4041 4042 If `popCountPtr' is not NULL, then CSClistStat() writes the total of 4043 libcsc list pops to the size_t that is pointed to by `popCountPtr'. 4044 4045 If `maxAllocPtr' is not NULL, then CSClistStat() writes the total count 4046 of bytes pushed to the size_t that is pointed to by `maxAllocPtr'. 4047 4048 If `curAllocPtr' is not NULL, then CSClistStat() writes the current 4049 count of bytes in the libcsc list to the size_t that is pointed to by 4050 `curAllocPtr'. 4051 4052SEE ALSO 4053 CSClistNew(3) 4054 CSClistDel(3) 4055 CSClistRead(3) 4056 CSClistWrite(3) 4057 CSClistSetCFunc(3) 4058 CSClistPush(3) 4059 CSClistPop(3) 4060 CSClistPeek(3) 4061 CSClistNodeNext(3) 4062 CSClistNodeFindByValue(3) 4063 CSClistNodeFindByReference(3) 4064 CSClistNodeStat(3) 4065 CSClistNodeValidate(3) 4066 CSClistNodeDel(3) 4067 4068 4069------------------------------------------------------------------------ 4070CSClistWrite(3) 4071 4072NAME 4073 CSClistWrite - write a libcsc list in an ASCII format 4074 4075SYNOPSYS 4076 #include "libcsc.h" 4077 4078 int CSClistWrite ( 4079 int fd, 4080 CSClistType const list 4081 ); 4082 4083RETURN VALUE 4084 CSClistWrite(), if successful, returns CSC_OK; otherwise, CSC_NOTFOUND, 4085 CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL 4086 pointers, bad function arguments, and internal data errors, 4087 respectively. 4088 4089DESCRIPTION 4090 CSClistWrite() writes to `fd' the libcsc list represented by the opaque 4091 `list' in an ASCII format. Small, simple lists will be human-readable 4092 by patient humans, but CSClistRead() will be happy to read it and create 4093 another duplicate libcsc list. In this way, libcsc lists can be 4094 transported between processes, in space or time. 4095 4096 Caution: client pointers stored in the list will be severe aliasing 4097 bugs when they are read by a different process. 4098 4099SEE ALSO 4100 CSClistNew(3) 4101 CSClistDel(3) 4102 CSClistRead(3) 4103 CSClistSetCFunc(3) 4104 CSClistStat(3) 4105 CSClistPush(3) 4106 CSClistPop(3) 4107 CSClistPeek(3) 4108 CSClistNodeNext(3) 4109 CSClistNodeFindByValue(3) 4110 CSClistNodeFindByReference(3) 4111 CSClistNodeStat(3) 4112 CSClistNodeValidate(3) 4113 CSClistNodeDel(3) 4114 4115 4116------------------------------------------------------------------------ 4117CSCmemAlloc(3) 4118 4119NAME 4120 CSCmemAlloc - allocate memory (and keep thrack of it in memList) 4121 4122SYNOPSYS 4123 #include "libcsc.h" 4124 4125 int CSCmemAlloc ( 4126 CSCmemListType const memList, 4127 void** const memPtrPtr, 4128 size_t itemCount, 4129 size_t itemSize, 4130 int tagData 4131 ); 4132 4133RETURN VALUE 4134 CSC_OK ......... successful 4135 4136 RTS_NOMEM ...... if no memory can be dynamically allocated 4137 4138 CSC_BADARG ..... memList or memPtrPtr is NULL or itemCount or itemSize 4139 is zero 4140 4141 CSC_CORRUPT .... corruption is detected in memList 4142 and CSCmemAlloc() is compiled with DEBUG 4143 4144DESCRIPTION 4145 CSCmemAlloc() allocates memory; the number of bytes that are allocated 4146 is `itemCount' multiplied by `itemSize'. 4147 4148 Multiple calls to CSCmemAlloc() can use the same `memList'; each 4149 allocated memory block will be put into `memList' and CSCmemFree() can 4150 be called with `memList' to free the block, or CSCmemListFree() can be 4151 called to free all the memory blocks in `memList'. 4152 4153 NOTE `memList' must first be created with CSCmemInit(). 4154 4155 If CSCmemAlloc() is compiled with DEBUG, then CSCmemAlloc() will fill 4156 newly allocated memory with some well-defined garbage to prevent the 4157 use of accidentally good values. 4158 4159 `tagData' is provided for profiling `memList's. When profiling, 4160 `memList' continues to contain a record of the allocation and free of 4161 the memory; the list doesn't really get smaller (the actual memory 4162 allocations for client code are of course freed). `tagData' is an 4163 arbitrary integer that the caller supplies for easier identification 4164 when using CSCmemListPrintProfile() or CSCmemListWriteProfile() on 4165 `memList'. 4166 4167EXAMPLE 4168 CSCmemListType myList; 4169 void* myData; 4170 int mysize = 100; 4171 int myTag = 55; 4172 int stat; 4173 4174 myList = CSCmemInit ("my data", NULL, NULL, NULL, CSC_DO_PROFILING); 4175 stat = CSCmemAlloc (myList, &myData, 1, mySize, myTag); 4176 . 4177 . 4178 . 4179 stat = CSCmemFree (myList, &myData, myTag); 4180 4181SEE ALSO 4182 CSCmemInit(3) 4183 CSCmemDone(3) 4184 CSCmemDup(3) 4185 CSCmemFree(3) 4186 CSCmemLookup(3) 4187 CSCmemValidate(3) 4188 CSCmemListFree(3) 4189 CSCmemListStat(3) 4190 CSCmemListPrintProfile(3) 4191 CSCmemListWriteProfile(3) 4192 4193 4194------------------------------------------------------------------------ 4195CSCmemDone(3) 4196 4197NAME 4198 CSCmemDone - cleanup and remove a memList (free all its memory) 4199 4200SYNOPSYS 4201 #include "libcsc.h" 4202 4203 int CSCmemDone (CSCmemListType const memList); 4204 4205RETURN VALUE 4206 CSC_OK ......... successful 4207 4208 CSC_BADARG ..... memList is NULL 4209 4210 CSC_CORRUPT .... corruption is detected in memList 4211 and CSCmemDone() is compiled with DEBUG 4212 4213DESCRIPTION 4214 CSCmemDone() unconditionally remves all memory blocks contained in 4215 `memList' and then removes `memList' itself. `memList' is not checked 4216 for profiling; no statistics for `memList' are retained. 4217 4218 Do not try to use `memList' after calling CSCmemDone(), at least until 4219 using `memList' in another CSCmemInit(). 4220 4221 If CSCmemDone() is compiled with DEBUG, then the memory is shredded 4222 by writing well-defined garbage to it before it is freed. This avoids 4223 code that accidentally works by using deallocated memory that hasn't 4224 yet changed. 4225 4226SEE ALSO 4227 CSCmemInit(3) 4228 CSCmemAlloc(3) 4229 CSCmemDup(3) 4230 CSCmemLookup(3) 4231 CSCmemValidate(3) 4232 CSCmemFree(3) 4233 CSCmemListFree(3) 4234 CSCmemListStat(3) 4235 CSCmemListPrintProfile(3) 4236 CSCmemListWriteProfile(3) 4237 4238 4239------------------------------------------------------------------------ 4240CSCmemDup(3) 4241 4242NAME 4243 CSCmemDup - duplicate (dynamically allocate and copy) memory 4244 4245SYNOPSYS 4246 #include "libcsc.h" 4247 4248 int CSCmemDup ( 4249 CSCmemListType const memList, 4250 void** const dstPtrPtr, 4251 const void* srcPtr, 4252 size_t size, 4253 int tagData 4254 ); 4255 4256RETURN VALUE 4257 CSC_OK ......... successful, the memory pointed to by memPtr is 4258 duplicated 4259 4260 CSC_BADARG ..... memList, dstPtrPtr, or srcPtr is NULL or size is zero 4261 4262 CSC_CORRUPT .... corruption is detected in memList 4263 and CSCmemDup() is compiled with DEBUG 4264 4265DESCRIPTION 4266 CSCmemDup() dynamically allocates `size' bytes and copies `size' bytes 4267 from `srcPtr' into the newly allocated memory. 4268 4269 `tagData' is provided for profiling `memList's. When profiling, 4270 `memList' continues to contain a record of the allocation and free of 4271 the memory; the list doesn't really get smaller (the actual memory 4272 allocations for client code are of course freed). `tagData' is an 4273 arbitrary integer that the caller supplies for easier identification 4274 when using CSCmemListPrintProfile() or CSCmemListWriteProfile() on the 4275 `memList'. 4276 4277 `srcPtr' can point to any readable memory. This may be usefull for 4278 creating dynamic duplicates of constant strings, etc. 4279 4280EXAMPLE 4281 CSCmemListType myList; 4282 void* myData; 4283 int stat; 4284 4285 myList = CSCmemInit ("my data", NULL, NULL, NULL, CSC_DO_PROFILING); 4286 . 4287 . 4288 . 4289 stat = CSCmemDup (myList, &myData, "duplicate this string", 22, myTag); 4290 4291SEE ALSO 4292 CSCmemInit(3) 4293 CSCmemDone(3) 4294 CSCmemAlloc(3) 4295 CSCmemFree(3) 4296 CSCmemLookup(3) 4297 CSCmemValidate(3) 4298 CSCmemListFree(3) 4299 CSCmemListStat(3) 4300 CSCmemListPrintProfile(3) 4301 CSCmemListWriteProfile(3) 4302 4303 4304------------------------------------------------------------------------ 4305CSCmemFree(3) 4306 4307NAME 4308 CSCmemFree - free dynamically allocated memory 4309 4310SYNOPSYS 4311 #include "libcsc.h" 4312 4313 int CSCmemFree ( 4314 CSCmemListType const memList, 4315 void** const memPtrPtr, 4316 int tagData 4317 ); 4318 4319RETURN VALUE 4320 CSC_OK ......... successful, memPtr was found in memList, and the 4321 memory pointed to by memPtr is freed 4322 4323 CSC_NOTFOUND ... memPtr not found in memList, or memList has no 4324 allocated blocks 4325 4326 CSC_BADARG ..... memList or memPtrPtr is NULL 4327 4328 CSC_CORRUPT .... corruption is detected in memList 4329 and CSCmemFree() is compiled with DEBUG 4330 4331DESCRIPTION 4332 CSCmemFree() frees the dynamically allocated memory whose address is 4333 pointed to by `memPtr'. The memory to be freed is checked and validated 4334 in `memList'. If it is not found in `memList', then no memory is freed. 4335 4336 Because of the `memList' usage, don't use CSCmemFree() on memory you got 4337 from malloc(), calloc(), etc. 4338 4339 If CSCmemFree() is compiled with DEBUG, then the memory is shredded 4340 by writing well-defined garbage to it before it is freed. This avoids 4341 code that accidentally works by using deallocated memory that hasn't 4342 yet changed. 4343 4344 `tagData' is provided for profiling `memList's. When profiling, 4345 `memList' continues to contain a record of the allocation and free of 4346 the memory; the list doesn't really get smaller (the actual memory 4347 allocations for client code are of course freed). `tagData' is an 4348 arbitrary integer that the caller supplies for easier identification 4349 when using CSCmemListPrintProfile() or CSCmemListWriteProfile() on the 4350 `memList'. 4351 4352EXAMPLE 4353 CSCmemListType myList; 4354 void* myData; 4355 int mysize = 100; 4356 int myTag = 55; 4357 int stat; 4358 4359 myList = CSCmemInit ("my data", NULL, NULL, NULL, CSC_DO_PROFILING); 4360 stat = CSCmemAlloc (myList, &myData, 1, mySize, myTag); 4361 . 4362 . 4363 . 4364 stat = CSCmemFree (myList, &myData, myTag); 4365 4366SEE ALSO 4367 CSCmemInit(3) 4368 CSCmemDone(3) 4369 CSCmemAlloc(3) 4370 CSCmemDup(3) 4371 CSCmemLookup(3) 4372 CSCmemValidate(3) 4373 CSCmemListFree(3) 4374 CSCmemListStat(3) 4375 CSCmemListPrintProfile(3) 4376 CSCmemListWriteProfile(3) 4377 4378 4379------------------------------------------------------------------------ 4380CSCmemInit(3) 4381 4382NAME 4383 CSCmemInit - initialize a csc memlist for subsequent memory allocations 4384 4385SYNOPSYS 4386 #include "libcsc.h" 4387 4388 CSCmemListType CSCmemInit ( 4389 const char* name, 4390 CSCtagFnType tagFunc, 4391 CSCmonFnType monFunc, 4392 void* monData, 4393 CSCprofileType profiling 4394 ); 4395 4396RETURN VALUE 4397 If successful CSCmemInit() returns a newly created csc memlist; 4398 otherwise, when unsuccessful CSCmemInit() returns NULL. 4399 4400DESCRIPTION 4401 CSCmemInit() creates and returns a csc memlist. 4402 4403 A csc memlist is needed to allocate and free memory using the csc memory 4404 subsystem. The csc memory subsystem records statistics on its allocate 4405 and free activities into csc memlists. The csc memory subsystem also 4406 uses the csc memlist to help detect memory leaks and other misuses. 4407 4408 Memory allocated with a given csc memlist must be freed with the same 4409 csc memlist. 4410 4411 NOTE No arguments are copied; the string pointed to by `name' (if 4412 not NULL) and the client data pointed to by `monData' (if not 4413 NULL) are *NOT* copied. The client is responsible for ensuring 4414 that the data are valid until the csc memlist itself is freed by 4415 CSCmemListFree(). 4416 4417 `name' can be NULL, but it should point to a descriptive string. The 4418 string is printed when the csc memlist profile is printed. 4419 4420 `tagFunc' can be NULL. When it is not NULL, it is used as a callback 4421 function during the printing of a csc memlist profile to retreive a 4422 (descriptive) string associated with the integer tag given when memory 4423 was allocated/freed. This helps to identified memory that has not been 4424 freed (leaked). 4425 4426 `monFunc' and `monData': 4427 The csc memory subsystem makes no assumptions about the threading 4428 environment, or even if the environment is threaded or not. It is the 4429 caller's (client's) responsibility to provide mutual exclusion locking 4430 for the csc memory subsystem. This allows the csc memory subsystem to 4431 function in multiple environments. `monFunc' is used to provide mutual 4432 exclusion locking for thread safty. If a proper modFunc is provided, 4433 then multiple threads may share a given csc memlist to allocate and free 4434 memory. `monFunc' is a callback function used to enter and exit the 4435 critical regions when updating the csc memlist. `monFunc' is invoked 4436 with the the client's `monData'; the calback function should enforce 4437 locking (mutex). `monFunc' is invoked with CSC_IO_IN and `monData' when 4438 entering a critical region an it is invoked with CSC_IO_OUT and 4439 `monData' when exiting a critical region. `monData' is provided so that 4440 the client can have it point to the necessary mutex (and/or whatever) 4441 and the csc memory subsystem delivers it to the callback. In this way 4442 the client does not otherwise have to keep track of the mutex. If the 4443 environment is not threaded, and no mutex is needed, then `monFunc' 4444 should be NULL. 4445 4446 `profiling' specifies whether alocate/free statistics should actually be 4447 generated and kept in the csc memlist. 4448 4449SEE ALSO 4450 CSCmemDone(3) 4451 CSCmemAlloc(3) 4452 CSCmemDup(3) 4453 CSCmemFree(3) 4454 CSCmemLookup(3) 4455 CSCmemValidate(3) 4456 CSCmemListFree(3) 4457 CSCmemListStat(3) 4458 CSCmemListPrintProfile(3) 4459 CSCmemListWriteProfile(3) 4460 4461 4462------------------------------------------------------------------------ 4463CSCmemListFree(3) 4464 4465NAME 4466 CSCmemListFree - free all memory allocated in a memList 4467 4468SYNOPSYS 4469 #include "libcsc.h" 4470 4471 int CSCmemListFree ( 4472 CSCmemListType const memList, 4473 int tagData 4474 ); 4475 4476RETURN VALUE 4477 CSC_OK ......... successful 4478 4479 CSC_NOTFOUND ... memList has no allocated blocks 4480 4481 CSC_BADARG ..... memList is NULL 4482 4483 CSC_CORRUPT .... corruption is detected in memList 4484 and CSCmemListFree() is compiled with DEBUG 4485 4486DESCRIPTION 4487 CSCmemListFree() frees all the memory described by `memList'. This is 4488 memory allocations for client code that was allocated by using `memList' 4489 with functions like CSCmemAlloc(). The actual `memList' itself is not 4490 freed. 4491 4492 CSCmemListFree() is a convenient mechanism to free many allocations of 4493 memory with a single function. 4494 4495 `tagData' is provided for profiling `memList's. When profiling, the 4496 `memList' continues to contain a record of the allocation and free of 4497 the memory; the list doesn't really get smaller (the actual memory 4498 allocations for client code are of course freed). `tagData' is an 4499 arbitrary integer that the caller supplies for easier identification 4500 when using CSCmemListPrintProfile() or CSCmemListWriteProfile() on the 4501 `memList'. 4502 4503SEE ALSO 4504 CSCmemInit(3) 4505 CSCmemDone(3) 4506 CSCmemAlloc(3) 4507 CSCmemDup(3) 4508 CSCmemFree(3) 4509 CSCmemLookup(3) 4510 CSCmemValidate(3) 4511 CSCmemListStat(3) 4512 CSCmemListPrintProfile(3) 4513 CSCmemListWriteProfile(3) 4514 4515 4516------------------------------------------------------------------------ 4517CSCmemListPrintProfile(3) 4518 4519NAME 4520 CSCmemListPrintProfile - write a memlist profile to standard output 4521 4522SYNOPSYS 4523 #include "libcsc.h" 4524 4525 int CSCmemListPrintProfile ( 4526 CSCmemListType const memList, 4527 CSCprofileType showing 4528 ); 4529 4530RETURN VALUE 4531 CSC_OK ........ successful 4532 4533 CSC_BADARG .... memList is NULL 4534 4535 CSC_CORRUPT ... corruption is detected in memList 4536 and CSCmemListWriteProfile() is compiled with DEBUG 4537 4538DESCRIPTION 4539 CSCmemListPrintProfile() writes to standard output the information of 4540 the dynamically allocated memory blocks that are described in `memList'. 4541 4542 CSCmemListPrintProfile() calls CSCmemListWriteProfile() to do the work; 4543 so, go read about CSCmemListWriteProfile(). 4544 4545SEE ALSO 4546 CSCmemInit(3) 4547 CSCmemDone(3) 4548 CSCmemAlloc(3) 4549 CSCmemDup(3) 4550 CSCmemFree(3) 4551 CSCmemLookup(3) 4552 CSCmemValidate(3) 4553 CSCmemListFree(3) 4554 CSCmemListStat(3) 4555 CSCmemListWriteProfile(3) 4556 4557 4558------------------------------------------------------------------------ 4559CSCmemListStat(3) 4560 4561NAME 4562 CSCmemListStat - get information about a memList 4563 4564SYNOPSYS 4565 #include "libcsc.h" 4566 4567 int CSCmemListStat ( 4568 CSCmemListType const memList, 4569 size_t* const allocCountPtr, 4570 size_t* const freeCountPtr, 4571 size_t* const maxMemAllocPtr, 4572 size_t* const curMemAllocPtr 4573 ); 4574 4575RETURN VALUE 4576 CSC_OK ............. successful 4577 4578 CSC_NO_PROFILING ... memList is not profiling 4579 4580 CSC_BADARG ......... memList is NULL 4581 4582 CSC_CORRUPT ........ corruption is detected in memList 4583 and CSCmemListStat() is compiled with DEBUG 4584 4585DESCRIPTION 4586 CSCmemListStat() can return the allocate count, free count, current 4587 allocating, and highest allocation from `memList', if `memList' was 4588 specified when it was created by CSCmemInit() to be profiling. 4589 4590 When profiling: 4591 4592 If `allocCountPtr' is not NULL, then CSCmemListStat() writes to 4593 the size_t pointed to by `allocCountPtr' the total number of 4594 allocates. 4595 4596 If `freeCountPtr' is not NULL, then CSCmemListStat() writes to 4597 the size_t pointed to by `freeCountPtr' the total number of 4598 frees. 4599 4600 If `maxMemAllocPtr' is not NULL, then CSCmemListStat() writes to 4601 the size_t pointed to by `maxMemAllocPtr' the number of bytes 4602 ever allocated at one time. 4603 4604 If `curMemAllocPtr' is not NULL, then CSCmemListStat() writes to 4605 the size_t pointed to by `curMemAllocPtr' the number of 4606 currently allocated bytes. 4607 4608 CSCmemListStat() can be used to determine if `memList' is profiling by 4609 using NULL for all of `allocCountPtr', `freeCountPtr', `maxMemAllocPtr', 4610 and `curMemAllocPtr'. CSC_NO_PROFILING is returned if `memList' is not 4611 profiling and CSC_OK is returned if `memList' is profiling. 4612 4613SEE ALSO 4614 CSCmemInit(3) 4615 CSCmemDone(3) 4616 CSCmemAlloc(3) 4617 CSCmemDup(3) 4618 CSCmemFree(3) 4619 CSCmemLookup(3) 4620 CSCmemValidate(3) 4621 CSCmemListFree(3) 4622 CSCmemListPrintProfile(3) 4623 CSCmemListWriteProfile(3) 4624 4625 4626------------------------------------------------------------------------ 4627CSCmemListWriteProfile(3) 4628 4629NAME 4630 CSCmemListWriteProfile - write a memlist profile to a file descriptor 4631 4632SYNOPSYS 4633 #include "libcsc.h" 4634 4635 int CSCmemListWriteProfile ( 4636 CSCmemListType const memList, 4637 int fd, 4638 CSCprofileType showing 4639 ); 4640 4641RETURN VALUE 4642 CSC_OK ........ successful 4643 4644 CSC_BADARG .... memList is NULL 4645 4646 CSC_CORRUPT ... corruption is detected in memList 4647 and CSCmemListWriteProfile() is compiled with DEBUG 4648 4649DESCRIPTION 4650 CSCmemListWriteProfile() writes to `fd' the information of the 4651 dynamically allocated memory blocks that are described in `memList'. 4652 4653 Use CSCmemListWriteProfile() and CSCmemListPrintProfile() to verify that 4654 there are no memory leaks. 4655 4656 This information written by CSCmemListWriteProfile() begins with a 4657 header of the name, tag function, monitor function, and profiling as 4658 specified when `memList' was created by CSCmemInit(). If `memList' was 4659 specified when it was created by CSCmemInit() to be profiling, then the 4660 allocate count, free count, current allocating, and highest allocation 4661 are included in the header information. 4662 4663 If `showing' is CSC_SHOW_ALL, then a list of allocationed/freeed blocks 4664 follows the header. The unfreed memory allocations are described by data 4665 address, size, and the allocate tag provided by the client code that 4666 called CSCmemAlloc(). If `memList' was specified to be profiling, then 4667 freed memory alocations remain in the list. In this case they will be 4668 included in this list of information but there is no data address and 4669 size, only an allocate tag and a free tag. 4670 4671 If `showing' is CSC_SHOW_ALLOCATED, then only allocated blocks are 4672 shown. 4673 4674SEE ALSO 4675 CSCmemInit(3) 4676 CSCmemDone(3) 4677 CSCmemAlloc(3) 4678 CSCmemDup(3) 4679 CSCmemFree(3) 4680 CSCmemLookup(3) 4681 CSCmemValidate(3) 4682 CSCmemListFree(3) 4683 CSCmemListStat(3) 4684 CSCmemListPrintProfile(3) 4685 4686 4687------------------------------------------------------------------------ 4688CSCmemLookup(3) 4689 4690NAME 4691 CSCmemLookup - lookup a memory pointer in memList 4692 4693SYNOPSYS 4694 #include "libcsc.h" 4695 4696 int CSCmemLookup ( 4697 CSCmemListType const memList, 4698 const void* memPtr, 4699 size_t* const sizePtr, 4700 int* const tagPtr 4701 ); 4702 4703RETURN VALUE 4704 CSC_OK ......... successful, memPtr was found in memList 4705 4706 CSC_NOTFOUND ... memPtr not found in memList, or memList has no 4707 allocated blocks 4708 4709 CSC_BADARG ..... memList or memPtr is NULL 4710 4711 CSC_CORRUPT .... corruption is detected in memList 4712 and CSCmemLookup() is compiled with DEBUG 4713 4714DESCRIPTION 4715 CSCmemLookup() looks up `memPtr' in `memList' to validate it, and if 4716 found returns its statistics: size of the data block pointer to by 4717 `memPtr' and the tag that was used to allocate the block of memory 4718 pointed to by `memPtr'. 4719 4720 If `sizePtr' is not NULL, then the size of the allocated memory block 4721 pointed to by `memPtr' is written to the size_t pointed to by `sizePtr'. 4722 4723 If `tagPtr' is not NULL, then the tag that was used to allocate the 4724 block of memory pointed to by `memPtr' is written to the int pointed to 4725 by `tagPtr'. 4726 4727 Either, or both, of `sizePtr' and `tagPtr' can be NULL. If both are 4728 NULL, then CSCmemLookup() pretty much acts like CSCmemValidate(). 4729 4730SEE ALSO 4731 CSCmemInit(3) 4732 CSCmemDone(3) 4733 CSCmemAlloc(3) 4734 CSCmemDup(3) 4735 CSCmemFree(3) 4736 CSCmemValidate(3) 4737 CSCmemListFree(3) 4738 CSCmemListStat(3) 4739 CSCmemListPrintProfile(3) 4740 CSCmemListWriteProfile(3) 4741 4742 4743------------------------------------------------------------------------ 4744CSCmemValidate(3) 4745 4746NAME 4747 CSCmemValidate - validate that a memory pointer is in memList 4748 4749SYNOPSYS 4750 #include "libcsc.h" 4751 4752 int CSCmemValidate ( 4753 CSCmemListType const memList, 4754 const void* memPtr 4755 ); 4756 4757RETURN VALUE 4758 CSC_OK ......... successful, memPtr was found in memList 4759 4760 CSC_NOTFOUND ... memPtr not found in memList, or memList has no 4761 allocated blocks 4762 4763 CSC_BADARG ..... memList is or memPtr NULL 4764 4765 CSC_CORRUPT .... corruption is detected in memList 4766 and CSCmemValidate() is compiled with DEBUG 4767 4768DESCRIPTION 4769 CSCmemValidate() looks up `memPtr' in `memList' to validate it. 4770 4771SEE ALSO 4772 CSCmemInit(3) 4773 CSCmemDone(3) 4774 CSCmemAlloc(3) 4775 CSCmemDup(3) 4776 CSCmemFree(3) 4777 CSCmemLookup(3) 4778 CSCmemListFree(3) 4779 CSCmemListStat(3) 4780 CSCmemListPrintProfile(3) 4781 CSCmemListWriteProfile(3) 4782 4783 4784------------------------------------------------------------------------ 4785CSCnotificationBoardDel(3) 4786 4787NAME 4788 CSCnotificationBoardDel - completely remove a notification board 4789 4790SYNOPSYS 4791 #include "libcsc.h" 4792 4793 int CSCnotificationBoardDel ( 4794 CSCnotificationBoardType const board 4795 ); 4796 4797RETURN VALUE 4798 CSCnotificationBoardDel(), if successful, returns CSC_OK; otherwise, 4799 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 4800 to NULL pointers, bad function arguments, and internal data errors, 4801 respectively. 4802 4803DESCRIPTION 4804 CSCnotificationBoardDel() deletes the notification `board' including all 4805 the notification entries it contains. 4806 4807SEE ALSO 4808 CSCnotificationBoardNew(3) 4809 CSCnotificationBoardPrint(3) 4810 CSCnotificationNew(3) 4811 CSCnotificationDel(3) 4812 CSCnotificationPost(3) 4813 CSCnotificationRegister(3) 4814 4815 4816------------------------------------------------------------------------ 4817CSCnotificationBoardNew(3) 4818 4819NAME 4820 CSCnotificationBoardNew - create a new notification board 4821 4822SYNOPSYS 4823 #include "libcsc.h" 4824 4825 CSCnotificationBoardType CSCnotificationBoardNew ( 4826 const char* name, 4827 CSCmonFnType monFunc, 4828 const void* monData, 4829 CSCprofileType profiling 4830 ); 4831 4832RETURN VALUE 4833 CSCnotificationBoardNew(), if successful, returns an opaque data type 4834 representing a new libcsc notification board, or NULL if otherwise not 4835 successful. 4836 4837DESCRIPTION 4838 CSCnotificationBoardNew() creates a new libcsc notification board. A 4839 notification board is simply something to hold an arbitrary number of 4840 notifications (like a cork note board). 4841 4842 `profiling' can be CSC_DO_PROFILING or CSC_NO_PROFILING; it specifies 4843 whether alocate/free statistics should actually be generated and kept 4844 in the list. 4845 4846SEE ALSO 4847 CSCnotificationBoardDel(3) 4848 CSCnotificationBoardPrint(3) 4849 CSCnotificationNew(3) 4850 CSCnotificationDel(3) 4851 CSCnotificationPost(3) 4852 CSCnotificationRegister(3) 4853 4854 4855------------------------------------------------------------------------ 4856CSCnotificationBoardPrint(3) 4857 4858NAME 4859 CSCnotificationBoardPrint - print a notification board in ASCII format 4860 4861SYNOPSYS 4862 #include "libcsc.h" 4863 4864 void CSCnotificationBoardPrint ( 4865 CSCnotificationBoardType const board 4866 ); 4867 4868RETURN VALUE 4869 CSCnotificationBoardPrint() has no return value. 4870 4871DESCRIPTION 4872 CSCnotificationBoardPrint() prints to standard output the libcsc 4873 notification board represented by the opaque `board' in an ASCII format. 4874 4875BUGS 4876 There is no error check in this function. Lame. 4877 4878SEE ALSO 4879 CSCnotificationBoardNew(3) 4880 CSCnotificationBoardDel(3) 4881 CSCnotificationNew(3) 4882 CSCnotificationDel(3) 4883 CSCnotificationPost(3) 4884 CSCnotificationRegister(3) 4885 4886 4887------------------------------------------------------------------------ 4888CSCnotificationDel(3) 4889 4890NAME 4891 CSCnotificationDel - delete a notification from a board 4892 4893SYNOPSYS 4894 #include "libcsc.h" 4895 4896 int CSCnotificationDel ( 4897 CSCnotificationBoardType const board, 4898 const char* name 4899 ); 4900 4901RETURN VALUE 4902 CSCnotificationDel(), if successful, returns CSC_OK; otherwise, 4903 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 4904 to NULL pointers, bad function arguments, and internal data errors, 4905 respectively. 4906 4907DESCRIPTION 4908 CSCnotificationDel() looks in the notification `board' for the 4909 notification entry whose name matches `name' and deletes it. 4910 4911BUGS 4912 Any clients registered for the particular notification being deleted 4913 will NOT be notified. 4914 4915SEE ALSO 4916 CSCnotificationBoardNew(3) 4917 CSCnotificationBoardDel(3) 4918 CSCnotificationBoardPrint(3) 4919 CSCnotificationNew(3) 4920 CSCnotificationPost(3) 4921 CSCnotificationRegister(3) 4922 4923 4924------------------------------------------------------------------------ 4925CSCnotificationNew(3) 4926 4927NAME 4928 CSCnotificationNew - create a new notification in a board 4929 4930SYNOPSYS 4931 #include "libcsc.h" 4932 4933 int CSCnotificationNew ( 4934 CSCnotificationBoardType const board, 4935 const char* name, 4936 CSCgenFnType errfn 4937 ); 4938 4939RETURN VALUE 4940 CSCnotificationNew(), if successful, CSC_OK; otherwise, CSC_NOTFOUND, 4941 CSC_BADARG, and CSC_CORRUPT can be returned corresponding to NULL 4942 pointers, bad function arguments, and internal data errors, 4943 respectively. 4944 4945DESCRIPTION 4946 CSCnotificationNew() creates a new notification entry and puts it into 4947 notification `board'. 4948 4949 `name' points to the character string that names the new notification 4950 entry. 4951 4952 `errfn' is a pointer to a libcsc CSCgenFnType function that is called 4953 when a call to `post' a notification, CSCnotificationPost() (which 4954 tries to distribute the notification), results in an an error. The 4955 prototype for `errfn' is: 4956 4957 int (*CSCgenFnType) (int, int, void*); 4958 4959 The client callback error function `errfn' is called with the current 4960 notification count and notification `name'; its return value is ignored: 4961 4962 (void)((*errfn) (0, count, name); 4963 4964SEE ALSO 4965 CSCnotificationBoardNew(3) 4966 CSCnotificationBoardDel(3) 4967 CSCnotificationBoardPrint(3) 4968 CSCnotificationDel(3) 4969 CSCnotificationPost(3) 4970 CSCnotificationRegister(3) 4971 4972 4973------------------------------------------------------------------------ 4974CSCnotificationPost(3) 4975 4976NAME 4977 CSCnotificationPost - post to a notification in a board 4978 4979SYNOPSYS 4980 #include "libcsc.h" 4981 4982 int CSCnotificationPost ( 4983 CSCnotificationBoardType const board, 4984 const char* name 4985 ); 4986 4987RETURN VALUE 4988 CSCnotificationPost(), if successful, returns CSC_OK; otherwise, 4989 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 4990 to NULL pointers, bad function arguments, and internal data errors, 4991 respectively. 4992 4993DESCRIPTION 4994 CSCnotificationPost() dispatches all client functions registered for 4995 particular notification `name' in notification `board'. 4996 4997 As the dispatched client functions are called they should return 4998 CSC_OK or CSC_NOTOUND. If CSC_NOTFOUND is returned by a client 4999 function, then no more client functions registered for the notification 5000 are called for the particular notification action and and the 5001 notification's error function, pointed to by errfn, is called. The 5002 error function, pointed to by errfn, is associated with the 5003 notification entry when the notification entry is created. The error 5004 function's return value is ignored. 5005 5006 The client functions are called in the order of their priority, which 5007 they specify with the tag value when they register. 5008 5009 Client functions are libcsc CSCgenFnType types; their prototype is: 5010 5011 int (*CSCgenFnType) (int, int, void*); 5012 5013 The client functions are called with a notification count, 5014 client-specified integer tag (used as the priority specifying the order 5015 in which the client functions are called), and client-specified data 5016 (with which they register): 5017 5018 (*fn) (count, tag, data); 5019 5020SEE ALSO 5021 CSCnotificationBoardNew(3) 5022 CSCnotificationBoardDel(3) 5023 CSCnotificationBoardPrint(3) 5024 CSCnotificationNew(3) 5025 CSCnotificationDel(3) 5026 CSCnotificationRegister(3) 5027 5028 5029------------------------------------------------------------------------ 5030CSCnotificationRegister(3) 5031 5032NAME 5033 CSCnotificationRegister - register client function to a notification 5034 5035SYNOPSYS 5036 #include "libcsc.h" 5037 5038 int CSCnotificationRegister ( 5039 CSCnotificationBoardType const board, 5040 const char* notifName, 5041 const char* clientName, 5042 CSCgenFnType fn, 5043 const CSCboolean* runFlag, 5044 int tag, 5045 const void* data 5046 ); 5047 5048RETURN VALUE 5049 CSCnotificationRegister(), if successful, returns CSC_OK; otherwise, 5050 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 5051 to NULL pointers, bad function arguments, and internal data errors, 5052 respectively. 5053 5054DESCRIPTION 5055 CSCnotificationRegister() registers the client function pointed to by 5056 `fn' with the notification entry named by `notifName' in the 5057 notification board associated with `board'. 5058 5059 Client functions are libcsc CSCgenFnType types; their prototype is: 5060 5061 int (*CSCgenFnType) (int, int, void*); 5062 5063 The client functions are called with a notification count, 5064 client-specified integer tag, and client-specified data (with which 5065 they register): 5066 5067 (*fn) (count, tag, data); 5068 5069 Client functions should return CSC_OK or CSC_NOTOUND. If CSC_NOTFOUND 5070 is returned by a client function, then no more client functions 5071 registered for the notification are called for the particular 5072 notification action, and and the notification's error function, 5073 pointed to by errfn, is called. The error function, pointed to by 5074 errfn, is associated with the notification entry when the notification 5075 entry is created. The error function's return value is ignored. 5076 5077 `clientName' is used only for debug messages and notification board 5078 printing. 5079 5080 When the notification named `notifName' is posted to, the function 5081 pointed to by `fn' is called. `tag' and `data' are returned to the 5082 client as arguments to the client function `fn'. 5083 5084 All client functions registered to a notification are called in order 5085 of their priority. `tag' is used as the priority; all the client 5086 functions registered to a notification are called in the numerical 5087 value order of their tag. 5088 5089 The client can dynamically control the calling of its registered 5090 function; if the value at `runFlag' is CSC_FALSE when the notification 5091 is posted to, then the registered client function will not be called. 5092 5093SEE ALSO 5094 CSCnotificationBoardNew(3) 5095 CSCnotificationBoardDel(3) 5096 CSCnotificationBoardPrint(3) 5097 CSCnotificationNew(3) 5098 CSCnotificationDel(3) 5099 CSCnotificationPost(3) 5100 5101 5102------------------------------------------------------------------------ 5103CSCsockConnectUDP(3) 5104 5105NAME 5106 CSCsockConnectUDP - initiate a socket connection 5107 5108SYNOPSYS 5109 #include "libcsc.h" 5110 5111 int CSCsockConnectUDP ( 5112 int* const socketPtr, 5113 const char* host, 5114 const char* service, 5115 CSCgenFnType errorCallback 5116 ); 5117 5118RETURN VALUE 5119 CSC_OK .......... successful, and the integer pointed to by socketPtr 5120 will be updated with the new socket descriptor 5121 5122 CSC_NOTFOUND .... can't make sense of host 5123 5124 CSC_NOSVC ....... can't make sense of service 5125 5126 CSC_NOPROT ...... can't make any sense out of the UDP protocol 5127 5128 CSC_NOSOCK ...... can't allocate a new socket or can't set a socket 5129 option 5130 5131 CSC_BADARG ...... socketPtr or service is NULL or connectCount is zero 5132 5133DESCRIPTION 5134 CSCsockConnectUDP() attempts to create a PF_INET (IPv4) protocol 5135 socket and make a UDP (SOCK_DGRAM) connection to another socket. 5136 5137 The other socket to which to connect is expected to be on `host' and 5138 `service', where `host' is the hostname or IP address, and `service' is 5139 the service or port number. If `service' specifies port number, then the 5140 integer value must fit in an unsigned 16 bit variable 5141 (0 <= sevice <= 65535). For example: 5142 5143 host service 5144 ---- ------- 5145 "batman" "telnet" 5146 "spidergirl" "5200" 5147 "198.168.0.2" "finger" 5148 "198.168.0.2" "5200" 5149 5150 Error conditions are announced via `errorCallback', if it is not NULL. 5151 The `errorCallback' function is called with the CSCsockConnectUDP() 5152 return value, errno, and a string describing the error e.g., 5153 5154 (*errorCallback) (CSC_NOSOCK, errno, "can't create socket"); 5155 5156BUGS 5157 There's no "connection" in UDP! CSCsockConnectUDP() probably shouldn't 5158 call connect() to make a connection. 5159 5160SEE ALSO 5161 CSCsockConnectTCP(3) 5162 CSCsockPassiveTCP(3) 5163 CSCsockPassiveUDP(3) 5164 5165 5166------------------------------------------------------------------------ 5167CSCsockPassiveTCP(3) 5168 5169NAME 5170 CSCsockPassiveTCP - listen for connections on a socket 5171 5172SYNOPSYS 5173 #include "libcsc.h" 5174 5175 int CSCsockPassiveTCP ( 5176 int* const socketPtr, 5177 const char* service, 5178 int connectCount, 5179 CSCgenFnType errorCallback 5180 ); 5181 5182RETURN VALUE 5183 CSC_OK .......... successful, and the integer pointed to by socketPtr 5184 will be updated with the new socket descriptor 5185 5186 CSC_NOSVC ....... can't make sense of service 5187 5188 CSC_NOPROT ...... can't make any sense out of the UDP protocol 5189 5190 CSC_NOSOCK ...... can't allocate a new socket or can't set a socket 5191 option 5192 5193 CSC_NOBIND ...... can't bind socket to service 5194 5195 CSC_NOLISTEN .... can't listen to socket 5196 5197 CSC_BADARG ...... socketPtr or service is NULL or connectCount is zero 5198 5199DESCRIPTION 5200 CSCsockPassiveTCP() attempts to create a PF_INET (IPv4) protocol socket 5201 and prepares it to accept TCP (SOCK_STREAM) connections. No accept() is 5202 actually tried, this must be done after calling CSCsockPassiveTCP(). 5203 5204 If successful, CSCsockPassiveTCP() creates a socket that is prepared 5205 to accept a connection from any IP. 5206 5207 The `service' argument is a string that represents the the service (see 5208 /etc/services) or port number. If `service' specifies port number, then 5209 the integer value must fit in an unsigned 16 bit variable 5210 (0 <= sevice <= 65535). For example: 5211 5212 service 5213 ------- 5214 "echo" 5215 "5200" 5216 "fsp" 5217 "7200" 5218 5219 The socket is set with the SO_REUSEADDR option to enable quick reuse of 5220 the same port. 5221 5222 `connectCount' is the connection backlog (the number of allowed 5223 concurrent connections). 5224 5225 Error conditions are announced via `errorCallback', if it is not NULL. 5226 The `errorCallback' function is called with the CSCsockPassiveUDP() 5227 return value, errno, and a string describing the error e.g., 5228 5229 (*errorCallback) (CSC_NOSOCK, errno, "can't create socket"); 5230 5231BUGS 5232 Cannot select a desired host from which to accept a connection. 5233 5234SEE ALSO 5235 CSCsockConnectTCP(3) 5236 CSCsockConnectUDP(3) 5237 CSCsockPassiveUDP(3) 5238 5239 5240------------------------------------------------------------------------ 5241CSCsockPassiveUDP(3) 5242 5243NAME 5244 CSCsockPassiveUDP - listen for connections on a socket 5245 5246SYNOPSYS 5247 #include "libcsc.h" 5248 5249 int CSCsockPassiveUDP ( 5250 int* const socketPtr, 5251 const char* service, 5252 int connectCount, 5253 CSCgenFnType errorCallback 5254 ); 5255 5256RETURN VALUE 5257 CSC_OK .......... successful, and the integer pointed to by socketPtr 5258 will be updated with the new socket descriptor 5259 5260 CSC_NOSVC ....... can't make sense of service 5261 5262 CSC_NOPROT ...... can't make any sense out of the UDP protocol 5263 5264 CSC_NOSOCK ...... can't allocate a new socket or can't set a socket 5265 option 5266 5267 CSC_NOBIND ...... can't bind socket to service 5268 5269 CSC_NOLISTEN .... can't listen to socket 5270 5271 CSC_BADARG ...... socketPtr or service is NULL or connectCount is zero 5272 5273DESCRIPTION 5274 CSCsockPassiveUDP() attempts to create a PF_INET (IPv4) protocol socket 5275 and prepares it to accept UDP (SOCK_DGRAM) connections. 5276 5277 If successful, CSCsockPassiveUDP() creates a socket that is prepared 5278 to accept a datagrams from any IP. 5279 5280 The `service' argument is a string that represents the the service (see 5281 /etc/services) or port number. If `service' specifies port number, then 5282 the integer value must fit in an unsigned 16 bit variable 5283 (0 <= sevice <= 65535). For example: 5284 5285 service 5286 ------- 5287 "echo" 5288 "5200" 5289 "fsp" 5290 "7200" 5291 5292 The socket is set with the SO_REUSEADDR option to enable quick reuse of 5293 the same port. 5294 5295 `connectCount' is the connection backlog (the number of allowed 5296 concurrent connections). 5297 5298 Error conditions are announced via `errorCallback', if it is not NULL. 5299 The `errorCallback' function is called with the CSCsockPassiveUDP() 5300 return value, errno, and a string describing the error e.g., 5301 5302 (*errorCallback) (CSC_NOSOCK, errno, "can't create socket"); 5303 5304BUGS 5305 There's no "connection" in UDP! This function should be re-coded to 5306 remove the TCPisms. I think this function has never been used. 5307 5308SEE ALSO 5309 CSCsockConnectTCP(3) 5310 CSCsockConnectUDP(3) 5311 CSCsockPassiveTCP(3) 5312 5313 5314------------------------------------------------------------------------ 5315CSCstatStr(3) 5316 5317NAME 5318 CSCstatStr - get string describing libcsc function return value 5319 5320SYNOPSYS 5321 #include "libcsc.h" 5322 5323 const char* CSCstatStr (int status); 5324 5325DESCRIPTION 5326 Most libcsc functions return an integer status; this integer status is 5327 passed as the `status' argument to CSCstatStr(). 5328 5329 CSCstatStr() returns a pointer to a constant ASCII-Z string containing 5330 the text describing `status'. 5331 5332SEE ALSO 5333 CSCcflags(3) 5334 CSCldflags(3) 5335 CSClibs(3) 5336 CSCversion(3) 5337 CSCcredits(3) 5338 CSCchkup(3) 5339 5340 5341------------------------------------------------------------------------ 5342CSCstringBasename(3) 5343 5344NAME 5345 CSCstringBasename - strip directory from a filename 5346 5347SYNOPSYS 5348 #include "libcsc.h" 5349 5350 char* CSCstringBasename ( 5351 char** const pathPtrPtr 5352 ); 5353 5354RETURN VALUE 5355 CSCstringBinary() returns a pointer to the filename component of the 5356 pathname at *pathPtrPtr, if successful. Otherwise, CSCstringBinary() 5357 returns NULL, particularly if pathPtrPtr, or *pathPtrPtr is NULL. 5358 5359DESCRIPTION 5360 CSCstringBinary() finds the first character after the last '/' character 5361 in the pathname pointed to by *pathPtrPtr. The last '/' character in the 5362 original string is replace will a NULL character. 5363 5364 If the original pathname pointed to by *pathPtrPtr contains no '/' 5365 character, then CSCstringBinary() returns *pathPtrPtr, and sets 5366 *pathPtrPtr to be a pointer to the string "." (the current directory). 5367 5368EXAMPLE 5369 char* pathname = "just.a.file.name"; 5370 file = CSCstringBasename (&pathname); 5371 5372 // Now we have: 5373 // file = "just.a.file.name" 5374 // pathname = "." 5375 5376 char* pathname = "path/file"; 5377 file = CSCstringBasename (&pathname); 5378 5379 // Now we have: 5380 // file = "file" ----v 5381 // pathname = "path\0file" 5382 5383BUGS 5384 If the original string has a '/' character, then that character gets 5385 set to '\0'; don't try this on components of argv and other strings 5386 that might not be writable. 5387 5388SEE ALSO 5389 CSCstringOctal(3) 5390 CSCstringBinary(3) 5391 5392 5393------------------------------------------------------------------------ 5394CSCstringBinary(3) 5395 5396NAME 5397 CSCstringBinary - format an ASCII string to represent a binary number 5398 5399SYNOPSYS 5400 #include "libcsc.h" 5401 5402 char* CSCstringBinary ( 5403 char* const bufPtr, 5404 int32 item 5405 ); 5406 5407RETURN VALUE 5408 CSCstringBinary() always returns bufPtr. 5409 5410DESCRIPTION 5411 If `bufPtr' is not NULL, then the integer value of `item', in binary, is 5412 written to bufPtr with a preceding "0b" and is represented in 32 bits 5413 with the preceding two "0b" characters and terminating '\0' for a total 5414 of 35 characters. 5415 5416EXAMPLE 5417 char* buf[35]; // no smaller! and bigger is a waste. 5418 int32 i = 72; 5419 5420 (void)CSCstringBinary (buf, i); 5421 // 5422 // Now: buf = "0b0000000001001000" 5423 5424BUGS 5425 Beware buffer overflows; they are your responsibility. 5426 5427SEE ALSO 5428 CSCstringOctal(3) 5429 CSCstringBasename(3) 5430 5431 5432------------------------------------------------------------------------ 5433CSCstringOctal(3) 5434 5435NAME 5436 CSCstringOctal - format an ASCII string to represent an octal number 5437 5438SYNOPSYS 5439 #include "libcsc.h" 5440 5441 char* CSCstringOctal ( 5442 char* const bufPtr, 5443 int32 item 5444 ); 5445 5446RETURN VALUE 5447 CSCstringOctal() always returns bufPtr. 5448 5449DESCRIPTION 5450 If `bufPtr' is not NULL, then the integer value of `item', in octal, is 5451 written to bufPtr with a preceding "0o" and is represented in 11 octets 5452 with the preceding two "0o" characters and terminating '\0' for a total 5453 of 14 characters. 5454 5455EXAMPLE 5456 char* buf[14]; // no smaller! and bigger is a waste. 5457 int32 i = 72; 5458 5459 (void)CSCstringOctal (buf, i); 5460 // 5461 // Now: buf = "0o00000000110" 5462 5463BUGS 5464 Beware buffer overflows; they are your responsibility. 5465 5466SEE ALSO 5467 CSCstringBinary(3) 5468 CSCstringBasename(3) 5469 5470 5471------------------------------------------------------------------------ 5472CSCsymbolDel(3) 5473 5474NAME 5475 CSCsymbolDel - remove a libcsc symbol table 5476 5477SYNOPSYS 5478 #include "libcsc.h" 5479 5480 int CSCsymbolDel ( 5481 CSCsymbolType** const symPtrPtr, 5482 CSCmemListType const memList, 5483 int memTag 5484 ); 5485 5486RETURN VALUE 5487 CSC_OK ....... successful 5488 5489 CSC_BADARG ... symPtrPtr or memList is NULL 5490 5491 CSC_ERROR .... other errors 5492 5493DESCRIPTION 5494 CSCsymbolDel() deletes the symbol whose pointer is pointed to by 5495 `symPtrPtr'. 5496 5497 If the symbol was created by CSCsymbolFloatInit(), CSCsymbolIntInit(), 5498 CSCsymbolPtrInit(), or otherwise does not have a dynamically allocated 5499 name, then there will be some complaints (crashes? heap corruption?) 5500 when the name field is freed. 5501 5502HINT 5503 If the symbol's valueFlag field is set to 1, 2 or 3, then the name 5504 field is deallocated. If the symbol's valueFlag field is set to 3, 5505 then the value.pointer field is also deallocated. 5506 5507SEE ALSO 5508 CSCsymbolIntInit(3) 5509 CSCsymbolFloatInit(3) 5510 CSCsymbolPtrInit(3) 5511 CSCsymbolIntNew(3) 5512 CSCsymbolFloatNew(3) 5513 CSCsymbolPtrNew(3) 5514 CSCsymbolIntDel(3) 5515 CSCsymbolFloatDel(3) 5516 CSCsymbolPtrDel(3) 5517 CSCsymbolIntWrite(3) 5518 CSCsymbolFloatWrite(3) 5519 CSCsymbolPtrWrite(3) 5520 CSCsymbolDup(3) 5521 5522 5523------------------------------------------------------------------------ 5524CSCsymbolDup(3) 5525 5526NAME 5527 CSCsymbolDup - dynamically allocate and duplicate a symbol 5528 5529SYNOPSYS 5530 #include "libcsc.h" 5531 5532 CSCsymbolType* CSCsymbolDup ( 5533 const CSCsymbolType* const symPtr, 5534 CSCmemListType const memList, 5535 int memTag 5536 ); 5537 5538RETURN VALUE 5539 CSCsymbolDup(), if successful, returns a pointer to the newly created 5540 symbol, otherwise NULL is returned. 5541 5542DESCRIPTION 5543 CSCsymbolDup() dynamically allocates a symbol structure and copies the 5544 symbol pointed to by `symPtr' into the new symbol. 5545 5546 The symbol's name is also dynamically allocated and copied. To free 5547 the newly created symbol's memory, the name field and the symbol 5548 structure itself must be freed; use the appropriate CSCsymbol*Del() 5549 function. 5550 5551SEE ALSO 5552 CSCsymbolIntInit(3) 5553 CSCsymbolFloatInit(3) 5554 CSCsymbolPtrInit(3) 5555 CSCsymbolIntNew(3) 5556 CSCsymbolFloatNew(3) 5557 CSCsymbolPtrNew(3) 5558 CSCsymbolIntDel(3) 5559 CSCsymbolFloatDel(3) 5560 CSCsymbolPtrDel(3) 5561 CSCsymbolIntWrite(3) 5562 CSCsymbolFloatWrite(3) 5563 CSCsymbolPtrWrite(3) 5564 CSCsymbolDel(3) 5565 5566 5567------------------------------------------------------------------------ 5568CSCsymbolFloatDel(3) 5569 5570NAME 5571 CSCsymbolFloatDel - delete a floating point symbol 5572 5573SYNOPSYS 5574 #include "libcsc.h" 5575 5576 int CSCsymbolFloatDel ( 5577 CSCsymbolType** const symPtrPtr, 5578 CSCmemListType const memList, 5579 int memTag 5580 ); 5581 5582RETURN VALUE 5583 CSC_OK ....... successful 5584 5585 CSC_BADARG ... symPtrPtr or memList is NULL 5586 5587 CSC_ERROR .... other errors 5588 5589DESCRIPTION 5590 CSCsymbolFloatDel() removes the floating point symbol whose pointer is 5591 pointed to by `symPtrPtr'. 5592 5593BUGS 5594 The name field of the symbol structure is a character pointer and 5595 CSCsymbolFloatDel() tries to deallocate it; therefore, don't create a 5596 symbol with a statically allocated name. 5597 5598SEE ALSO 5599 CSCsymbolIntInit(3) 5600 CSCsymbolFloatInit(3) 5601 CSCsymbolPtrInit(3) 5602 CSCsymbolIntNew(3) 5603 CSCsymbolFloatNew(3) 5604 CSCsymbolPtrNew(3) 5605 CSCsymbolIntDel(3) 5606 CSCsymbolPtrDel(3) 5607 CSCsymbolIntWrite(3) 5608 CSCsymbolFloatWrite(3) 5609 CSCsymbolPtrWrite(3) 5610 CSCsymbolDup(3) 5611 CSCsymbolDel(3) 5612 5613 5614------------------------------------------------------------------------ 5615CSCsymbolFloatInit(3) 5616 5617NAME 5618 CSCsymbolFloatInit - initialize a floating point symbol 5619 5620SYNOPSYS 5621 #include "libcsc.h" 5622 5623 int CSCsymbolFloatInit ( 5624 CSCsymbolType* const symbol, 5625 const char* const symName, 5626 long symType, 5627 float symVal 5628 ); 5629 5630RETURN VALUE 5631 CSC_OK ........ successful 5632 5633 CSC_BADARG .... symbol or symName is equal to NULL 5634 5635DESCRIPTION 5636 CSCsymbolFloatInit() initializes the symbol pointed to by `symbol' with 5637 `symName', `symType', and `symVal'. Client code probably should use the 5638 same `symType' value for all floating point symbols, and `symName' 5639 probably should be the ASCII string equivalent of `symVal'. 5640 5641BUGS 5642 The pointer `symName' is copied into the symbol structure; therefore, if 5643 `symName' is subsequently freed, then the newly initialized symbol will 5644 have an aliasing error (pointer to freed memory). 5645 5646 And remember: CSCsymbolFloatDel() will try to deallocate the name, so 5647 it won't be happy if the name was not dynamically 5648 allocated. 5649 5650HINT 5651 The symbol's valueFlag field is set to 2. 5652 5653SEE ALSO 5654 CSCsymbolIntInit(3) 5655 CSCsymbolPtrInit(3) 5656 CSCsymbolIntNew(3) 5657 CSCsymbolFloatNew(3) 5658 CSCsymbolPtrNew(3) 5659 CSCsymbolIntDel(3) 5660 CSCsymbolFloatDel(3) 5661 CSCsymbolPtrDel(3) 5662 CSCsymbolIntWrite(3) 5663 CSCsymbolFloatWrite(3) 5664 CSCsymbolPtrWrite(3) 5665 CSCsymbolDup(3) 5666 CSCsymbolDel(3) 5667 5668 5669------------------------------------------------------------------------ 5670CSCsymbolFloatNew(3) 5671 5672NAME 5673 CSCsymbolFloatNew - allocate and initialize a floating point symbol 5674 5675SYNOPSYS 5676 #include "libcsc.h" 5677 5678 CSCsymbolType* CSCsymbolFloatNew ( 5679 const char* const symName, 5680 long symType, 5681 float symVal, 5682 CSCmemListType const memList, 5683 int memTag 5684 ); 5685 5686RETURN VALUE 5687 CSCsymbolFloatNew() returns a pointer to the newly allocated symbol, if 5688 successful; otherwise, NULL is returned. 5689 5690DESCRIPTION 5691 CSCsymbolFloatNew() dynamically allocates a new symbol structure and 5692 fills it in with `symName', `symType', and `symVal'. Client code 5693 probably should use the same `symType' value for all floating point 5694 symbols, and `symName' probably should be the ASCII string equivalent of 5695 `symVal'. 5696 5697HINTS 5698 Memory for the new symbol's name is allocated and `symName' is copied 5699 in to it, so client code can immediately free `symName' upon returning 5700 from CSCsymbolFloatNew(). 5701 5702 The symbol's valueFlag field is set to 2. 5703 5704SEE ALSO 5705 CSCsymbolIntInit(3) 5706 CSCsymbolFloatInit(3) 5707 CSCsymbolPtrInit(3) 5708 CSCsymbolIntNew(3) 5709 CSCsymbolPtrNew(3) 5710 CSCsymbolIntDel(3) 5711 CSCsymbolFloatDel(3) 5712 CSCsymbolPtrDel(3) 5713 CSCsymbolIntWrite(3) 5714 CSCsymbolFloatWrite(3) 5715 CSCsymbolPtrWrite(3) 5716 CSCsymbolDup(3) 5717 CSCsymbolDel(3) 5718 5719 5720------------------------------------------------------------------------ 5721CSCsymbolFloatWrite(3) 5722 5723NAME 5724 CSCsymbolFloatWrite - write a floating point symbol in ASCII format 5725 5726SYNOPSYS 5727 #include "libcsc.h" 5728 5729 int CSCsymbolFloatWrite ( 5730 const int fd, 5731 const CSCsymbolType* const symPtr 5732 ); 5733 5734RETURN VALUE 5735 CSC_OK ....... always 5736 5737DESCRIPTION 5738 CSCsymbolFloatWrite() writes to fd the fields of the symbol in an ASCII 5739 format. 5740 5741SEE ALSO 5742 CSCsymbolIntInit(3) 5743 CSCsymbolFloatInit(3) 5744 CSCsymbolPtrInit(3) 5745 CSCsymbolIntNew(3) 5746 CSCsymbolFloatNew(3) 5747 CSCsymbolPtrNew(3) 5748 CSCsymbolIntDel(3) 5749 CSCsymbolFloatDel(3) 5750 CSCsymbolPtrDel(3) 5751 CSCsymbolIntWrite(3) 5752 CSCsymbolPtrWrite(3) 5753 CSCsymbolDup(3) 5754 CSCsymbolDel(3) 5755 5756 5757------------------------------------------------------------------------ 5758CSCsymbolIntDel(3) 5759 5760NAME 5761 CSCsymbolIntDel - delete a integer symbol 5762 5763SYNOPSYS 5764 #include "libcsc.h" 5765 5766 int CSCsymbolIntDel ( 5767 CSCsymbolType** const symPtrPtr, 5768 CSCmemListType const memList, 5769 int memTag 5770 ); 5771 5772RETURN VALUE 5773 CSC_OK ....... successful 5774 5775 CSC_BADARG ... symPtrPtr or memList is NULL 5776 5777 CSC_ERROR .... other errors 5778 5779DESCRIPTION 5780 CSCsymbolIntDel() removes the integer symbol whose pointer is pointed 5781 to by `symPtrPtr'. 5782 5783BUGS 5784 The name field of the symbol structure is a character pointer and 5785 CSCsymbolIntDel() tries to deallocate it; therefore, don't create a 5786 symbol with a statically allocated name. 5787 5788SEE ALSO 5789 CSCsymbolIntInit(3) 5790 CSCsymbolFloatInit(3) 5791 CSCsymbolPtrInit(3) 5792 CSCsymbolIntNew(3) 5793 CSCsymbolFloatNew(3) 5794 CSCsymbolPtrNew(3) 5795 CSCsymbolFloatDel(3) 5796 CSCsymbolPtrDel(3) 5797 CSCsymbolIntWrite(3) 5798 CSCsymbolFloatWrite(3) 5799 CSCsymbolPtrWrite(3) 5800 CSCsymbolDup(3) 5801 CSCsymbolDel(3) 5802 5803 5804------------------------------------------------------------------------ 5805CSCsymbolIntInit(3) 5806 5807NAME 5808 CSCsymbolIntInit - initialize a integer symbol 5809 5810SYNOPSYS 5811 #include "libcsc.h" 5812 5813 int CSCsymbolIntInit ( 5814 CSCsymbolType* const symbol, 5815 const char* const symName, 5816 long symType, 5817 int symVal 5818 ); 5819 5820RETURN VALUE 5821 CSC_OK ........ successful 5822 5823 CSC_BADARG .... symbol or symName is equal to NULL 5824 5825DESCRIPTION 5826 CSCsymbolIntInit() initializes the symbol pointed to by `symbol' with 5827 `symName', `symType', and `symVal'. Client code probably should use the 5828 same `symType' value for all integer symbols, and `symName' probably 5829 should be the ASCII string equivalent of `symVal'. 5830 5831BUGS 5832 The pointer `symName' is copied into the symbol structure; therefore, if 5833 `symName' is subsequently freed, then the newly initialized symbol will 5834 have an aliasing error (pointer to freed memory). 5835 5836 And remember: CSCsymbolIntDel() will try to deallocate the name, so 5837 it won't be happy if the name was not dynamically 5838 allocated. 5839 5840HINT 5841 The symbol's valueFlag field is set to 1. 5842 5843SEE ALSO 5844 CSCsymbolFloatInit(3) 5845 CSCsymbolPtrInit(3) 5846 CSCsymbolIntNew(3) 5847 CSCsymbolFloatNew(3) 5848 CSCsymbolPtrNew(3) 5849 CSCsymbolIntDel(3) 5850 CSCsymbolFloatDel(3) 5851 CSCsymbolPtrDel(3) 5852 CSCsymbolIntWrite(3) 5853 CSCsymbolFloatWrite(3) 5854 CSCsymbolPtrWrite(3) 5855 CSCsymbolDup(3) 5856 CSCsymbolDel(3) 5857 5858 5859------------------------------------------------------------------------ 5860CSCsymbolIntNew(3) 5861 5862NAME 5863 CSCsymbolIntNew - allocate and initialize a integer symbol 5864 5865SYNOPSYS 5866 #include "libcsc.h" 5867 5868 CSCsymbolType* CSCsymbolIntNew ( 5869 const char* const symName, 5870 long symType, 5871 int symVal, 5872 CSCmemListType const memList, 5873 int memTag 5874 ); 5875 5876RETURN VALUE 5877 CSCsymbolIntNew() returns a pointer to the newly allocated symbol, if 5878 successful; otherwise, NULL is returned. 5879 5880DESCRIPTION 5881 CSCsymbolIntNew() dynamically allocates a new symbol structure and 5882 fills it in with `symName', `symType', and `symVal'. Client code 5883 probably should use the same `symType' value for all integer symbols, 5884 and `symName' probably should be the ASCII string equivalent of 5885 `symVal'. 5886 5887HINTS 5888 Memory for the new symbol's name is allocated and `symName' is copied 5889 in to it, so client code can immediately free `symName' upon returning 5890 from CSCsymbolIntNew(). 5891 5892 The symbol's valueFlag field is set to 1. 5893 5894SEE ALSO 5895 CSCsymbolIntInit(3) 5896 CSCsymbolFloatInit(3) 5897 CSCsymbolPtrInit(3) 5898 CSCsymbolFloatNew(3) 5899 CSCsymbolPtrNew(3) 5900 CSCsymbolIntDel(3) 5901 CSCsymbolFloatDel(3) 5902 CSCsymbolPtrDel(3) 5903 CSCsymbolIntWrite(3) 5904 CSCsymbolFloatWrite(3) 5905 CSCsymbolPtrWrite(3) 5906 CSCsymbolDup(3) 5907 CSCsymbolDel(3) 5908 5909 5910------------------------------------------------------------------------ 5911CSCsymbolIntWrite(3) 5912 5913NAME 5914 CSCsymbolIntWrite - write a integer symbol in ASCII format 5915 5916SYNOPSYS 5917 #include "libcsc.h" 5918 5919 int CSCsymbolIntWrite ( 5920 const int fd, 5921 const CSCsymbolType* const symPtr 5922 ); 5923 5924RETURN VALUE 5925 CSC_OK ....... always 5926 5927DESCRIPTION 5928 CSCsymbolIntWrite() writes to fd the fields of the symbol in an ASCII 5929 format. 5930 5931SEE ALSO 5932 CSCsymbolIntInit(3) 5933 CSCsymbolFloatInit(3) 5934 CSCsymbolPtrInit(3) 5935 CSCsymbolIntNew(3) 5936 CSCsymbolFloatNew(3) 5937 CSCsymbolPtrNew(3) 5938 CSCsymbolIntDel(3) 5939 CSCsymbolFloatDel(3) 5940 CSCsymbolPtrDel(3) 5941 CSCsymbolFloatWrite(3) 5942 CSCsymbolPtrWrite(3) 5943 CSCsymbolDup(3) 5944 CSCsymbolDel(3) 5945 5946 5947------------------------------------------------------------------------ 5948CSCsymbolPtrDel(3) 5949 5950NAME 5951 CSCsymbolPtrDel - delete a pointer symbol 5952 5953SYNOPSYS 5954 #include "libcsc.h" 5955 5956 int CSCsymbolPtrDel ( 5957 CSCsymbolType** const symPtrPtr, 5958 CSCmemListType const memList, 5959 int memTag 5960 ); 5961 5962RETURN VALUE 5963 CSC_OK ....... successful 5964 5965 CSC_BADARG ... symPtrPtr or memList is NULL 5966 5967 CSC_ERROR .... other errors 5968 5969DESCRIPTION 5970 CSCsymbolPtrDel() removes the pointer symbol whose pointer is pointed 5971 to by `symPtrPtr'. 5972 5973BUGS 5974 The name and value fields of the symbol structure are pointers and 5975 CSCsymbolPtrDel() tries to deallocate them; therefore, don't create a 5976 symbol with a statically allocated name or pointer. 5977 5978SEE ALSO 5979 CSCsymbolIntInit(3) 5980 CSCsymbolFloatInit(3) 5981 CSCsymbolPtrInit(3) 5982 CSCsymbolIntNew(3) 5983 CSCsymbolFloatNew(3) 5984 CSCsymbolPtrNew(3) 5985 CSCsymbolIntDel(3) 5986 CSCsymbolFloatDel(3) 5987 CSCsymbolIntWrite(3) 5988 CSCsymbolFloatWrite(3) 5989 CSCsymbolPtrWrite(3) 5990 CSCsymbolDup(3) 5991 CSCsymbolDel(3) 5992 5993 5994------------------------------------------------------------------------ 5995CSCsymbolPtrInit(3) 5996 5997NAME 5998 CSCsymbolPtrInit - initialize a pointer symbol 5999 6000SYNOPSYS 6001 #include "libcsc.h" 6002 6003 int CSCsymbolPtrInit ( 6004 CSCsymbolType* const symbol, 6005 const char* const symName, 6006 long symType, 6007 const void* symVal, 6008 size_t symValSize 6009 ); 6010 6011RETURN VALUE 6012 CSC_OK ........ successful 6013 6014 CSC_BADARG .... symbol, symName, or symVal is equal to NULL 6015 6016DESCRIPTION 6017 CSCsymbolPtrInit() initializes the symbol pointed to by `symbol' with 6018 `symName', `symType', and `symVal' for `symValSize'. Client code 6019 probably should use the same `symType' value for all pointer symbols. 6020 6021BUGS 6022 The pointers `symName' and `symval' are copied into the symbol 6023 structure; therefore, if `symName' or `symVal' is subsequently freed, 6024 then the newly initialized symbol will have an aliasing error (pointer 6025 to freed memory). 6026 6027 And remember: CSCsymbolPtrDel() will try to deallocate the name and 6028 pointer, so it won't be happy if they were not 6029 dynamically allocated. 6030 6031HINT 6032 The symbol's valueFlag field is set to 3. 6033 6034SEE ALSO 6035 CSCsymbolIntInit(3) 6036 CSCsymbolFloatInit(3) 6037 CSCsymbolIntNew(3) 6038 CSCsymbolFloatNew(3) 6039 CSCsymbolPtrNew(3) 6040 CSCsymbolIntDel(3) 6041 CSCsymbolFloatDel(3) 6042 CSCsymbolPtrDel(3) 6043 CSCsymbolIntWrite(3) 6044 CSCsymbolFloatWrite(3) 6045 CSCsymbolPtrWrite(3) 6046 CSCsymbolDup(3) 6047 CSCsymbolDel(3) 6048 6049 6050------------------------------------------------------------------------ 6051CSCsymbolPtrNew(3) 6052 6053NAME 6054 CSCsymbolPtrNew - allocate and initialize a pointer symbol 6055 6056SYNOPSYS 6057 #include "libcsc.h" 6058 6059 CSCsymbolType* CSCsymbolPtrNew ( 6060 const char* const symName, 6061 long symType, 6062 const void* symVal, 6063 size_t symValSize, 6064 CSCmemListType const memList, 6065 int memTag 6066 ); 6067 6068RETURN VALUE 6069 CSCsymbolPtrNew() returns a pointer to the newly allocated symbol, if 6070 successful; otherwise, NULL is returned. 6071 6072DESCRIPTION 6073 CSCsymbolPtrNew() dynamically allocates a new symbol structure and 6074 fills it in with `symName', `symType', and `symVal' for `symValSize'. 6075 Client code probably should use the same `symType' value for all pointer 6076 symbols. 6077 6078HINTS 6079 Memory for the new `symName' and `symval' are allocated and they are 6080 copied in to it, so client code can immediately free `symName' and 6081 `symVal' upon returning from CSCsymbolPtrNew(). 6082 6083 The symbol's valueFlag field is set to 3. 6084 6085SEE ALSO 6086 CSCsymbolIntInit(3) 6087 CSCsymbolFloatInit(3) 6088 CSCsymbolPtrInit(3) 6089 CSCsymbolIntNew(3) 6090 CSCsymbolFloatNew(3) 6091 CSCsymbolIntDel(3) 6092 CSCsymbolFloatDel(3) 6093 CSCsymbolPtrDel(3) 6094 CSCsymbolIntWrite(3) 6095 CSCsymbolFloatWrite(3) 6096 CSCsymbolPtrWrite(3) 6097 CSCsymbolDup(3) 6098 CSCsymbolDel(3) 6099 6100 6101------------------------------------------------------------------------ 6102CSCsymbolPtrWrite(3) 6103 6104NAME 6105 CSCsymbolPtrWrite - write a pointer symbol in ASCII format 6106 6107SYNOPSYS 6108 #include "libcsc.h" 6109 6110 int CSCsymbolPtrWrite ( 6111 const int fd, 6112 const CSCsymbolType* const symPtr 6113 ); 6114 6115RETURN VALUE 6116 CSC_OK ....... always 6117 6118DESCRIPTION 6119 CSCsymbolPtrWrite() writes to fd the fields of the symbol in an ASCII 6120 format. 6121 6122SEE ALSO 6123 CSCsymbolIntInit(3) 6124 CSCsymbolFloatInit(3) 6125 CSCsymbolPtrInit(3) 6126 CSCsymbolIntNew(3) 6127 CSCsymbolFloatNew(3) 6128 CSCsymbolPtrNew(3) 6129 CSCsymbolIntDel(3) 6130 CSCsymbolFloatDel(3) 6131 CSCsymbolPtrDel(3) 6132 CSCsymbolIntWrite(3) 6133 CSCsymbolFloatWrite(3) 6134 CSCsymbolDup(3) 6135 CSCsymbolDel(3) 6136 6137 6138------------------------------------------------------------------------ 6139CSCsymtabDel(3) 6140 6141NAME 6142 CSCsymtabDel - remove a libcsc symbol table 6143 6144SYNOPSYS 6145 #include "libcsc.h" 6146 6147 int CSCsymtabDel ( 6148 CSCsymTableType const symTab 6149 ); 6150 6151RETURN VALUE 6152 CSCsymtabDel(), if successful, returns CSC_OK; otherwise, 6153 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 6154 to NULL pointers, bad function arguments, and internal data errors, 6155 respectively. 6156 6157DESCRIPTION 6158 The libcsc symbol table represented by the opaque `symTab' is completely 6159 removed. 6160 6161BUGS 6162 Symbols not created by CSCsymbolFloatNew(), CSCsymbolIntNew(), and 6163 CSCsymbolPtrNew() may cause problems. (The name and value.pointer data 6164 of the symbol should be dynamically allocated, and the valueFlag field 6165 needs to be set the way CSCsymbolFloatNew(), CSCsymbolIntNew(), and 6166 CSCsymbolPtrNew() set it.) 6167 6168SEE ALSO 6169 CSCsymtabNew(3) 6170 CSCsymtabStat(3) 6171 CSCsymtabEntryPut(3) 6172 CSCsymtabEntryGet(3) 6173 CSCsymtabEntryDel(3) 6174 CSCsymtabEntryNext(3) 6175 6176 6177------------------------------------------------------------------------ 6178CSCsymtabEntryDel(3) 6179 6180NAME 6181 CSCsymtabEntryDel - remove a symbol from a libcsc symbol table 6182 6183SYNOPSYS 6184 #include "libcsc.h" 6185 6186 int CSCsymtabEntryDel ( 6187 CSCsymTableType const symTab, 6188 char* const symName 6189 ); 6190 6191RETURN VALUE 6192 CSCsymtabEntryDel(), if successful, returns CSC_OK; otherwise, 6193 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 6194 to NULL pointers, bad function arguments, and internal data errors, 6195 respectively. 6196 6197DESCRIPTION 6198 CSCsymtabEntryDel() removes the symbol entry specified by `symName' 6199 from `symTab'. The symbol in `symTab' whose name field contains 6200 `symName' is removed. 6201 6202BUGS 6203 Symbols not created by CSCsymbolFloatNew(), CSCsymbolIntNew(), and 6204 CSCsymbolPtrNew() may cause problems. (The name and value.pointer data 6205 of the symbol should be dynamically allocated, and the valueFlag field 6206 needs to be set the way CSCsymbolFloatNew(), CSCsymbolIntNew(), and 6207 CSCsymbolPtrNew() set it.) 6208 6209SEE ALSO 6210 CSCsymtabNew(3) 6211 CSCsymtabDel(3) 6212 CSCsymtabStat(3) 6213 CSCsymtabEntryPut(3) 6214 CSCsymtabEntryGet(3) 6215 CSCsymtabEntryNext(3) 6216 6217 6218------------------------------------------------------------------------ 6219CSCsymtabEntryGet(3) 6220 6221NAME 6222 CSCsymtabEntryGet - get a symbol in a libcsc symbol table 6223 6224SYNOPSYS 6225 #include "libcsc.h" 6226 6227 CSCsymbolType* CSCsymtabEntryGet ( 6228 CSCsymTableType const symTab, 6229 char* const symName, 6230 CSCmemListType const memLst 6231 ); 6232 6233RETURN VALUE 6234 CSCsymtabEntryGet(), if successful, returns a pointer to a 6235 CSCsymbolType, or NULL if otherwise unsuccessful. 6236 6237DESCRIPTION 6238 CSCsymtabEntryGet() returns a pointer to a duplicate symbol from 6239 `symTab' whose name field matches `symName'. 6240 6241 If `memLst' is not NULL the duplicated symbol is dynamically allocated 6242 with CSCmemDup(), and should be removed with CSCmemFree() (with 6243 "tagData" of zero) to avoid leaking memory. 6244 6245 If `memLst' is NULL the duplicated symbol is dynamically allocated with 6246 malloc() and should be removed with free() to avoid leaking memory. 6247 6248SEE ALSO 6249 CSCsymtabNew(3) 6250 CSCsymtabDel(3) 6251 CSCsymtabStat(3) 6252 CSCsymtabEntryPut(3) 6253 CSCsymtabEntryDel(3) 6254 CSCsymtabEntryNext(3) 6255 6256 6257------------------------------------------------------------------------ 6258CSCsymtabEntryNext(3) 6259 6260NAME 6261 CSCsymtabEntryNext - find next entry in a libcsc symbol table 6262 6263SYNOPSYS 6264 #include "libcsc.h" 6265 6266 void* CSCsymtabEntryNext ( 6267 CSCsymTableType const symTab, 6268 void* const lhPtr 6269 ); 6270 6271RETURN VALUE 6272 CSCsymtabEntryNext(), if successful, returns an opaque symbol table 6273 entry. If not successful, CSCsymtabEntryNext() returns NULL. 6274 6275DESCRIPTION 6276 CSCsymtabEntryNext() uses the libcsc symbol table specified by the 6277 opaque `symTab' and returns a pointer to the next consecutive entry 6278 following the entry pointed to by `lhPtr'. This next consecutive entry 6279 is the entry physically following the entry pointed to by `lhPtr'. 6280 6281 If `lhPtr' is NULL, then the first item in the table is returned. 6282 6283 If `symTab' is a table with no entries, or there are no more entries 6284 following the entry pointed to by `lhPtr', then NULL is returned. 6285 6286BUGS 6287 There is no legitimate way for client code to know what to do with the 6288 void pointer returned from this function. The secret is the returned 6289 value is a CSChashEntryType with its dataPtr field being a pointer to 6290 the symbol, but that might (very much not likely) change. 6291 6292SEE ALSO 6293 CSCsymtabNew(3) 6294 CSCsymtabDel(3) 6295 CSCsymtabStat(3) 6296 CSCsymtabEntryPut(3) 6297 CSCsymtabEntryGet(3) 6298 CSCsymtabEntryDel(3) 6299 6300 6301------------------------------------------------------------------------ 6302CSCsymtabEntryPut(3) 6303 6304NAME 6305 CSCsymtabEntryPut - add a symbol to a libcsc symbol table 6306 6307SYNOPSYS 6308 #include "libcsc.h" 6309 6310 int CSCsymtabEntryPut ( 6311 CSCsymTableType const symTab, 6312 CSCsymbolType* const symbol 6313 ); 6314 6315RETURN VALUE 6316 CSCsymtabEntryPut(), if successful, returns CSC_OK; otherwise, 6317 CSC_NOTFOUND, CSC_BADARG, and CSC_CORRUPT can be returned corresponding 6318 to NULL pointers, bad function arguments, and internal data errors, 6319 respectively. 6320 6321DESCRIPTION 6322 CSCsymtabEntryPut() puts `symbol' into the symbol table specified by 6323 `symTab'. 6324 6325 NOTE Its best to put only symbols created by CSCsymbolFloatNew(), 6326 CSCsymbolIntNew(), and CSCsymbolPtrNew() because the symbol 6327 table delete functions expect the symbols to be created the 6328 way these function do, with the name and value.pointer data 6329 being dynamically allocated, and the valueFlag field being 6330 correctly set. 6331 6332SEE ALSO 6333 CSCsymtabNew(3) 6334 CSCsymtabDel(3) 6335 CSCsymtabStat(3) 6336 CSCsymtabEntryGet(3) 6337 CSCsymtabEntryDel(3) 6338 CSCsymtabEntryNext(3) 6339 6340 6341------------------------------------------------------------------------ 6342CSCsymtabNew(3) 6343 6344NAME 6345 CSCsymtabNew - create a new libcsc hash table 6346 6347SYNOPSYS 6348 #include "libcsc.h" 6349 6350 CSCsymTableType CSCsymtabNew ( 6351 const char* const name, 6352 size_t size, 6353 const char** keyWords, 6354 int keyWordSpec, 6355 CSCmonFnType monFunc, 6356 const void* monData, 6357 CSCprofileType profiling 6358 ); 6359 6360RETURN VALUE 6361 CSCsymtabNew(), if successful, returns an opaque data type 6362 representing a new libcsc symbol table, or NULL if otherwise not 6363 successful. 6364 6365DESCRIPTION 6366 CSCsymtabNew() creates a new libcsc symbol table of `size' entries, and 6367 initialized with a set of keywords. 6368 6369 `name' points to an arbitrary string that is used as the name of the 6370 new libcsc symbol table. 6371 6372 If `size' is zero, then a default size is used. Since the symbol table 6373 is implemented as a hash table, the number of entries can be larger 6374 than size. 6375 6376 If `keyWords' is NULL, then no keywords are loaded. Otherwise, keyWords 6377 is an array of character pointers; a symbol is created and put into the 6378 new table for each keyword. A list of keywords is terminated by a 6379 keyword of zero length, not a NULL keyword pointer. 6380 6381 `keyWordType' is the value used for the keyword symbols' type field. 6382 6383SEE ALSO 6384 CSCsymtabDel(3) 6385 CSCsymtabStat(3) 6386 CSCsymtabEntryPut(3) 6387 CSCsymtabEntryGet(3) 6388 CSCsymtabEntryDel(3) 6389 CSCsymtabEntryNext(3) 6390 6391 6392------------------------------------------------------------------------ 6393CSCsymtabStat(3) 6394 6395NAME 6396 CSCsymtabStat - retrieve statistics for a libcsc symbol table 6397 6398SYNOPSYS 6399 #include "libcsc.h" 6400 6401 int CSCsymtabStat ( 6402 CSCsymTableType const symTab, 6403 size_t* const sizePtr 6404 ); 6405 6406RETURN VALUE 6407 CSCsymtabStat(), if successful, returns RTS_OK; otherwise, 6408 RTS_NOTFOUND, RTS_BADARG, and RTS_ERROR can be returned corresponding 6409 to NULL pointers, bad function arguments, and internal data errors, 6410 respectively. 6411 6412DESCRIPTION 6413 CSCsymtabStat() queries the libcsc symbol table specified by the 6414 opaque `symTab'. 6415 6416 If `sizePtr' is not NULL, then the count of symbols in `symTab' is 6417 written to the size_t that is pointed to by `sizePtr'. 6418 6419SEE ALSO 6420 CSCsymtabNew(3) 6421 CSCsymtabDel(3) 6422 CSCsymtabEntryPut(3) 6423 CSCsymtabEntryGet(3) 6424 CSCsymtabEntryDel(3) 6425 CSCsymtabEntryNext(3) 6426 6427 6428------------------------------------------------------------------------ 6429CSCsysInstallSignal(3) 6430 6431NAME 6432 CSCsysInstallSignal - fairly portable signal installer 6433 6434SYNOPSYS 6435 #include "libcsc.h" 6436 6437 CSCsigFnType CSCsysInstallSignal ( 6438 const int signo, 6439 const CSCsigFnType func, 6440 const CSCsigModeType mode 6441 ); 6442 6443RETURN VALUE 6444 The return value from CSCsysInstallSignal() is a function pointer to a 6445 signal handler. 6446 6447 If CSCsysInstallSignal() is NOT successful, then the return value is 6448 SIG_ERR cast as a signal handler function. 6449 6450 If CSCsysInstallSignal() is successful, then the return value is a 6451 function pointer to the previously installed handler cast as a 6452 signal handler function; this might be NULL in the typical case that 6453 there was no previous signal handler. 6454 6455DESCRIPTION 6456 CSCsysInstallSignal() is a reliable version of signal() using POSIX 6457 sigaction(). 6458 6459 `signo' is the signal number of the signal for which the signal handler 6460 function `func' is installed. 6461 6462 `mode' is CSC_SIG_INTERRUPT or CSC_SIG_RESTART; it is used to control 6463 behavior, specifically for slow system calls: 6464 6465 mode behavior 6466 ---- -------- 6467 CSC_SIG_INTERRUPT slow system calls are interrupted 6468 6469 CSC_SIG_RESTART slow system calls are not interrupted 6470 6471 An illustration of slow system call and signal interrupt is a program 6472 that creates children and has a signal handler for SIGCHLD. If this 6473 program blocks on something like an accept() on a TCP socket connection 6474 and a child process terminates, then the registered SIGCHLD signal 6475 handler runs; but, the process unblocks and returns from the accept() 6476 with no connection (errno should be EINTR). This can be avoided by 6477 using CSCsysInstallSignal() to install the SIGCHLD signal handler 6478 function `func' and specifying CSC_SIG_RESTART for `mode'. 6479 6480SEE ALSO 6481 CSCsysLimitsGet(3) 6482 CSCsysUsleep(3) 6483 6484 6485------------------------------------------------------------------------ 6486CSCsysLimitsGet(3) 6487 6488NAME 6489 CSCsysLimitsGet - find some system limits 6490 6491SYNOPSYS 6492 #include "libcsc.h" 6493 6494 int CSCsysLimitsGet ( 6495 int* const fileOpenMaxPtr, 6496 int* const fileNameLengthPtr, 6497 int* const filePathLengthPtr 6498 ); 6499 6500RETURN VALUE 6501 RTS_OK ........ successful 6502 6503 CSC_BADARG .... fileOpenMaxPtr, or fileNameLengthPtr, or 6504 filePathLengthPtr is NULL 6505 6506 CSC_ERROR ..... error getting limit from system call 6507 6508DESCRIPTION 6509 CSCsysLimitsGet() makes some system calls and writes the integer 6510 information to the addresses specified in the arguments. 6511 6512 `fileOpenMaxPtr' must be a non-NULL pointer to an integer. If the call 6513 to CSCsysLimitsGet() is successful, the integer value will be the 6514 maximum number of open files allowed per process. 6515 6516 `fileNameLenghtPtr' must be a non-NULL pointer to an integer. If the 6517 call to CSCsysLimitsGet() is successful, the integer value will be the 6518 maximum files name length allowed by the system. 6519 6520 `filePathLengthPtr' must be a non-NULL pointer to an integer. If the 6521 call to CSCsysLimitsGet() is successful, the integer value will be the 6522 maximum path length allowed by the system. 6523 6524SEE ALSO 6525 CSCsysInstallSignal(3) 6526 CSCsysUsleep(3) 6527 6528 6529------------------------------------------------------------------------ 6530CSCsysUsleep(3) 6531 6532NAME 6533 CSCsysUsleep - sleep some microseconds (rounded to kernel capability) 6534 6535SYNOPSYS 6536 #include "libcsc.h" 6537 6538 void CSCsysUsleep ( 6539 const size_t microseconds 6540 ); 6541 6542RETURN VALUE 6543 CSCsysUsleep() has no return value. 6544 6545DESCRIPTION 6546 The calling process/task will block for microseconds. The actual time 6547 blocked will be descretized to the granularity implemented by the 6548 kernel. 6549 6550SEE ALSO 6551 CSCsysInstallSignal(3) 6552 CSCsysLimitsGet(3) 6553 6554 6555------------------------------------------------------------------------ 6556CSCtimerClear(3) 6557 6558NAME 6559 CSCtimerClear - clear marks in timer 6560 6561SYNOPSYS 6562 #include "libcsc.h" 6563 6564 int CSCtimerClear ( 6565 CSCtimerType const timer 6566 ); 6567 6568RETURN VALUE 6569 CSC_OK ........ successful 6570 6571 CSC_BADARG .... timer is NULL 6572 6573 CSC_CORRUPT ... corruption is detected in timer 6574 and CSCtimerClear() is compiled with DEBUG 6575 6576DESCRIPTION 6577 CSCtimerClear() clears marks (and all the stats) in `timer'. 6578 6579SEE ALSO 6580 PRtimerInit(3) 6581 PRtimerDone(3) 6582 PRtimerMark(3) 6583 PRtimerDiff(3) 6584 PRtimerStat(3) 6585 6586 6587------------------------------------------------------------------------ 6588CSCtimerDiff(3) 6589 6590NAME 6591 CSCtimerStat - create and get current timer's time 6592 6593SYNOPSYS 6594 #include "libcsc.h" 6595 6596 int CSCtimerDiff ( 6597 CSCtimerType const timer, 6598 double* const diffPtr 6599 ); 6600 6601RETURN VALUE 6602 CSC_OK ........ successful 6603 6604 CSC_ERROR ..... an error occurs trying to get system time or there was 6605 no previous call to PRtimerMark() with the timer 6606 6607 CSC_BADARG .... timer is NULL 6608 6609 CSC_CORRUPT ... corruption is detected in timer 6610 and CSCtimerDiff() is compiled with DEBUG 6611 6612DESCRIPTION 6613 CSCtimerDiff() creates a time from the caller's previous call to 6614 CSCtimerMark() with `timer' and the call to this function. The 6615 difference is stored in a double as seconds. 6616 6617 A previous call to PRtimerMark() must have been made with `timer'. 6618 6619 If the `diffPtr' argument is not NULL, then CSCtimerDiff() writes to 6620 the double pointed to by `diffPtr' the difference between the marks 6621 taken with `timer'. 6622 6623SEE ALSO 6624 PRtimerInit(3) 6625 PRtimerDone(3) 6626 PRtimerClear(3) 6627 PRtimerMark(3) 6628 PRtimerStat(3) 6629 6630 6631------------------------------------------------------------------------ 6632CSCtimerDone(3) 6633 6634NAME 6635 CSCtimerDone - delete a timer 6636 6637SYNOPSYS 6638 #include "libcsc.h" 6639 6640 int CSCtimerDone ( 6641 CSCtimerType const timer 6642 ); 6643 6644RETURN VALUE 6645 CSC_OK ........ successful 6646 6647 CSC_BADARG .... timer is NULL 6648 6649 CSC_CORRUPT ... corruption is detected in timer 6650 and CSCtimerDone() is compiled with DEBUG 6651 6652DESCRIPTION 6653 CSCtimerDone() completely removes `timer'. 6654 6655 Do not try to use `timer' again. At least until it is reset by assigning 6656 it the results of a subsequent call to PRtimerInit(); 6657 6658SEE ALSO 6659 PRtimerInit(3) 6660 PRtimerClear(3) 6661 PRtimerMark(3) 6662 PRtimerDiff(3) 6663 PRtimerStat(3) 6664 6665 6666------------------------------------------------------------------------ 6667CSCtimerInit(3) 6668 6669NAME 6670 CSCtimerInit - create a timer 6671 6672SYNOPSYS 6673 #include "libcsc.h" 6674 6675 CSCtimerType CSCtimerInit (void) 6676 6677RETURN VALUE 6678 CSCtimerInit() returns a new timer. 6679 6680DESCRIPTION 6681 CSCtimerInit() creates timer for the caller's subsequent calls to 6682 CSCtimerMark() and CSCtimerDiff(). 6683 6684SEE ALSO 6685 PRtimerDone(3) 6686 PRtimerClear(3) 6687 PRtimerMark(3) 6688 PRtimerDiff(3) 6689 PRtimerStat(3) 6690 6691 6692------------------------------------------------------------------------ 6693CSCtimerMark(3) 6694 6695NAME 6696 CSCtimerMark - create a mark in a timer 6697 6698SYNOPSYS 6699 #include "libcsc.h" 6700 6701 int CSCtimerMark ( 6702 CSCtimerType const timer 6703 ); 6704 6705RETURN VALUE 6706 CSC_OK ........ successful 6707 6708 CSC_ERROR ..... an error occurs trying to get system time 6709 6710 CSC_BADARG .... timer is NULL 6711 6712 CSC_CORRUPT ... corruption is detected in timer 6713 and CSCtimerMark() is compiled with DEBUG 6714 6715DESCRIPTION 6716 CSCtimerMark() creates a mark in `timer' for the caller's subsequent 6717 call to CSCtimerDiff() with `timer'. 6718 6719 Given the some `timer', CSCtimerDiff() will create the time value of 6720 the number of seconds that passed since the call to this function 6721 CSCtimerMark(). 6722 6723SEE ALSO 6724 PRtimerInit(3) 6725 PRtimerDone(3) 6726 PRtimerClear(3) 6727 PRtimerDiff(3) 6728 PRtimerStat(3) 6729 6730 6731------------------------------------------------------------------------ 6732CSCtimerStat(3) 6733 6734NAME 6735 CSCtimerStat - get current timer's time 6736 6737SYNOPSYS 6738 #include "libcsc.h" 6739 6740 int CSCtimerStat ( 6741 CSCtimerType const timer, 6742 double* const diffPtr 6743 ); 6744 6745RETURN VALUE 6746 CSC_OK ........ successful 6747 6748 CSC_ERROR ..... at least one of the two marks has not been taken with 6749 timer 6750 6751 CSC_BADARG .... timer is NULL 6752 6753 CSC_CORRUPT ... corruption is detected in timer 6754 and CSCtimerStat() is compiled with DEBUG 6755 6756DESCRIPTION 6757 CSCtimerStat() writes to the double pointed to by `diffPtr' the 6758 difference between the marks taken with `timer'. The difference is in 6759 seconds. 6760 6761 Marks are taken with `timer' by using functions CSCtimerMark() and 6762 CSCtimerDiff(). The difference in seconds between CSCtimerMark() and 6763 CSCtimerDiff() is kept in `timer' as a double. 6764 6765 The `timer's difference between marks is created by CSCtimerDiff(); 6766 CSCtimerStat() merely returns the saved value. 6767 6768SEE ALSO 6769 PRtimerInit(3) 6770 PRtimerDone(3) 6771 PRtimerClear(3) 6772 PRtimerMark(3) 6773 PRtimerDiff(3) 6774 6775 6776------------------------------------------------------------------------ 6777CSCurand(3) 6778 6779NAME 6780 CSCurand - uniform random number generator 6781 6782SYNOPSYS 6783 #include "libcsc.h" 6784 6785 int CSCurand ( 6786 int y, 6787 double* dptr 6788 ); 6789 6790RETURN VALUE 6791 urand() returns a random int. 6792 6793DESCRIPTION 6794 Urand is a Uniform/Universal RANDom number generator. 6795 6796 The integer argument y should be initialized to some arbitrary non-zero 6797 number prior to the first call to CSCurand. 6798 6799 Function CSCurand takes the form: f(x) = a(x) + c(modulo m) 6800 6801 m is 2 to the power of t for t-bit integers. X, a, and c are 6802 themselves integers in the same range. Some choices of a and c are 6803 good; urand chooses values suggested by Knuth (1969). The scale factor 6804 that is used for converting y to a floating point value in the interval 6805 (0,1) is s = (double) 0.5 / halfm. 6806 6807 CSCurand is taken from George E. Forsythe, Michael A. Malcolm, and Cleve 6808 B. Moler, "Computer Methods for Mathematical Programming" (Englewood 6809 Cliffs: Prentice Hall, 1977), 246. 6810 6811 CSCurand is based on theory and suggestions given in Donald E. Knuth 6812 "Seminumerical Algorithms," The Art of Computer Programming, vol. 2 6813 (Reading Mass.: Addison-Wesley 1969). 6814 6815BUGS 6816 Using CSCurand() always seems too difficult. 6817 6818SEE ALSO 6819 CSC2x(3) 6820 6821 6822------------------------------------------------------------------------ 6823CSCversion(3) 6824 6825NAME 6826 CSCversion - get string containing the libcsc version 6827 6828SYNOPSYS 6829 #include "libcsc.h" 6830 6831 const char* CSCversion (void); 6832 6833DESCRIPTION 6834 CSCversion() returns a pointer to a constant ASCII-Z string containing 6835 the libcsc version. 6836 6837SEE ALSO 6838 CSCstatStr(3) 6839 CSCcflags(3) 6840 CSCldflags(3) 6841 CSClibs(3) 6842 CSCcredits(3) 6843 CSCchkup(3) 6844 6845 6846 6847 6848 ------------------------------------------------ 6849 6850 6851 6852 6853APPENDIX C LICENSE 6854======================= 6855 6856 6857 GNU Free Documentation License 6858 Version 1.1, March 2000 6859 6860Copyright (C) 2000 Free Software Foundation, Inc. 6861 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 6862Everyone is permitted to copy and distribute verbatim copies 6863of this license document, but changing it is not allowed. 6864 68650. PREAMBLE 6866 6867The purpose of this License is to make a manual, textbook, or other written 6868document "free" in the sense of freedom: to assure everyone the effective 6869freedom to copy and redistribute it, with or without modifying it, either 6870commercially or noncommercially. Secondarily, this License preserves for the 6871author and publisher a way to get credit for their work, while not being 6872considered responsible for modifications made by others. 6873 6874This License is a kind of "copyleft", which means that derivative works of 6875the document must themselves be free in the same sense. It complements the 6876GNU General Public License, which is a copyleft license designed for free 6877software. 6878 6879We have designed this License in order to use it for manuals for free 6880software, because free software needs free documentation: a free program 6881should come with manuals providing the same freedoms that the software does. 6882But this License is not limited to software manuals; it can be used for any 6883textual work, regardless of subject matter or whether it is published as a 6884printed book. We recommend this License principally for works whose purpose 6885is instruction or reference. 6886 68871. APPLICABILITY AND DEFINITIONS 6888 6889This License applies to any manual or other work that contains a notice 6890placed by the copyright holder saying it can be distributed under the terms 6891of this License. The "Document", below, refers to any such manual or work. 6892Any member of the public is a licensee, and is addressed as "you". 6893 6894A "Modified Version" of the Document means any work containing the Document 6895or a portion of it, either copied verbatim, or with modifications and/or 6896translated into another language. 6897 6898A "Secondary Section" is a named appendix or a front-matter section of the 6899Document that deals exclusively with the relationship of the publishers or 6900authors of the Document to the Document's overall subject (or to related 6901matters) and contains nothing that could fall directly within that overall 6902subject. (For example, if the Document is in part a textbook of mathematics, 6903a Secondary Section may not explain any mathematics.) The relationship could 6904be a matter of historical connection with the subject or with related 6905matters, or of legal, commercial, philosophical, ethical or political 6906position regarding them. 6907 6908The "Invariant Sections" are certain Secondary Sections whose titles are 6909designated, as being those of Invariant Sections, in the notice that says 6910that the Document is released under this License. 6911 6912The "Cover Texts" are certain short passages of text that are listed, as 6913Front-Cover Texts or Back-Cover Texts, in the notice that says that the 6914Document is released under this License. 6915 6916A "Transparent" copy of the Document means a machine-readable copy, 6917represented in a format whose specification is available to the general 6918public, whose contents can be viewed and edited directly and 6919straightforwardly with generic text editors or (for images composed of 6920pixels) generic paint programs or (for drawings) some widely available 6921drawing editor, and that is suitable for input to text formatters or for 6922automatic translation to a variety of formats suitable for input to text 6923formatters. A copy made in an otherwise Transparent file format whose markup 6924has been designed to thwart or discourage subsequent modification by readers 6925is not Transparent. A copy that is not "Transparent" is called "Opaque". 6926 6927Examples of suitable formats for Transparent copies include plain ASCII 6928without markup, Texinfo input format, LaTeX input format, SGML or XML using 6929a publicly available DTD, and standard-conforming simple HTML designed for 6930human modification. Opaque formats include PostScript, PDF, proprietary 6931formats that can be read and edited only by proprietary word processors, 6932SGML or XML for which the DTD and/or processing tools are not generally 6933available, and the machine-generated HTML produced by some word processors 6934for output purposes only. 6935 6936The "Title Page" means, for a printed book, the title page itself, plus such 6937following pages as are needed to hold, legibly, the material this License 6938requires to appear in the title page. For works in formats which do not have 6939any title page as such, "Title Page" means the text near the most prominent 6940appearance of the work's title, preceding the beginning of the body of the 6941text. 6942 69432. VERBATIM COPYING 6944 6945You may copy and distribute the Document in any medium, either commercially 6946or noncommercially, provided that this License, the copyright notices, and 6947the license notice saying this License applies to the Document are 6948reproduced in all copies, and that you add no other conditions whatsoever to 6949those of this License. You may not use technical measures to obstruct or 6950control the reading or further copying of the copies you make or distribute. 6951However, you may accept compensation in exchange for copies. If you 6952distribute a large enough number of copies you must also follow the 6953conditions in section 3. 6954 6955You may also lend copies, under the same conditions stated above, and you 6956may publicly display copies. 6957 69583. COPYING IN QUANTITY 6959 6960If you publish printed copies of the Document numbering more than 100, and 6961the Document's license notice requires Cover Texts, you must enclose the 6962copies in covers that carry, clearly and legibly, all these Cover Texts: 6963Front-Cover Texts on the front cover, and Back-Cover Texts on the back 6964cover. Both covers must also clearly and legibly identify you as the 6965publisher of these copies. The front cover must present the full title with 6966all words of the title equally prominent and visible. You may add other 6967material on the covers in addition. Copying with changes limited to the 6968covers, as long as they preserve the title of the Document and satisfy these 6969conditions, can be treated as verbatim copying in other respects. 6970 6971If the required texts for either cover are too voluminous to fit legibly, 6972you should put the first ones listed (as many as fit reasonably) on the 6973actual cover, and continue the rest onto adjacent pages. 6974 6975If you publish or distribute Opaque copies of the Document numbering more 6976than 100, you must either include a machine-readable Transparent copy along 6977with each Opaque copy, or state in or with each Opaque copy a 6978publicly-accessible computer-network location containing a complete 6979Transparent copy of the Document, free of added material, which the general 6980network-using public has access to download anonymously at no charge using 6981public-standard network protocols. If you use the latter option, you must 6982take reasonably prudent steps, when you begin distribution of Opaque copies 6983in quantity, to ensure that this Transparent copy will remain thus 6984accessible at the stated location until at least one year after the last 6985time you distribute an Opaque copy (directly or through your agents or 6986retailers) of that edition to the public. 6987 6988It is requested, but not required, that you contact the authors of the 6989Document well before redistributing any large number of copies, to give them 6990a chance to provide you with an updated version of the Document. 6991 69924. MODIFICATIONS 6993 6994You may copy and distribute a Modified Version of the Document under the 6995conditions of sections 2 and 3 above, provided that you release the Modified 6996Version under precisely this License, with the Modified Version filling the 6997role of the Document, thus licensing distribution and modification of the 6998Modified Version to whoever possesses a copy of it. In addition, you must do 6999these things in the Modified Version: 7000 7001 * A. Use in the Title Page (and on the covers, if any) a title distinct 7002 from that of the Document, and from those of previous versions (which 7003 should, if there were any, be listed in the History section of the 7004 Document). You may use the same title as a previous version if the 7005 original publisher of that version gives permission. 7006 * B. List on the Title Page, as authors, one or more persons or entities 7007 responsible for authorship of the modifications in the Modified 7008 Version, together with at least five of the principal authors of the 7009 Document (all of its principal authors, if it has less than five). 7010 * C. State on the Title page the name of the publisher of the Modified 7011 Version, as the publisher. 7012 * D. Preserve all the copyright notices of the Document. 7013 * E. Add an appropriate copyright notice for your modifications adjacent 7014 to the other copyright notices. 7015 * F. Include, immediately after the copyright notices, a license notice 7016 giving the public permission to use the Modified Version under the 7017 terms of this License, in the form shown in the Addendum below. 7018 * G. Preserve in that license notice the full lists of Invariant Sections 7019 and required Cover Texts given in the Document's license notice. 7020 * H. Include an unaltered copy of this License. 7021 * I. Preserve the section entitled "History", and its title, and add to 7022 it an item stating at least the title, year, new authors, and publisher 7023 of the Modified Version as given on the Title Page. If there is no 7024 section entitled "History" in the Document, create one stating the 7025 title, year, authors, and publisher of the Document as given on its 7026 Title Page, then add an item describing the Modified Version as stated 7027 in the previous sentence. 7028 * J. Preserve the network location, if any, given in the Document for 7029 public access to a Transparent copy of the Document, and likewise the 7030 network locations given in the Document for previous versions it was 7031 based on. These may be placed in the "History" section. You may omit a 7032 network location for a work that was published at least four years 7033 before the Document itself, or if the original publisher of the version 7034 it refers to gives permission. 7035 * K. In any section entitled "Acknowledgements" or "Dedications", 7036 preserve the section's title, and preserve in the section all the 7037 substance and tone of each of the contributor acknowledgements and/or 7038 dedications given therein. 7039 * L. Preserve all the Invariant Sections of the Document, unaltered in 7040 their text and in their titles. Section numbers or the equivalent are 7041 not considered part of the section titles. 7042 * M. Delete any section entitled "Endorsements". Such a section may not 7043 be included in the Modified Version. 7044 * N. Do not retitle any existing section as "Endorsements" or to conflict 7045 in title with any Invariant Section. 7046 7047If the Modified Version includes new front-matter sections or appendices 7048that qualify as Secondary Sections and contain no material copied from the 7049Document, you may at your option designate some or all of these sections as 7050invariant. To do this, add their titles to the list of Invariant Sections in 7051the Modified Version's license notice. These titles must be distinct from 7052any other section titles. 7053 7054You may add a section entitled "Endorsements", provided it contains nothing 7055but endorsements of your Modified Version by various parties--for example, 7056statements of peer review or that the text has been approved by an 7057organization as the authoritative definition of a standard. 7058 7059You may add a passage of up to five words as a Front-Cover Text, and a 7060passage of up to 25 words as a Back-Cover Text, to the end of the list of 7061Cover Texts in the Modified Version. Only one passage of Front-Cover Text 7062and one of Back-Cover Text may be added by (or through arrangements made by) 7063any one entity. If the Document already includes a cover text for the same 7064cover, previously added by you or by arrangement made by the same entity you 7065are acting on behalf of, you may not add another; but you may replace the 7066old one, on explicit permission from the previous publisher that added the 7067old one. 7068 7069The author(s) and publisher(s) of the Document do not by this License give 7070permission to use their names for publicity for or to assert or imply 7071endorsement of any Modified Version. 7072 70735. COMBINING DOCUMENTS 7074 7075You may combine the Document with other documents released under this 7076License, under the terms defined in section 4 above for modified versions, 7077provided that you include in the combination all of the Invariant Sections 7078of all of the original documents, unmodified, and list them all as Invariant 7079Sections of your combined work in its license notice. 7080 7081The combined work need only contain one copy of this License, and multiple 7082identical Invariant Sections may be replaced with a single copy. If there 7083are multiple Invariant Sections with the same name but different contents, 7084make the title of each such section unique by adding at the end of it, in 7085parentheses, the name of the original author or publisher of that section if 7086known, or else a unique number. Make the same adjustment to the section 7087titles in the list of Invariant Sections in the license notice of the 7088combined work. 7089 7090In the combination, you must combine any sections entitled "History" in the 7091various original documents, forming one section entitled "History"; likewise 7092combine any sections entitled "Acknowledgements", and any sections entitled 7093"Dedications". You must delete all sections entitled "Endorsements." 7094 70956. COLLECTIONS OF DOCUMENTS 7096 7097You may make a collection consisting of the Document and other documents 7098released under this License, and replace the individual copies of this 7099License in the various documents with a single copy that is included in the 7100collection, provided that you follow the rules of this License for verbatim 7101copying of each of the documents in all other respects. 7102 7103You may extract a single document from such a collection, and distribute it 7104individually under this License, provided you insert a copy of this License 7105into the extracted document, and follow this License in all other respects 7106regarding verbatim copying of that document. 7107 71087. AGGREGATION WITH INDEPENDENT WORKS 7109 7110A compilation of the Document or its derivatives with other separate and 7111independent documents or works, in or on a volume of a storage or 7112distribution medium, does not as a whole count as a Modified Version of the 7113Document, provided no compilation copyright is claimed for the compilation. 7114Such a compilation is called an "aggregate", and this License does not apply 7115to the other self-contained works thus compiled with the Document, on 7116account of their being thus compiled, if they are not themselves derivative 7117works of the Document. If the Cover Text requirement of section 3 is 7118applicable to these copies of the Document, then if the Document is less 7119than one quarter of the entire aggregate, the Document's Cover Texts may be 7120placed on covers that surround only the Document within the aggregate. 7121Otherwise they must appear on covers around the whole aggregate. 7122 71238. TRANSLATION 7124 7125Translation is considered a kind of modification, so you may distribute 7126translations of the Document under the terms of section 4. Replacing 7127Invariant Sections with translations requires special permission from their 7128copyright holders, but you may include translations of some or all Invariant 7129Sections in addition to the original versions of these Invariant Sections. 7130You may include a translation of this License provided that you also include 7131the original English version of this License. In case of a disagreement 7132between the translation and the original English version of this License, 7133the original English version will prevail. 7134 71359. TERMINATION 7136 7137You may not copy, modify, sublicense, or distribute the Document except as 7138expressly provided for under this License. Any other attempt to copy, 7139modify, sublicense or distribute the Document is void, and will 7140automatically terminate your rights under this License. However, parties who 7141have received copies, or rights, from you under this License will not have 7142their licenses terminated so long as such parties remain in full compliance. 7143 714410. FUTURE REVISIONS OF THIS LICENSE 7145 7146The Free Software Foundation may publish new, revised versions of the GNU 7147Free Documentation License from time to time. Such new versions will be 7148similar in spirit to the present version, but may differ in detail to 7149address new problems or concerns. See http://www.gnu.org/copyleft/. 7150 7151Each version of the License is given a distinguishing version number. If the 7152Document specifies that a particular numbered version of this License "or 7153any later version" applies to it, you have the option of following the terms 7154and conditions either of that specified version or of any later version that 7155has been published (not as a draft) by the Free Software Foundation. If the 7156Document does not specify a version number of this License, you may choose 7157any version ever published (not as a draft) by the Free Software Foundation. 7158 7159How to use this License for your documents 7160 7161To use this License in a document you have written, include a copy of the 7162License in the document and put the following copyright and license notices 7163just after the title page: 7164 7165 Copyright (c) YEAR YOUR NAME. 7166 Permission is granted to copy, distribute and/or modify this document 7167 under the terms of the GNU Free Documentation License, Version 1.1 7168 or any later version published by the Free Software Foundation; 7169 with the Invariant Sections being LIST THEIR TITLES, with the 7170 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 7171 A copy of the license is included in the section entitled "GNU 7172 Free Documentation License". 7173 7174If you have no Invariant Sections, write "with no Invariant Sections" 7175instead of saying which ones are invariant. If you have no Front-Cover 7176Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being 7177LIST"; likewise for Back-Cover Texts. 7178 7179If your document contains nontrivial examples of program code, we recommend 7180releasing these examples in parallel under your choice of free software 7181license, such as the GNU General Public License, to permit their use in free 7182software. 7183