Emeric Vigier | 2f62582 | 2012-08-06 11:09:52 -0400 | [diff] [blame] | 1 | This is /home/dyfet/software/commoncpp2/doc/commoncpp2.info, produced |
| 2 | by makeinfo version 4.8 from |
| 3 | /home/dyfet/software/commoncpp2/doc/commoncpp2.texi. |
| 4 | |
| 5 | INFO-DIR-SECTION Development |
| 6 | START-INFO-DIR-ENTRY |
| 7 | * GNU Common C++ 2: (commoncpp2). GNU Common C++ 2 Framework Documentation. |
| 8 | END-INFO-DIR-ENTRY |
| 9 | |
| 10 | GNU Common C++ 2 is the second major release of a C++ framework |
| 11 | offering portable support for threading, sockets, file access, daemons, |
| 12 | persistence, serial I/O, XML parsing, and system services, initially |
| 13 | started by David Sugar and Daniel Silverstone. |
| 14 | |
| 15 | Copyright (C) 1999, 2000, 2001, 2002 Open Source Telecom Corporation. |
| 16 | Permission is granted to copy, distribute and/or modify this document |
| 17 | under the terms of the GNU Free Documentation License, Version 1.2 or |
| 18 | any later version published by the Free Software Foundation; with no |
| 19 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A |
| 20 | copy of the license is included in the section entitled "GNU Free |
| 21 | Documentation License". |
| 22 | |
| 23 | |
| 24 | File: commoncpp2.info, Node: Top, Next: Introduction, Up: (dir) |
| 25 | |
| 26 | GNU Common C++ 2 |
| 27 | **************** |
| 28 | |
| 29 | This document describes GNU Common C++ 2, the second major release of a |
| 30 | C++ framework offering portable support for threading, sockets, file |
| 31 | access, daemons, persistence, serial I/O, XML parsing, and system |
| 32 | services, initially started by David Sugar and Daniel Silverstone. |
| 33 | |
| 34 | This is the edition 1.0pre0 of this manual and documents GNU Common |
| 35 | C++ 2 version 1.0. |
| 36 | |
| 37 | * Menu: |
| 38 | |
| 39 | * Introduction:: What GNU Common C++ and this manual are. |
| 40 | * Distribution:: How to get GNU Common C++. |
| 41 | * Framework Description:: GNU Common C++ classes. |
| 42 | * Extras:: GNU Common C++ extras. |
| 43 | * Serverlets:: GNU Common C++ serverlets. |
| 44 | * Compiler Options:: Compiler options to use with GNU Common C++. |
| 45 | * Automake Services:: GNU Common C++ automake services. |
| 46 | * Configuring Sources:: Configuring GNU Common C++ sources. |
| 47 | * Developer Documentation:: Information of interest for CC++ developers. |
| 48 | * Licenses:: Library and documentation licenses. |
| 49 | * Class and Data Type Index:: Index of Common C++ classes and data types. |
| 50 | * Method and Function Index:: Index of Common C++ methods and functions. |
| 51 | * Concept Index:: Index of concepts. |
| 52 | |
| 53 | |
| 54 | File: commoncpp2.info, Node: Introduction, Next: Distribution, Prev: Top, Up: Top |
| 55 | |
| 56 | 1 Introduction |
| 57 | ************** |
| 58 | |
| 59 | *PLEASE NOTE;* This is a preliminary version of this document. |
| 60 | Some information may not be complete or even somewhat obsolete; |
| 61 | bug reports, suggestions and contributions are welcome. |
| 62 | |
| 63 | In writing this document I hope to better explain what the GNU Common |
| 64 | C++ library is about and how it may be used in developing your own C++ |
| 65 | applications. This document is intended as an overview and unifying |
| 66 | document to support the already detailed class-by-class function |
| 67 | descriptions found and browsable in the "doc" subdirectory of the |
| 68 | Common C++ distribution. |
| 69 | |
| 70 | GNU Common C++ offers a set of "portable" classes that can be used to |
| 71 | build highly portable applications in C++. In particular, Common C++ |
| 72 | offers classes that abstract threading, sockets, synchronization, serial |
| 73 | I/O, "config" file parsing, class object persistence, shared object |
| 74 | module loading, daemon management, and optimized "block" and memory |
| 75 | mapped file I/O under a set of consistent classes that your application |
| 76 | can then be built from. The goal is to write your application to use |
| 77 | the portable abstract services and classes of the GNU Common C++ |
| 78 | libraries rather than having to access low level system services |
| 79 | directly. |
| 80 | |
| 81 | There is a large diversity of views in how one should code a C++ |
| 82 | framework. Since a large number of older C++ compilers remain in |
| 83 | everyday use, I choose to use what I felt was an appropriate set of C++ |
| 84 | language features and practices to provide the greatest compiler |
| 85 | compatibility and to generate the most optimized code for GNU Common |
| 86 | C++. To further reduce the overhead of writing GNU Common C++ |
| 87 | applications, I have split the primary library image itself into |
| 88 | several different shared libraries. This allowed me to collect the |
| 89 | more obscure and less likely to be used features into separate |
| 90 | libraries which need never be loaded. |
| 91 | |
| 92 | Finally, in designing GNU Common C++, I assume that class extension |
| 93 | (inheritance) is the primary vehicle for application development. The |
| 94 | GNU Common C++ framework, while offering many classes that are usable |
| 95 | directly, is designed for one to create applications by extending Common |
| 96 | C++ "base" classes into an application specific versions of said classes |
| 97 | as needed. |
| 98 | |
| 99 | |
| 100 | File: commoncpp2.info, Node: Distribution, Next: Framework Description, Prev: Introduction, Up: Top |
| 101 | |
| 102 | 2 Distribution |
| 103 | ************** |
| 104 | |
| 105 | This manual is licensed under the terms of the GNU Free Documentation |
| 106 | License, *Note GNU Free Documentation License::. |
| 107 | |
| 108 | GNU Common C++ is free software (see |
| 109 | `http://www.gnu.org/philosophy/philosophy.html'). There are several |
| 110 | ways to get GNU Common C++, refer to `http://www.gnu.org' and |
| 111 | `http://www.gnu.org/software/commoncpp/'. |
| 112 | |
| 113 | The GNU Common C++ framework is licensed under the terms of the GNU |
| 114 | General Public License, *Note GNU General Public License::, plus a |
| 115 | linking exception, *Note GNU Common C++ Linking Exception::, that |
| 116 | grants additional privileges. These privileges are similar to the terms |
| 117 | Guile is licensed under and constitute privileges similar to the LGPL. |
| 118 | David Sugar explains why these licensing terms were chosen for Common |
| 119 | C++ as follows: |
| 120 | |
| 121 | The one problem I recall immediately with the LGPL as it applies to |
| 122 | C++ class frameworks is the way it defines and refers to "linking" vs |
| 123 | "derived works". In concept, a C++ header with inline members or |
| 124 | template is not "linked" in the same sense as one might presume the |
| 125 | meaning in traditional C library, and what does one make of a class |
| 126 | who's base class is defined in a header in a LGPL protected library? |
| 127 | Is creating a derived C++ class purely a linking operation or creating |
| 128 | a derived/composite work? |
| 129 | |
| 130 | At the time it seemed simpler to take the language of the GPL and |
| 131 | provide an appropriate privileges to allow Common C++ to be used in |
| 132 | ways that achieve the same goals of the LGPL, but without using the |
| 133 | same choice of language for this that is found in the LGPL. We |
| 134 | actually looked at the Guile license, which also faced many of these |
| 135 | questions, and choose to use their methodology for creating a special |
| 136 | privilege in this regard. Of course, this was a number of years ago, |
| 137 | and the language of the LGPL (and GPL) has evolved over time to better |
| 138 | address the needs of object oriented frameworks. If the language of |
| 139 | the current LGPL were close enough to resolving these goals, I think we |
| 140 | would likely switch to it, as that would resolve some confusion over |
| 141 | the exact license status. I have found it simpler to explain it as a |
| 142 | LGPL-like license since we were trying for much the same effect within |
| 143 | the context of a C++ framework, and most people basically understand |
| 144 | what the LGPL is. |
| 145 | |
| 146 | |
| 147 | File: commoncpp2.info, Node: Framework Description, Next: Extras, Prev: Distribution, Up: Top |
| 148 | |
| 149 | 3 Framework Description |
| 150 | *********************** |
| 151 | |
| 152 | This chapter provides a description of the GNU Common C++ framework |
| 153 | main components. |
| 154 | |
| 155 | * Menu: |
| 156 | |
| 157 | * Overall Concepts:: Global GNU Common C++ Practices. |
| 158 | * Threading Concepts:: GNU Common C++ Threading Concepts. |
| 159 | * Synchronization:: GNU Common C++ Synchronization. |
| 160 | * Sockets:: GNU Common C++ Sockets. |
| 161 | * Serial I/O:: GNU Common C++ Serial I/O. |
| 162 | * Block I/O:: GNU Common C++ Block I/O. |
| 163 | * Daemons:: GNU Common C++ Daemon Support. |
| 164 | * Persistence:: GNU Common C++ Persistence. |
| 165 | * Configuration and Misc.:: GNU Common C++ Configuration and Other Things. |
| 166 | * Numbers and Dates:: GNU Common C++ Numbers and Dates Manipulation. |
| 167 | * URL Streams:: GNU Common C++ HTTP Support. |
| 168 | * XML Streams and RPC:: GNU Common C++ XML Streams and RPC. |
| 169 | * Exceptions:: GNU Common C++ Exception Model. |
| 170 | * Templates:: GNU Common C++ Template Subsystem |
| 171 | |
| 172 | |
| 173 | File: commoncpp2.info, Node: Overall Concepts, Next: Threading Concepts, Up: Framework Description |
| 174 | |
| 175 | 3.1 Overall Concepts |
| 176 | ==================== |
| 177 | |
| 178 | Unless explicitly stated, all GNU Common C++ symbols are under the |
| 179 | `ost' namespace(1). Thus, when we refer to the Thread class, we |
| 180 | actually refer to ost::Thread. |
| 181 | |
| 182 | The GNU Common C++ framework actually consists of two libraries: |
| 183 | `ccgnu2' and `ccext2'(2). The first includes core functionality that |
| 184 | other things commonly depend on, such as threading and synchronization. |
| 185 | That way, if you are building a tight application with a small |
| 186 | footprint, you can have it used the ccgnu2 shared image alone. On the |
| 187 | contrary, things that require or induce new library link requirements |
| 188 | are included in `ccext2'. Hence, for example, if you do not wish to |
| 189 | use XML parsing in your application, why create an unused library |
| 190 | dependency for libxml2? The idea being that one can, if one needs to, |
| 191 | use only "core" features found in ccgnu2 and then create very compact |
| 192 | executables with very few additional library dependencies. |
| 193 | |
| 194 | ---------- Footnotes ---------- |
| 195 | |
| 196 | (1) Provided the C++ compiler used to compile GNU Common C++ |
| 197 | suupports namespaces, which is checked at configuration time. |
| 198 | |
| 199 | (2) *Note Compiler Options::, for how to specify compiling and |
| 200 | linking options for these libraries. On Win32 systems, these libraries |
| 201 | are compiled as `ccgnu2.dll' and `ccext2.dll' |
| 202 | |
| 203 | |
| 204 | File: commoncpp2.info, Node: Threading Concepts, Next: Synchronization, Prev: Overall Concepts, Up: Framework Description |
| 205 | |
| 206 | 3.2 Threading Concepts |
| 207 | ====================== |
| 208 | |
| 209 | Threading was the first part of GNU Common C++ I wrote, back when it |
| 210 | was still the APE library. My goal for GNU Common C++ threading has |
| 211 | been to make threading as natural and easy to use in C++ application |
| 212 | development as threading is in Java. With this said, one does not need |
| 213 | to use threading at all to take advantage of GNU Common C++. However, |
| 214 | all GNU Common C++ classes are designed at least to be |
| 215 | thread-aware/thread-safe as appropriate and necessary. |
| 216 | |
| 217 | GNU Common C++ threading is currently built either from the Posix |
| 218 | "pthread" library or using the win32 SDK. In that the Posix "pthread" |
| 219 | draft has gone through many revisions, and many system implementations |
| 220 | are only marginally compliant, and even then usually in different ways, |
| 221 | I wrote a large series of autoconf macros found in ost_pthread.m4 which |
| 222 | handle the task of identifying which pthread features and capabilities |
| 223 | your target platform supports. In the process I learned much about |
| 224 | what autoconf can and cannot do for you. |
| 225 | |
| 226 | Currently the GNU Portable Thread library (GNU pth) is not directly |
| 227 | supported in GNU Common C++. While GNU "Pth" doesn't offer direct |
| 228 | native threading support or benefit from SMP hardware, many of the |
| 229 | design advantages of threading can be gained from it's use, and the Pth |
| 230 | pthread "emulation" library should be usable with GNU Common C++. In |
| 231 | the future, GNU Common C++ will directly support Pth, as well as OS/2 |
| 232 | and BeOS native threading API's. |
| 233 | |
| 234 | GNU Common C++ itself defines a fairly "neutral" threading model that |
| 235 | is not tied to any specific API such as pthread, win32, etc. This |
| 236 | neutral thread model is contained in a series of classes which handle |
| 237 | threading and synchronization and which may be used together to build |
| 238 | reliable threaded applications. |
| 239 | |
| 240 | GNU Common C++ defines application specific threads as objects which |
| 241 | are derived from the GNU Common C++ "Thread" base class. At minimum |
| 242 | the "run" method must be implemented, and this method essentially is |
| 243 | the "thread", for it is executed within the execution context of the |
| 244 | thread, and when the run method terminates the thread is assumed to |
| 245 | have terminated. |
| 246 | |
| 247 | GNU Common C++ allows one to specify the running priority of a newly |
| 248 | created thread relative to the "parent" thread which is the thread that |
| 249 | is executing when the constructor is called. Since most newer C++ |
| 250 | implementations do not allow one to call virtual constructors or virtual |
| 251 | methods from constructors, the thread must be "started" after the |
| 252 | constructor returns. This is done either by defining a "starting" |
| 253 | semaphore object that one or more newly created thread objects can wait |
| 254 | upon, or by invoking an explicit "Start" member function. |
| 255 | |
| 256 | Threads can be "suspended" and "resumed". As this behavior is not |
| 257 | defined in the Posix "pthread" specification, it is often emulated |
| 258 | through signals. Typically SIGUSR1 will be used for this purpose in |
| 259 | GNU Common C++ applications, depending in the target platform. On |
| 260 | Linux, since threads are indeed processes, SIGSTOP and SIGCONT can be |
| 261 | used. On solaris, the Solaris thread library supports suspend and |
| 262 | resume directly. |
| 263 | |
| 264 | Threads can be canceled. Not all platforms support the concept of |
| 265 | externally cancelable threads. On those platforms and API |
| 266 | implementations that do not, threads are typically canceled through the |
| 267 | action of a signal handler. |
| 268 | |
| 269 | As noted earlier, threads are considered running until the "run" |
| 270 | method returns, or until a cancellation request is made. GNU Common |
| 271 | C++ threads can control how they respond to cancellation, using |
| 272 | setCancellation(). Cancellation requests can be ignored, set to occur |
| 273 | only when a cancellation "point" has been reached in the code, or occur |
| 274 | immediately. Threads can also exit by returning from run() or by |
| 275 | invoking the exit() method. |
| 276 | |
| 277 | Generally it is a good practice to initialize any resources the |
| 278 | thread may require within the constructor of your derived thread class, |
| 279 | and to purge or restore any allocated resources in the destructor. In |
| 280 | most cases, the destructor will be executed after the thread has |
| 281 | terminated, and hence will execute within the context of the thread |
| 282 | that requested a join rather than in the context of the thread that is |
| 283 | being terminated. Most destructors in derived thread classes should |
| 284 | first call terminate() to make sure the thread has stopped running |
| 285 | before releasing resources. |
| 286 | |
| 287 | A GNU Common C++ thread is normally canceled by deleting the thread |
| 288 | object. The process of deletion invokes the thread's destructor, and |
| 289 | the destructor will then perform a "join" against the thread using the |
| 290 | terminate() function. This behavior is not always desirable since the |
| 291 | thread may block itself from cancellation and block the current |
| 292 | "delete" operation from completing. One can alternately invoke |
| 293 | terminate() directly before deleting a thread object. |
| 294 | |
| 295 | When a given GNU Common C++ thread exits on it's own through it's |
| 296 | run() method, a "final" method will be called. This Final method will |
| 297 | be called while the thread is "detached". If a thread object is |
| 298 | constructed through a "new" operator, it's final method can be used to |
| 299 | "self delete" when done, and allows an independent thread to construct |
| 300 | and remove itself autonomously. |
| 301 | |
| 302 | A special global function, getThread(), is provided to identify the |
| 303 | thread object that represents the current execution context you are |
| 304 | running under. This is sometimes needed to deliver signals to the |
| 305 | correct thread. Since all thread manipulation should be done through |
| 306 | the GNU Common C++ (base) thread class itself, this provides the same |
| 307 | functionality as things like "pthread_self" for GNU Common C++. |
| 308 | |
| 309 | GNU Common C++ threads are often aggregated into other classes to |
| 310 | provide services that are "managed" from or operate within the context |
| 311 | of a thread, even within the GNU Common C++ framework itself. A good |
| 312 | example of this is the TCPSession class, which essentially is a |
| 313 | combination of a TCP client connection and a separate thread the user |
| 314 | can define by deriving a class with a Run() method to handle the |
| 315 | connected service. This aggregation logically connects the successful |
| 316 | allocation of a given resource with the construction of a thread to |
| 317 | manage and perform operations for said resource. |
| 318 | |
| 319 | Threads are also used in "service pools". In GNU Common C++, a |
| 320 | service pool is one or more threads that are used to manage a set of |
| 321 | resources. While GNU Common C++ does not provide a direct "pool" |
| 322 | class, it does provide a model for their implementation, usually by |
| 323 | constructing an array of thread "service" objects, each of which can |
| 324 | then be assigned the next new instance of a given resource in turn or |
| 325 | algorithmically. |
| 326 | |
| 327 | Threads have signal handlers associated with them. Several signal |
| 328 | types are "predefined" and have special meaning. All signal handlers |
| 329 | are defined as virtual member functions of the Thread class which are |
| 330 | called when a specific signal is received for a given thread. The |
| 331 | "SIGPIPE" event is defined as a "onDisconnect" event since it's normally |
| 332 | associated with a socket disconnecting or broken fifo. The onHangup() |
| 333 | method is associated with the SIGHUP signal. All other signals are |
| 334 | handled through the more generic signal(). |
| 335 | |
| 336 | Incidently, unlike Posix, the win32 API has no concept of signals, |
| 337 | and certainly no means to define or deliver signals on a per-thread |
| 338 | basis. For this reason, no signal handling is supported or emulated in |
| 339 | the win32 implementation of GNU Common C++ at this time. |
| 340 | |
| 341 | In addition to TCPStream, there is a TCPSession class which combines |
| 342 | a thread with a TCPStream object. The assumption made by TCPSession is |
| 343 | that one will service each TCP connection with a separate thread, and |
| 344 | this makes sense for systems where extended connections may be |
| 345 | maintained and complex protocols are being used over TCP. |
| 346 | |
| 347 | |
| 348 | File: commoncpp2.info, Node: Synchronization, Next: Sockets, Prev: Threading Concepts, Up: Framework Description |
| 349 | |
| 350 | 3.3 Synchronization |
| 351 | =================== |
| 352 | |
| 353 | Synchronization objects are needed when a single object can be |
| 354 | potentially manipulated by more than one thread (execution) context |
| 355 | concurrently. GNU Common C++ provides a number of specialized classes |
| 356 | and objects that can be used to synchronize threads. |
| 357 | |
| 358 | One of the most basic GNU Common C++ synchronization object is the |
| 359 | Mutex class. A Mutex only allows one thread to continue execution at a |
| 360 | given time over a specific section of code. Mutex's have a enter and |
| 361 | leave method; only one thread can continue from the Enter until the |
| 362 | Leave is called. The next thread waiting can then get through. |
| 363 | Mutex's are also known as "CRITICAL SECTIONS" in win32-speak. |
| 364 | |
| 365 | The GNU Common C++ mutex is presumed to support recursive locking. |
| 366 | This was deemed essential because a mutex might be used to block |
| 367 | individual file requests in say, a database, but the same mutex might |
| 368 | be needed to block a whole series of database updates that compose a |
| 369 | "transaction" for one thread to complete together without having to |
| 370 | write alternate non-locking member functions to invoke for each part of |
| 371 | a transaction. |
| 372 | |
| 373 | Strangely enough, the original pthread draft standard does not |
| 374 | directly support recursive mutexes. In fact this is the most common |
| 375 | "NP" extension for most pthread implementations. GNU Common C++ |
| 376 | emulates recursive mutex behavior when the target platform does not |
| 377 | directly support it. |
| 378 | |
| 379 | In addition to the Mutex, GNU Common C++ supports a rwlock class |
| 380 | (ThreadLock). This implements the X/Open recommended "rwlock". On |
| 381 | systems which do not support rwlock's, the behavior is emulated with a |
| 382 | Mutex; however, the advantage of a rwlock over a mutex is then entirely |
| 383 | lost. There has been some suggested clever hacks for "emulating" the |
| 384 | behavior of a rwlock with a pair of mutexes and a semaphore, and one of |
| 385 | these will be adapted for GNU Common C++ in the future for platforms |
| 386 | that do not support rwlock's directly. |
| 387 | |
| 388 | GNU Common C++ also supports "semaphores". Semaphores are typically |
| 389 | used as a counter for protecting or limiting concurrent access to a |
| 390 | given resource, such as to permitting at most "x" number of threads to |
| 391 | use resource "y", for example. Semaphore's are also convenient to use |
| 392 | as synchronization objects to rondevous and signal activity and/or post |
| 393 | pending service requests between one thread thread and another. |
| 394 | |
| 395 | In addition to Semaphore objects, GNU Common C++ supports "Event" |
| 396 | objects. Event objects are triggered "events" which are used to notify |
| 397 | one thread of some event it is waiting for from another thread. These |
| 398 | event objects use a trigger/reset mechanism and are related to low |
| 399 | level conditional variables. |
| 400 | |
| 401 | A special class, the ThreadKey, is used to hold state information |
| 402 | that must be unique for each thread of context. Finally, GNU Common C++ |
| 403 | supports a thread-safe "AtomicCounter" class. This can often be used |
| 404 | for reference counting without having to protect the counter with a |
| 405 | separate Mutex counter. This lends to lighter-weight code. |
| 406 | |
| 407 | |
| 408 | File: commoncpp2.info, Node: Sockets, Next: Serial I/O, Prev: Synchronization, Up: Framework Description |
| 409 | |
| 410 | 3.4 Sockets |
| 411 | =========== |
| 412 | |
| 413 | GNU Common C++ provides a set of classes that wrap and define the |
| 414 | operation of network "sockets". Much like with Java, there are also a |
| 415 | related set of classes that are used to define and manipulate objects |
| 416 | which act as "hostname" and "network addresses" for socket connections. |
| 417 | |
| 418 | The network name and address objects are all derived from a common |
| 419 | InetAddress base class. Specific classes, such as InetHostAddress, |
| 420 | InetMaskAddress, etc, are defined from InetAddress entirely so that the |
| 421 | manner a network address is being used can easily be documented and |
| 422 | understood from the code and to avoid common errors and accidental |
| 423 | misuse of the wrong address object. For example, a "connection" to |
| 424 | something that is declared as a "InetHostAddress" can be kept type-safe |
| 425 | from a "connection" accidently being made to something that was |
| 426 | declared a "BroadcastAddress". |
| 427 | |
| 428 | The socket is itself defined in a single base class named, quite |
| 429 | unremarkably, "Socket". This base class is not directly used, but is |
| 430 | provided to offer properties common to other GNU Common C++ socket |
| 431 | classes, including the socket exception model and the ability to set |
| 432 | socket properties such as QoS, "sockopts" properties like Dont-Route |
| 433 | and Keep-Alive, etc. |
| 434 | |
| 435 | The first usable socket class is the TCPStream. Since a TCP |
| 436 | connection is always a "streamed" virtual circuit with flow control, |
| 437 | the standard stream operators ("<<" and ">>") may be used with |
| 438 | TCPStream directly. TCPStream itself can be formed either by |
| 439 | connecting to a bound network address of a TCP server, or can be |
| 440 | created when "accepting" a network connection from a TCP server. |
| 441 | |
| 442 | An implicit and unique TCPSocket object exists in GNU Common C++ to |
| 443 | represent a bound TCP socket acting as a "server" for receiving |
| 444 | connection requests. This class is not part of TCPStream because such |
| 445 | objects normally perform no physical I/O (read or write operations) |
| 446 | other than to specify a listen backlog queue and perform "accept" |
| 447 | operations for pending connections. The GNU Common C++ TCPSocket |
| 448 | offers a Peek method to examine where the next pending connection is |
| 449 | coming from, and a Reject method to flush the next request from the |
| 450 | queue without having to create a session. |
| 451 | |
| 452 | The TCPSocket also supports a "onAccept" method which can be called |
| 453 | when a TCPStream related object is created from a TCPSocket. By |
| 454 | creating a TCPStream from a TCPSocket, an accept operation |
| 455 | automatically occurs, and the TCPSocket can then still reject the |
| 456 | client connection through the return status of it's OnAccept method. |
| 457 | |
| 458 | In addition to connected TCP sessions, GNU Common C++ supports UDP |
| 459 | sockets and these also cover a range of functionality. Like a |
| 460 | TCPSocket, A UDPSocket can be created bound to a specific network |
| 461 | interface and/or port address, although this is not required. UDP |
| 462 | sockets also are usually either connected or otherwise "associated" |
| 463 | with a specific "peer" UDP socket. Since UDP sockets operate through |
| 464 | discreet packets, there are no streaming operators used with UDP |
| 465 | sockets. |
| 466 | |
| 467 | In addition to the UDP "socket" class, there is a "UDPBroadcast" |
| 468 | class. The UDPBroadcast is a socket that is set to send messages to a |
| 469 | subnet as a whole rather than to an individual peer socket that it may |
| 470 | be associated with. |
| 471 | |
| 472 | UDP sockets are often used for building "realtime" media streaming |
| 473 | protocols and full duplex messaging services. When used in this |
| 474 | manner, typically a pair of UDP sockets are used together; one socket |
| 475 | is used to send and the other to receive data with an associated pair |
| 476 | of UDP sockets on a "peer" host. This concept is represented through |
| 477 | the GNU Common C++ UDPDuplex object, which is a pair of sockets that |
| 478 | communicate with another UDPDuplex pair. |
| 479 | |
| 480 | Finally, a special set of classes, "SocketPort" and "SocketService", |
| 481 | exist for building realtime streaming media servers on top of UDP and |
| 482 | TCP protocols. The "SocketPort" is used to hold a connected or |
| 483 | associated TCP or UDP socket which is being "streamed" and which offers |
| 484 | callback methods that are invoked from a "SocketService" thread. |
| 485 | SocketService's can be pooled into logical thread pools that can |
| 486 | service a group of SocketPorts. A millisecond accurate "timer" is |
| 487 | associated with each SocketPort and can be used to time synchronize |
| 488 | SocketPort I/O operations. |
| 489 | |
| 490 | |
| 491 | File: commoncpp2.info, Node: Serial I/O, Next: Block I/O, Prev: Sockets, Up: Framework Description |
| 492 | |
| 493 | 3.5 Serial I/O |
| 494 | ============== |
| 495 | |
| 496 | GNU Common C++ serial I/O classes are used to manage serial devices and |
| 497 | implement serial device protocols. From the point of view of GNU |
| 498 | Common C++, serial devices are supported by the underlying Posix |
| 499 | specified "termios" call interface. |
| 500 | |
| 501 | The serial I/O base class is used to hold a descriptor to a serial |
| 502 | device and to provide an exception handling interface for all serial |
| 503 | I/O classes. The base class is also used to specify serial I/O |
| 504 | properties such as communication speed, flow control, data size, and |
| 505 | parity. The "Serial" base class is not itself directly used in |
| 506 | application development, however. |
| 507 | |
| 508 | GNU Common C++ Serial I/O is itself divided into two conceptual |
| 509 | modes; frame oriented and line oriented I/O. Both frame and line |
| 510 | oriented I/O makes use of the ability of the underlying tty driver to |
| 511 | buffer data and return "ready" status from when select either a |
| 512 | specified number of bytes or newline record has been reached by |
| 513 | manipulating termios c_cc fields appropriately. This provides some |
| 514 | advantage in that a given thread servicing a serial port can block and |
| 515 | wait rather than have to continually poll or read each and every byte |
| 516 | as soon as it appears at the serial port. |
| 517 | |
| 518 | The first application relevant serial I/O class is the TTYStream |
| 519 | class. TTYStream offers a linearly buffered "streaming" I/O session |
| 520 | with the serial device. Furthermore, traditional C++ "stream" |
| 521 | operators (<< and >>) may be used with the serial device. A more |
| 522 | "true" to ANSI C++ library format "ttystream" is also available, and |
| 523 | this supports an "open" method in which one can pass initial serial |
| 524 | device parameters immediately following the device name in a single |
| 525 | string, as in "/dev/tty3a:9600,7,e,1", as an example. |
| 526 | |
| 527 | The TTYSession aggragates a TTYStream and a GNU Common C++ Thread |
| 528 | which is assumed to be the execution context that will be used to |
| 529 | perform actual I/O operations. This class is very anagolous to |
| 530 | TCPSession. |
| 531 | |
| 532 | The TTYPort and TTYService classes are used to form thread-pool |
| 533 | serviced serial I/O protocol sets. These can be used when one has a |
| 534 | large number of serial devices to manage, and a single (or limited |
| 535 | number of) thread(s) can then be used to service the tty port objects |
| 536 | present. Each tty port supports a timer control and several virtual |
| 537 | methods that the service thread can call when events occur. This model |
| 538 | provides for "callback" event management, whereby the service thread |
| 539 | performs a "callback" into the port object when events occur. Specific |
| 540 | events supported include the expiration of a TTYPort timer, pending |
| 541 | input data waiting to be read, and "sighup" connection breaks. |
| 542 | |
| 543 | |
| 544 | File: commoncpp2.info, Node: Block I/O, Next: Daemons, Prev: Serial I/O, Up: Framework Description |
| 545 | |
| 546 | 3.6 Block I/O |
| 547 | ============= |
| 548 | |
| 549 | GNU Common C++ block I/O classes are meant to provide more convenient |
| 550 | file control for paged or random access files portably, and to answer |
| 551 | many issues that ANSI C++ leaves untouched in this area. A common base |
| 552 | class, RandomFile, is provided for setting descriptor attributes and |
| 553 | handling exceptions. From this, three kinds of random file access are |
| 554 | supported. |
| 555 | |
| 556 | ThreadFile is meant for use by a threaded database server where |
| 557 | multiple threads may each perform semi-independent operations on a |
| 558 | given database table stored on disk. A special "fcb" structure is used |
| 559 | to hold file "state", and pread/pwrite is used whenever possible for |
| 560 | optimized I/O. On systems that do not offer pwread/pwrite, a Mutex |
| 561 | lock is used to protect concurrent lseek and read/write operations. |
| 562 | ThreadFile managed databases are assumed to be used only by the local |
| 563 | server and through a single file descriptor. |
| 564 | |
| 565 | SharedFile is used when a database may be shared between multiple |
| 566 | processes. SharedFile automatically applies low level byte-range "file |
| 567 | locks", and provides an interface to fetch and release byte-range |
| 568 | locked portions of a file. |
| 569 | |
| 570 | The MappedFile class provides a portable interface to memory mapped |
| 571 | file access. One can map and unmap portions of a file on demand, and |
| 572 | update changed memory pages mapped from files immediately through |
| 573 | sync(). |
| 574 | |
| 575 | |
| 576 | File: commoncpp2.info, Node: Daemons, Next: Persistence, Prev: Block I/O, Up: Framework Description |
| 577 | |
| 578 | 3.7 Daemons |
| 579 | =========== |
| 580 | |
| 581 | Daemon support consists of two GNU Common C++ features. The first is |
| 582 | the "pdetach" function. This function provides a simple and portable |
| 583 | means to fork/detach a process into a daemon. In addition, the "slog" |
| 584 | object is provided. |
| 585 | |
| 586 | "slog" is an object which behaves very similar to the Standard C++ |
| 587 | "clog". The key difference is that the "slog" object sends it's output |
| 588 | to the system logging daemon (typically syslogd) rather than through |
| 589 | stderr. "slog" can be streamed with the << operator just like "clog". |
| 590 | "slog" can also accept arguments to specify logging severity level, etc. |
| 591 | |
| 592 | |
| 593 | File: commoncpp2.info, Node: Persistence, Next: Configuration and Misc., Prev: Daemons, Up: Framework Description |
| 594 | |
| 595 | 3.8 Persistence |
| 596 | =============== |
| 597 | |
| 598 | The GNU Common C++ Persistence library was designed with one thought |
| 599 | foremost - namely that large interlinked structures should be easily |
| 600 | serializable. The current implementation is _not_ endian safe, and so, |
| 601 | whilst it should in theory be placed in the "Extras" section, the |
| 602 | codebase itself is considered stable enough to be part of the main |
| 603 | distribution. |
| 604 | |
| 605 | The Persistence library classes are designed to provide a quick and |
| 606 | easy way to make your data structures serializable. The only way of |
| 607 | doing this safely is to inherit your classes from the provided class |
| 608 | Persistence::BaseObject. The macros "IMPLEMENT_PERSISTENCE" and |
| 609 | "DECLARE_PERSISTENCE" provide all the function prototypes and |
| 610 | implementation details you may require to get your code off the ground. |
| 611 | |
| 612 | |
| 613 | File: commoncpp2.info, Node: Configuration and Misc., Next: Numbers and Dates, Prev: Persistence, Up: Framework Description |
| 614 | |
| 615 | 3.9 Configuration and Misc. |
| 616 | =========================== |
| 617 | |
| 618 | There are a number of odd and specialized utility classes found in |
| 619 | Common C++. The most common of these is the "MemPager" class. This is |
| 620 | basically a class to enable page-grouped "cumulative" memory |
| 621 | allocation; all accumulated allocations are dropped during the |
| 622 | destructor. This class has found it's way in a lot of other utility |
| 623 | classes in GNU Common C++. |
| 624 | |
| 625 | The most useful of the misc. classes is the Keydata class. This |
| 626 | class is used to load and then hold "keyword = value" pairs parsed from |
| 627 | a text based "config" file that has been divided into "[sections]". |
| 628 | Keydata can also load a table of "initialization" values for keyword |
| 629 | pairs that were not found in the external file. |
| 630 | |
| 631 | One typically derives an application specific keydata class to load a |
| 632 | specific portion of a known config file and initialize it's values. |
| 633 | One can then declare a global instance of these objects and have |
| 634 | configuration data initialized automatically as the executable is |
| 635 | loaded. |
| 636 | |
| 637 | Hence, if I have a "[paths]" section in a "/etc/server.conf" file, I |
| 638 | might define something like: |
| 639 | |
| 640 | class KeyPaths : public Keydata |
| 641 | { |
| 642 | public: |
| 643 | KeyPaths() : Keydata("/server/paths") |
| 644 | { |
| 645 | static KEYDEF *defvalues = { |
| 646 | {"datafiles", "/var/server"}, |
| 647 | {NULL, NULL}}; |
| 648 | |
| 649 | // override with [paths] from "~/.serverrc" if avail. |
| 650 | |
| 651 | Load("~server/paths"); |
| 652 | Load(defvalues); |
| 653 | } |
| 654 | }; |
| 655 | |
| 656 | KeyPaths keypaths; |
| 657 | |
| 658 | |
| 659 | File: commoncpp2.info, Node: Numbers and Dates, Next: URL Streams, Prev: Configuration and Misc., Up: Framework Description |
| 660 | |
| 661 | 3.10 Numbers and Dates |
| 662 | ====================== |
| 663 | |
| 664 | _TODO._ This section will explain the number manipulation classes |
| 665 | (`Number' and `ZNumber', as well as the data related classes (`Date' |
| 666 | and `DateNumber'). |
| 667 | |
| 668 | |
| 669 | File: commoncpp2.info, Node: URL Streams, Next: XML Streams and RPC, Prev: Numbers and Dates, Up: Framework Description |
| 670 | |
| 671 | 3.11 URL Streams |
| 672 | ================ |
| 673 | |
| 674 | _TODO._ This section will explain the URLStream class, as well as the |
| 675 | following URL related functions: |
| 676 | |
| 677 | `URLStream' |
| 678 | |
| 679 | `urlDecode' |
| 680 | |
| 681 | `urlEncode' |
| 682 | |
| 683 | `b64Decode' |
| 684 | |
| 685 | `b64Encode' |
| 686 | |
| 687 | In the meantime you can have a look at the `urlfetch.cpp' demo, |
| 688 | which is a good example of use of URLStream to retrieve documents from |
| 689 | URLs. |
| 690 | |
| 691 | |
| 692 | File: commoncpp2.info, Node: XML Streams and RPC, Next: Exceptions, Prev: URL Streams, Up: Framework Description |
| 693 | |
| 694 | 3.12 XML Streams and RPC |
| 695 | ======================== |
| 696 | |
| 697 | _TODO._ This section will explain the XML streams parsing (`XMLStream' |
| 698 | class) and XML RPC (`XMLRPC' class) facilities of Common C++. In the |
| 699 | meantime, you can have a look at the `xmlfetch.cpp' demo, which defines |
| 700 | a basic XML parser for URL streams. |
| 701 | |
| 702 | |
| 703 | File: commoncpp2.info, Node: Exceptions, Next: Templates, Prev: XML Streams and RPC, Up: Framework Description |
| 704 | |
| 705 | 3.13 Exceptions |
| 706 | =============== |
| 707 | |
| 708 | _TODO._ This section will explain the exception model of Common C++, |
| 709 | based on the `Exception' class, derived from std::exception. |
| 710 | |
| 711 | Other exception classes that will be commented are: `IOException', |
| 712 | `SockException', `DirException', `DSOException', `FIFOException', |
| 713 | `PipeException', `FileException', `FTPException', `SerException', |
| 714 | `ThrException' and `PersistException'. In the meantime you can have a |
| 715 | look at the exception class hierarchy on the reference manual. |
| 716 | |
| 717 | |
| 718 | File: commoncpp2.info, Node: Templates, Prev: Exceptions, Up: Framework Description |
| 719 | |
| 720 | 3.14 Templates |
| 721 | ============== |
| 722 | |
| 723 | _TODO._ This section will explain the template subsistem of Common C++. |
| 724 | |
| 725 | |
| 726 | File: commoncpp2.info, Node: Extras, Next: Serverlets, Prev: Framework Description, Up: Top |
| 727 | |
| 728 | 4 Extras |
| 729 | ******** |
| 730 | |
| 731 | _TODO: this is rather outdated._ |
| 732 | |
| 733 | At the time of the release of GNU Common C++ 1.0, it was deemed that |
| 734 | several class libraries either were incomplete or still experimental, |
| 735 | and the 1.0 designation seemed very inappropriate for these libraries. |
| 736 | I also wanted to have a mechanism to later add new GNU Common C++ class |
| 737 | libraries without having to disrupt or add experimental code into the |
| 738 | main GNU Common C++ release. |
| 739 | |
| 740 | To resolve this issue, a second package has been created, and is |
| 741 | named GNU "GNU Common C++ Extras". The extras package simply holds |
| 742 | class frameworks that are still not considered "mature" or |
| 743 | "recommended". This package can be downloaded, compiled, and |
| 744 | installed, after GNU Common C++ itself. Many of the class libraries |
| 745 | appearing in the extras package are likely to appear in GNU Common C++ |
| 746 | proper at some future date, and should be considered usable in their |
| 747 | current form. They are made available both to support continued |
| 748 | development of GNU Common C++ proper and because, while not yet mature, |
| 749 | they are considered "useful" in some manner. |
| 750 | |
| 751 | The initial GNU Common C++ "extras" package consisted of two |
| 752 | libraries; Common C++ "scripting" and "math". The scripting library |
| 753 | (-lccscript) is the GNU Bayonne scripting engine which is used as a |
| 754 | near-realtime event driven embedded scripting engine for "callback" |
| 755 | driven state-event server applications. The Bayonne scripting engine |
| 756 | directly uses C++ inheritance to extend the Bayonne dialect for |
| 757 | application specific features and is used as a core technology in the |
| 758 | GNU Bayonne, DBS, and Meridian telephony servers and as part of the a |
| 759 | free home automation project. There has been some discussion about |
| 760 | folding the GNU Bayonne scripting concepts around a more conventional |
| 761 | scripting language, and so this package currently remains in "extras" |
| 762 | rather than part of GNU Common C++ itself. |
| 763 | |
| 764 | The other package found in the initial "extras" distribution is the |
| 765 | Common C++ math libraries. These are still at a VERY early stage of |
| 766 | development, and may well be depreciated if another suitable free C++ |
| 767 | math/numerical analysis package comes along. |
| 768 | |
| 769 | |
| 770 | File: commoncpp2.info, Node: Serverlets, Next: Compiler Options, Prev: Extras, Up: Top |
| 771 | |
| 772 | 5 Serverlets |
| 773 | ************ |
| 774 | |
| 775 | Serverlets are a concept popularized with Java and web servers. There |
| 776 | is a broad abstract architectural concept of serverlets or plugins that |
| 777 | one also finds in my GNU Common C++ projects, though they are not |
| 778 | directly defined as part of GNU Common C++ itself. |
| 779 | |
| 780 | A GNU Common C++ "serverlet" comes about in a Common C++ server |
| 781 | project, such as the Bayonne telephony server, where one wishes to |
| 782 | define functionality for alternate hardware or API's in alternated |
| 783 | shared object files that are selected at runtime, or to add "plugins" |
| 784 | to enhance functionality. A serverlet is defined in this sense as a |
| 785 | "DSO" loaded "-module" object file which is linked at runtime against a |
| 786 | server process that exports it's base classes using "-export-dynamic". |
| 787 | The "server" image then acts as a carrier for the runtime module's base |
| 788 | functionality. |
| 789 | |
| 790 | Modules, or "serverlets", defined in this way do not need to be |
| 791 | compiled with position independent code. The module is only used with |
| 792 | a specific server image and so the runtime address is only resolved |
| 793 | once rather than at different load addresses for different arbitrary |
| 794 | processes. |
| 795 | |
| 796 | I recommend that GNU Common C++ based "servers" which publish and |
| 797 | export base classes in this manner for plugins should also have a |
| 798 | server specific "include" file which can be installed in the cc++ |
| 799 | include directory. |
| 800 | |
| 801 | |
| 802 | File: commoncpp2.info, Node: Compiler Options, Next: Automake Services, Prev: Serverlets, Up: Top |
| 803 | |
| 804 | 6 Compiler Options |
| 805 | ****************** |
| 806 | |
| 807 | GNU Common C++ does a few things special with automake and autoconf. |
| 808 | When the Common C++ library is built, it saves a number of compiler |
| 809 | options that can be retrieved by an application being configured to use |
| 810 | GNU Common C++. These options can be retrieved from the standard output |
| 811 | of the `ccgnu2-config' script, which is installed in the machine |
| 812 | binaries path. |
| 813 | |
| 814 | This is done to assure the same compiler options are used to build |
| 815 | your application that were in effect when GNU Common C++ itself was |
| 816 | built. Since linkage information is also saved in this manner, this |
| 817 | means your application's "configure" script does not have to go through |
| 818 | the entire process of testing for libraries or GNU Common C++ related |
| 819 | compiler options all over again. Finally, GNU Common C++ saves it's |
| 820 | own generated `config.h' file in `cc++/config.h'(1). |
| 821 | |
| 822 | `ccgnu2-config' has the following options (which are shown if you |
| 823 | type `ccgnu2-config --help'): |
| 824 | |
| 825 | Usage: ccgnu2-config [OPTIONS] |
| 826 | Options: |
| 827 | [--prefix] |
| 828 | [--version] |
| 829 | [--flags] |
| 830 | [--libs] |
| 831 | [--gnulibs] |
| 832 | [--iolibs] |
| 833 | [--extlibs] |
| 834 | [--stdlibs] |
| 835 | [--includes] |
| 836 | |
| 837 | For a basic usage of Common C++, you just need the options given by |
| 838 | the following command: `ccgnu2-config --flags --stdlibs', whose output |
| 839 | should be something like this: |
| 840 | |
| 841 | foo@bar:~/$ ccgnu2-config --flags --stdlibs |
| 842 | -I/usr/local/include/cc++2 -I/usr/local/include -D_GNU_SOURCE |
| 843 | -L/usr/local/lib -lccext2 -lccgnu2 -lxml2 -lz -ldl -pthread |
| 844 | |
| 845 | Note that this is just an example, the concrete output on your system |
| 846 | will probably differ. The first output line (corresponding to |
| 847 | `--flags') tells what directories must be added to the compiler include |
| 848 | path, as well as global symbol definitions (`_GNU_SOURCE') needed to |
| 849 | compile with Common C++. The second output line (corresponding to |
| 850 | `--stdlibs') gives the linker options, both additional library path and |
| 851 | libraries that must be linked. `ccgnu2' and `ccext2' are the two |
| 852 | libraries Common C++ currently consists of. The other libraries shown |
| 853 | in the example are dependencies of Common C++. |
| 854 | |
| 855 | The list shown below tells what information is given by each of the |
| 856 | options that can be specified to `ccgnu2-config'. It also specifies |
| 857 | what would be the output corresponding to the example given before. |
| 858 | |
| 859 | `--prefix' |
| 860 | Common C++ Installation path prefix. For example, `/usr/local'. |
| 861 | |
| 862 | `--version' |
| 863 | Common C++ version. For example, `1.0.0'. |
| 864 | |
| 865 | `--flags' |
| 866 | C++ preprocessor flags. For example, `-I/usr/local/include/cc++2 |
| 867 | -I/usr/local/include -D_GNU_SOURCE'. |
| 868 | |
| 869 | `--libs' |
| 870 | C++ linker options for the main Common C++ library (`ccgnu2'). For |
| 871 | example, `-L/usr/local/lib -lccgnu2 -ldl -pthread'. |
| 872 | |
| 873 | `--gnulibs' |
| 874 | C++ linker options for the main Common C++ library (`ccgnu2'). For |
| 875 | example, `-L/usr/local/lib -lccgnu2 -ldl -pthread'. |
| 876 | |
| 877 | `--iolibs' |
| 878 | C++ linker options for the input/output Common C++ library |
| 879 | (`ccgnu2'). For example, `-L/usr/local/lib -lccgnu2 -ldl -pthread'. |
| 880 | |
| 881 | `--extlibs' |
| 882 | C++ linker options for the Common C++ "extension" library |
| 883 | (`ccext2'). For exmple, `-lccext2 -lxml2 -lz'. |
| 884 | |
| 885 | `--stdlibs' |
| 886 | C++ linker options for the whole Common C++ (`ccgnu2' and |
| 887 | `ccext2'). For example, `-L/usr/local/lib -lccext2 -lccgnu2 -lxml2 |
| 888 | -lz -ldl -pthread'. |
| 889 | |
| 890 | `--includes' |
| 891 | Common C++ specific include path. For example, |
| 892 | `/usr/local/include/cc++2'. |
| 893 | |
| 894 | |
| 895 | ---------- Footnotes ---------- |
| 896 | |
| 897 | (1) On Win32 systems, a specific `config.h' located under the |
| 898 | win32/cc++/ directory is used and installed. |
| 899 | |
| 900 | |
| 901 | File: commoncpp2.info, Node: Automake Services, Next: Configuring Sources, Prev: Compiler Options, Up: Top |
| 902 | |
| 903 | 7 Automake Services |
| 904 | ******************* |
| 905 | |
| 906 | If you are using automake, you can add the `ost_check2.m4' macros to |
| 907 | your projects autoconf "m4" directory and use several CCXX2_ macros for |
| 908 | your convenience. A "minimal" `configure.in' or `configure.ac' can be |
| 909 | constructed as: |
| 910 | |
| 911 | AC_INIT(something...) |
| 912 | AC_PROG_CXX |
| 913 | AC_PROG_CXXCPP |
| 914 | AM_PROG_LIBTOOL |
| 915 | AM_INIT_AUTOMAKE(....) |
| 916 | AM_CONFIG_HEADER(my-local-config.h) |
| 917 | OST_CCXX2_VERSION(1.0.0) |
| 918 | |
| 919 | Where `1.0.0' means configure will check for GNU Common C++ 2 1.0.0 |
| 920 | or later. These are the macros currently provided: |
| 921 | |
| 922 | `OST_CCXX2_VERSION([MINIMUM-VERSION[,ACTION-IF-FOUND[,ACTION-IF-NOT-FOUND]]])' |
| 923 | Test for usable version of CommonC++. |
| 924 | |
| 925 | `OST_CCXX2_XML([ACTION-IF-TRUE[,ACTION-IF-FALSE]])' |
| 926 | Test whether the CommonC++ library was compiled with XML parsing |
| 927 | support. |
| 928 | |
| 929 | `OST_CCXX2_HOARD' |
| 930 | Will test for and, if found, add the SMP optimized Hoard memory |
| 931 | allocator to your application link LIBS. |
| 932 | |
| 933 | `OST_CCXX2_FOX' |
| 934 | Test for the FOX toolkit. |
| 935 | |
| 936 | |
| 937 | |
| 938 | File: commoncpp2.info, Node: Configuring Sources, Next: Developer Documentation, Prev: Automake Services, Up: Top |
| 939 | |
| 940 | 8 Configuring Sources |
| 941 | ********************* |
| 942 | |
| 943 | When building GNU Common C++ on platforms that support the use of |
| 944 | configure, the following specific configuration options are provided: |
| 945 | |
| 946 | `--with-pthread[=lib]' |
| 947 | using specified pthread library |
| 948 | |
| 949 | `--with-linuxthreads' |
| 950 | use linux kernel mode library |
| 951 | |
| 952 | `--without-xml' |
| 953 | Disable xml support |
| 954 | |
| 955 | `--with-ftp' |
| 956 | Enable ftp support |
| 957 | |
| 958 | `--with-memaudit' |
| 959 | Enable memory auditing |
| 960 | |
| 961 | `--with-stlport[=dir]' |
| 962 | using SGI portable C++ stream library,ie: /usr/local, not all |
| 963 | include directory |
| 964 | |
| 965 | `--enable-debug' |
| 966 | compile for debugging |
| 967 | |
| 968 | `--enable-profiling' |
| 969 | compile for profiling |
| 970 | |
| 971 | |
| 972 | File: commoncpp2.info, Node: Developer Documentation, Next: Licenses, Prev: Configuring Sources, Up: Top |
| 973 | |
| 974 | 9 Developer Documentation |
| 975 | ************************* |
| 976 | |
| 977 | This chapter contains information of interest for developers of |
| 978 | components for the GNU Common C++ framework. |
| 979 | |
| 980 | * Menu: |
| 981 | |
| 982 | * Coding Style:: How a CommonC++ 2 source file should be written. |
| 983 | * Porting:: Common porting related problems and practices. |
| 984 | |
| 985 | |
| 986 | File: commoncpp2.info, Node: Coding Style, Next: Porting, Up: Developer Documentation |
| 987 | |
| 988 | 9.1 Coding Style |
| 989 | ================ |
| 990 | |
| 991 | How a CommonC++ 2 source file should be written. |
| 992 | |
| 993 | * Menu: |
| 994 | |
| 995 | * Naming Convention:: Overall GNU Common C++ naming conventions. |
| 996 | * Class Encapsulation:: Class interface design guidelines. |
| 997 | |
| 998 | |
| 999 | File: commoncpp2.info, Node: Naming Convention, Next: Class Encapsulation, Up: Coding Style |
| 1000 | |
| 1001 | 9.1.1 Naming Convention |
| 1002 | ----------------------- |
| 1003 | |
| 1004 | * *Classes and structs*. Begin with uppercase with word parts |
| 1005 | capitalized (ThisIsAClass) |
| 1006 | |
| 1007 | * *Method (function member, also static member)*. Begin with |
| 1008 | lowercase with word parts capitalized (setSomething, send). If a |
| 1009 | member variable is set, a `setXxxx' style name should be used, and |
| 1010 | if a member variable is fetched, a `getXxxx' style name should be |
| 1011 | used. Sometimes things might both set and perform an action, like |
| 1012 | `setError' in place of `Error' in the older release, in which |
| 1013 | case, set should still be used as the prefix. Function to handle |
| 1014 | some event (such as data arrival) should begin with `on' (ex: |
| 1015 | `onInput') |
| 1016 | |
| 1017 | * *Data member*. Begin with lowercase with word parts capitalized |
| 1018 | (`currentThread') private member can begin with underscore (_). |
| 1019 | |
| 1020 | * *Global function*. Begin with lowercase with word parts |
| 1021 | capitalized (`getThread'). |
| 1022 | |
| 1023 | * *Enumeration type*. Begin with uppercase with word parts |
| 1024 | capitalized (`Error'). |
| 1025 | |
| 1026 | * *Enumeration item*. Begin with lowercase with word parts |
| 1027 | capitalized (`errSuccess'). First word should refer to |
| 1028 | enumeration type (`errFailure', cancelImmediate). For error enum |
| 1029 | we use the prefix `err' (everyone should understand the meaning). |
| 1030 | |
| 1031 | * *Member data types*. Sometimes a class might use internal member |
| 1032 | data types or structs. These should be written using `class' |
| 1033 | rather than struct wherever possible and treated as inner |
| 1034 | `classes'. Hence, they would be capitalized in the same |
| 1035 | conventions of a class. |
| 1036 | |
| 1037 | |
| 1038 | |
| 1039 | File: commoncpp2.info, Node: Class Encapsulation, Prev: Naming Convention, Up: Coding Style |
| 1040 | |
| 1041 | 9.1.2 Class Encapsulation |
| 1042 | ------------------------- |
| 1043 | |
| 1044 | * *Friend functions*. To clean up the namespace we are looking to |
| 1045 | eliminate _friend functions_ that exist in the default or ost |
| 1046 | namespace and we are suggesting that in many cases static member |
| 1047 | functions should be used in place of friend functions unless the |
| 1048 | friend function is actually used in multiple classes. |
| 1049 | |
| 1050 | A typical example of this is found in things like `getXXX', which |
| 1051 | might be a friend function for finding a specific named instance of |
| 1052 | `XXX' thru a self organized link list contained in `XXX'. Rather, |
| 1053 | it is suggested for this to use a static member something like |
| 1054 | `XXX::find'. |
| 1055 | |
| 1056 | * *Scope of view and inheritance*. In many cases we combine and mix |
| 1057 | classes directly in GNU Common C++ (multiple inheritence). Hence, |
| 1058 | classes have to be well designed for this possibility. Ideally |
| 1059 | things that should not be exposed to derived classes should be |
| 1060 | made private so that clashes mixing similar classes with common |
| 1061 | named members do not need to occur. |
| 1062 | |
| 1063 | * *Access to member properties*. A well formed GNU Common C++ class |
| 1064 | need not expose more than is nessisary for it's practical and |
| 1065 | effective use in derived classes or thru proper public methods. |
| 1066 | Ideally set and get members should be used to manipulate internal |
| 1067 | member variables thru public interfaces rather than exposing |
| 1068 | property values directly thru public declarations. These set and |
| 1069 | get methods should use appropriate valid range and error checking |
| 1070 | logic. |
| 1071 | |
| 1072 | Member properties can often be made visible protected to optimize |
| 1073 | the code of derived classes, and care then needs to be taken when |
| 1074 | creating derived classes to make sure they do have reasonable |
| 1075 | error checking when needed. |
| 1076 | |
| 1077 | * *Constructors and destructors*. It is very common in GNU Common |
| 1078 | C++ for the constructor to create or obtain a resource that |
| 1079 | remains in scope as long as the object does, and is then releas\ed |
| 1080 | in the destructor when the object falls out of scope. Things like |
| 1081 | Mutexes, Threads and Semaphores and such very much behave this way. |
| 1082 | |
| 1083 | |
| 1084 | |
| 1085 | File: commoncpp2.info, Node: Porting, Prev: Coding Style, Up: Developer Documentation |
| 1086 | |
| 1087 | 9.2 Porting |
| 1088 | =========== |
| 1089 | |
| 1090 | Only for no-remake same problem :). |
| 1091 | |
| 1092 | * FreeBSD: assuming having thread A and B. If A call pthread_join on |
| 1093 | B and B call pthread_detach and then exit thread A hang. |
| 1094 | |
| 1095 | * Solaris: On multiple inheriting from streambuf and iostream |
| 1096 | together streambuf should inherited first (and initialized too). |
| 1097 | |
| 1098 | * Win32/MSVC6: if you use CC++ DLL library you MUST use C++ DLL |
| 1099 | library. `iostream' use a pointer to object. This object pointer |
| 1100 | can be different from library static linked and dinamically |
| 1101 | linked, so iostream see distinct object, causing strange exception |
| 1102 | and crashes. |
| 1103 | |
| 1104 | * GCC: including declaration for polimorphic class cause link to |
| 1105 | typeinfo, but typeinfos are defined only in module with classes |
| 1106 | constructors Include only needed header (this problem disappear |
| 1107 | with optimization). |
| 1108 | |
| 1109 | |
| 1110 | |
| 1111 | File: commoncpp2.info, Node: Licenses, Next: Class and Data Type Index, Prev: Developer Documentation, Up: Top |
| 1112 | |
| 1113 | Appendix A Licenses |
| 1114 | ******************* |
| 1115 | |
| 1116 | * Menu: |
| 1117 | |
| 1118 | * GNU Free Documentation License:: License for this document. |
| 1119 | * GNU General Public License:: License for the library. |
| 1120 | * GNU Common C++ Linking Exception:: Library linking exception. |
| 1121 | |
| 1122 | |
| 1123 | File: commoncpp2.info, Node: GNU Free Documentation License, Next: GNU General Public License, Up: Licenses |
| 1124 | |
| 1125 | A.1 GNU Free Documentation License |
| 1126 | ================================== |
| 1127 | |
| 1128 | Version 1.2, November 2002 |
| 1129 | |
| 1130 | Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. |
| 1131 | 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA |
| 1132 | |
| 1133 | Everyone is permitted to copy and distribute verbatim copies |
| 1134 | of this license document, but changing it is not allowed. |
| 1135 | |
| 1136 | 0. PREAMBLE |
| 1137 | |
| 1138 | The purpose of this License is to make a manual, textbook, or other |
| 1139 | functional and useful document "free" in the sense of freedom: to |
| 1140 | assure everyone the effective freedom to copy and redistribute it, |
| 1141 | with or without modifying it, either commercially or |
| 1142 | noncommercially. Secondarily, this License preserves for the |
| 1143 | author and publisher a way to get credit for their work, while not |
| 1144 | being considered responsible for modifications made by others. |
| 1145 | |
| 1146 | This License is a kind of "copyleft", which means that derivative |
| 1147 | works of the document must themselves be free in the same sense. |
| 1148 | It complements the GNU General Public License, which is a copyleft |
| 1149 | license designed for free software. |
| 1150 | |
| 1151 | We have designed this License in order to use it for manuals for |
| 1152 | free software, because free software needs free documentation: a |
| 1153 | free program should come with manuals providing the same freedoms |
| 1154 | that the software does. But this License is not limited to |
| 1155 | software manuals; it can be used for any textual work, regardless |
| 1156 | of subject matter or whether it is published as a printed book. |
| 1157 | We recommend this License principally for works whose purpose is |
| 1158 | instruction or reference. |
| 1159 | |
| 1160 | 1. APPLICABILITY AND DEFINITIONS |
| 1161 | |
| 1162 | This License applies to any manual or other work, in any medium, |
| 1163 | that contains a notice placed by the copyright holder saying it |
| 1164 | can be distributed under the terms of this License. Such a notice |
| 1165 | grants a world-wide, royalty-free license, unlimited in duration, |
| 1166 | to use that work under the conditions stated herein. The |
| 1167 | "Document", below, refers to any such manual or work. Any member |
| 1168 | of the public is a licensee, and is addressed as "you". You |
| 1169 | accept the license if you copy, modify or distribute the work in a |
| 1170 | way requiring permission under copyright law. |
| 1171 | |
| 1172 | A "Modified Version" of the Document means any work containing the |
| 1173 | Document or a portion of it, either copied verbatim, or with |
| 1174 | modifications and/or translated into another language. |
| 1175 | |
| 1176 | A "Secondary Section" is a named appendix or a front-matter section |
| 1177 | of the Document that deals exclusively with the relationship of the |
| 1178 | publishers or authors of the Document to the Document's overall |
| 1179 | subject (or to related matters) and contains nothing that could |
| 1180 | fall directly within that overall subject. (Thus, if the Document |
| 1181 | is in part a textbook of mathematics, a Secondary Section may not |
| 1182 | explain any mathematics.) The relationship could be a matter of |
| 1183 | historical connection with the subject or with related matters, or |
| 1184 | of legal, commercial, philosophical, ethical or political position |
| 1185 | regarding them. |
| 1186 | |
| 1187 | The "Invariant Sections" are certain Secondary Sections whose |
| 1188 | titles are designated, as being those of Invariant Sections, in |
| 1189 | the notice that says that the Document is released under this |
| 1190 | License. If a section does not fit the above definition of |
| 1191 | Secondary then it is not allowed to be designated as Invariant. |
| 1192 | The Document may contain zero Invariant Sections. If the Document |
| 1193 | does not identify any Invariant Sections then there are none. |
| 1194 | |
| 1195 | The "Cover Texts" are certain short passages of text that are |
| 1196 | listed, as Front-Cover Texts or Back-Cover Texts, in the notice |
| 1197 | that says that the Document is released under this License. A |
| 1198 | Front-Cover Text may be at most 5 words, and a Back-Cover Text may |
| 1199 | be at most 25 words. |
| 1200 | |
| 1201 | A "Transparent" copy of the Document means a machine-readable copy, |
| 1202 | represented in a format whose specification is available to the |
| 1203 | general public, that is suitable for revising the document |
| 1204 | straightforwardly with generic text editors or (for images |
| 1205 | composed of pixels) generic paint programs or (for drawings) some |
| 1206 | widely available drawing editor, and that is suitable for input to |
| 1207 | text formatters or for automatic translation to a variety of |
| 1208 | formats suitable for input to text formatters. A copy made in an |
| 1209 | otherwise Transparent file format whose markup, or absence of |
| 1210 | markup, has been arranged to thwart or discourage subsequent |
| 1211 | modification by readers is not Transparent. An image format is |
| 1212 | not Transparent if used for any substantial amount of text. A |
| 1213 | copy that is not "Transparent" is called "Opaque". |
| 1214 | |
| 1215 | Examples of suitable formats for Transparent copies include plain |
| 1216 | ASCII without markup, Texinfo input format, LaTeX input format, |
| 1217 | SGML or XML using a publicly available DTD, and |
| 1218 | standard-conforming simple HTML, PostScript or PDF designed for |
| 1219 | human modification. Examples of transparent image formats include |
| 1220 | PNG, XCF and JPG. Opaque formats include proprietary formats that |
| 1221 | can be read and edited only by proprietary word processors, SGML or |
| 1222 | XML for which the DTD and/or processing tools are not generally |
| 1223 | available, and the machine-generated HTML, PostScript or PDF |
| 1224 | produced by some word processors for output purposes only. |
| 1225 | |
| 1226 | The "Title Page" means, for a printed book, the title page itself, |
| 1227 | plus such following pages as are needed to hold, legibly, the |
| 1228 | material this License requires to appear in the title page. For |
| 1229 | works in formats which do not have any title page as such, "Title |
| 1230 | Page" means the text near the most prominent appearance of the |
| 1231 | work's title, preceding the beginning of the body of the text. |
| 1232 | |
| 1233 | A section "Entitled XYZ" means a named subunit of the Document |
| 1234 | whose title either is precisely XYZ or contains XYZ in parentheses |
| 1235 | following text that translates XYZ in another language. (Here XYZ |
| 1236 | stands for a specific section name mentioned below, such as |
| 1237 | "Acknowledgements", "Dedications", "Endorsements", or "History".) |
| 1238 | To "Preserve the Title" of such a section when you modify the |
| 1239 | Document means that it remains a section "Entitled XYZ" according |
| 1240 | to this definition. |
| 1241 | |
| 1242 | The Document may include Warranty Disclaimers next to the notice |
| 1243 | which states that this License applies to the Document. These |
| 1244 | Warranty Disclaimers are considered to be included by reference in |
| 1245 | this License, but only as regards disclaiming warranties: any other |
| 1246 | implication that these Warranty Disclaimers may have is void and |
| 1247 | has no effect on the meaning of this License. |
| 1248 | |
| 1249 | 2. VERBATIM COPYING |
| 1250 | |
| 1251 | You may copy and distribute the Document in any medium, either |
| 1252 | commercially or noncommercially, provided that this License, the |
| 1253 | copyright notices, and the license notice saying this License |
| 1254 | applies to the Document are reproduced in all copies, and that you |
| 1255 | add no other conditions whatsoever to those of this License. You |
| 1256 | may not use technical measures to obstruct or control the reading |
| 1257 | or further copying of the copies you make or distribute. However, |
| 1258 | you may accept compensation in exchange for copies. If you |
| 1259 | distribute a large enough number of copies you must also follow |
| 1260 | the conditions in section 3. |
| 1261 | |
| 1262 | You may also lend copies, under the same conditions stated above, |
| 1263 | and you may publicly display copies. |
| 1264 | |
| 1265 | 3. COPYING IN QUANTITY |
| 1266 | |
| 1267 | If you publish printed copies (or copies in media that commonly |
| 1268 | have printed covers) of the Document, numbering more than 100, and |
| 1269 | the Document's license notice requires Cover Texts, you must |
| 1270 | enclose the copies in covers that carry, clearly and legibly, all |
| 1271 | these Cover Texts: Front-Cover Texts on the front cover, and |
| 1272 | Back-Cover Texts on the back cover. Both covers must also clearly |
| 1273 | and legibly identify you as the publisher of these copies. The |
| 1274 | front cover must present the full title with all words of the |
| 1275 | title equally prominent and visible. You may add other material |
| 1276 | on the covers in addition. Copying with changes limited to the |
| 1277 | covers, as long as they preserve the title of the Document and |
| 1278 | satisfy these conditions, can be treated as verbatim copying in |
| 1279 | other respects. |
| 1280 | |
| 1281 | If the required texts for either cover are too voluminous to fit |
| 1282 | legibly, you should put the first ones listed (as many as fit |
| 1283 | reasonably) on the actual cover, and continue the rest onto |
| 1284 | adjacent pages. |
| 1285 | |
| 1286 | If you publish or distribute Opaque copies of the Document |
| 1287 | numbering more than 100, you must either include a |
| 1288 | machine-readable Transparent copy along with each Opaque copy, or |
| 1289 | state in or with each Opaque copy a computer-network location from |
| 1290 | which the general network-using public has access to download |
| 1291 | using public-standard network protocols a complete Transparent |
| 1292 | copy of the Document, free of added material. If you use the |
| 1293 | latter option, you must take reasonably prudent steps, when you |
| 1294 | begin distribution of Opaque copies in quantity, to ensure that |
| 1295 | this Transparent copy will remain thus accessible at the stated |
| 1296 | location until at least one year after the last time you |
| 1297 | distribute an Opaque copy (directly or through your agents or |
| 1298 | retailers) of that edition to the public. |
| 1299 | |
| 1300 | It is requested, but not required, that you contact the authors of |
| 1301 | the Document well before redistributing any large number of |
| 1302 | copies, to give them a chance to provide you with an updated |
| 1303 | version of the Document. |
| 1304 | |
| 1305 | 4. MODIFICATIONS |
| 1306 | |
| 1307 | You may copy and distribute a Modified Version of the Document |
| 1308 | under the conditions of sections 2 and 3 above, provided that you |
| 1309 | release the Modified Version under precisely this License, with |
| 1310 | the Modified Version filling the role of the Document, thus |
| 1311 | licensing distribution and modification of the Modified Version to |
| 1312 | whoever possesses a copy of it. In addition, you must do these |
| 1313 | things in the Modified Version: |
| 1314 | |
| 1315 | A. Use in the Title Page (and on the covers, if any) a title |
| 1316 | distinct from that of the Document, and from those of |
| 1317 | previous versions (which should, if there were any, be listed |
| 1318 | in the History section of the Document). You may use the |
| 1319 | same title as a previous version if the original publisher of |
| 1320 | that version gives permission. |
| 1321 | |
| 1322 | B. List on the Title Page, as authors, one or more persons or |
| 1323 | entities responsible for authorship of the modifications in |
| 1324 | the Modified Version, together with at least five of the |
| 1325 | principal authors of the Document (all of its principal |
| 1326 | authors, if it has fewer than five), unless they release you |
| 1327 | from this requirement. |
| 1328 | |
| 1329 | C. State on the Title page the name of the publisher of the |
| 1330 | Modified Version, as the publisher. |
| 1331 | |
| 1332 | D. Preserve all the copyright notices of the Document. |
| 1333 | |
| 1334 | E. Add an appropriate copyright notice for your modifications |
| 1335 | adjacent to the other copyright notices. |
| 1336 | |
| 1337 | F. Include, immediately after the copyright notices, a license |
| 1338 | notice giving the public permission to use the Modified |
| 1339 | Version under the terms of this License, in the form shown in |
| 1340 | the Addendum below. |
| 1341 | |
| 1342 | G. Preserve in that license notice the full lists of Invariant |
| 1343 | Sections and required Cover Texts given in the Document's |
| 1344 | license notice. |
| 1345 | |
| 1346 | H. Include an unaltered copy of this License. |
| 1347 | |
| 1348 | I. Preserve the section Entitled "History", Preserve its Title, |
| 1349 | and add to it an item stating at least the title, year, new |
| 1350 | authors, and publisher of the Modified Version as given on |
| 1351 | the Title Page. If there is no section Entitled "History" in |
| 1352 | the Document, create one stating the title, year, authors, |
| 1353 | and publisher of the Document as given on its Title Page, |
| 1354 | then add an item describing the Modified Version as stated in |
| 1355 | the previous sentence. |
| 1356 | |
| 1357 | J. Preserve the network location, if any, given in the Document |
| 1358 | for public access to a Transparent copy of the Document, and |
| 1359 | likewise the network locations given in the Document for |
| 1360 | previous versions it was based on. These may be placed in |
| 1361 | the "History" section. You may omit a network location for a |
| 1362 | work that was published at least four years before the |
| 1363 | Document itself, or if the original publisher of the version |
| 1364 | it refers to gives permission. |
| 1365 | |
| 1366 | K. For any section Entitled "Acknowledgements" or "Dedications", |
| 1367 | Preserve the Title of the section, and preserve in the |
| 1368 | section all the substance and tone of each of the contributor |
| 1369 | acknowledgements and/or dedications given therein. |
| 1370 | |
| 1371 | L. Preserve all the Invariant Sections of the Document, |
| 1372 | unaltered in their text and in their titles. Section numbers |
| 1373 | or the equivalent are not considered part of the section |
| 1374 | titles. |
| 1375 | |
| 1376 | M. Delete any section Entitled "Endorsements". Such a section |
| 1377 | may not be included in the Modified Version. |
| 1378 | |
| 1379 | N. Do not retitle any existing section to be Entitled |
| 1380 | "Endorsements" or to conflict in title with any Invariant |
| 1381 | Section. |
| 1382 | |
| 1383 | O. Preserve any Warranty Disclaimers. |
| 1384 | |
| 1385 | If the Modified Version includes new front-matter sections or |
| 1386 | appendices that qualify as Secondary Sections and contain no |
| 1387 | material copied from the Document, you may at your option |
| 1388 | designate some or all of these sections as invariant. To do this, |
| 1389 | add their titles to the list of Invariant Sections in the Modified |
| 1390 | Version's license notice. These titles must be distinct from any |
| 1391 | other section titles. |
| 1392 | |
| 1393 | You may add a section Entitled "Endorsements", provided it contains |
| 1394 | nothing but endorsements of your Modified Version by various |
| 1395 | parties--for example, statements of peer review or that the text |
| 1396 | has been approved by an organization as the authoritative |
| 1397 | definition of a standard. |
| 1398 | |
| 1399 | You may add a passage of up to five words as a Front-Cover Text, |
| 1400 | and a passage of up to 25 words as a Back-Cover Text, to the end |
| 1401 | of the list of Cover Texts in the Modified Version. Only one |
| 1402 | passage of Front-Cover Text and one of Back-Cover Text may be |
| 1403 | added by (or through arrangements made by) any one entity. If the |
| 1404 | Document already includes a cover text for the same cover, |
| 1405 | previously added by you or by arrangement made by the same entity |
| 1406 | you are acting on behalf of, you may not add another; but you may |
| 1407 | replace the old one, on explicit permission from the previous |
| 1408 | publisher that added the old one. |
| 1409 | |
| 1410 | The author(s) and publisher(s) of the Document do not by this |
| 1411 | License give permission to use their names for publicity for or to |
| 1412 | assert or imply endorsement of any Modified Version. |
| 1413 | |
| 1414 | 5. COMBINING DOCUMENTS |
| 1415 | |
| 1416 | You may combine the Document with other documents released under |
| 1417 | this License, under the terms defined in section 4 above for |
| 1418 | modified versions, provided that you include in the combination |
| 1419 | all of the Invariant Sections of all of the original documents, |
| 1420 | unmodified, and list them all as Invariant Sections of your |
| 1421 | combined work in its license notice, and that you preserve all |
| 1422 | their Warranty Disclaimers. |
| 1423 | |
| 1424 | The combined work need only contain one copy of this License, and |
| 1425 | multiple identical Invariant Sections may be replaced with a single |
| 1426 | copy. If there are multiple Invariant Sections with the same name |
| 1427 | but different contents, make the title of each such section unique |
| 1428 | by adding at the end of it, in parentheses, the name of the |
| 1429 | original author or publisher of that section if known, or else a |
| 1430 | unique number. Make the same adjustment to the section titles in |
| 1431 | the list of Invariant Sections in the license notice of the |
| 1432 | combined work. |
| 1433 | |
| 1434 | In the combination, you must combine any sections Entitled |
| 1435 | "History" in the various original documents, forming one section |
| 1436 | Entitled "History"; likewise combine any sections Entitled |
| 1437 | "Acknowledgements", and any sections Entitled "Dedications". You |
| 1438 | must delete all sections Entitled "Endorsements." |
| 1439 | |
| 1440 | 6. COLLECTIONS OF DOCUMENTS |
| 1441 | |
| 1442 | You may make a collection consisting of the Document and other |
| 1443 | documents released under this License, and replace the individual |
| 1444 | copies of this License in the various documents with a single copy |
| 1445 | that is included in the collection, provided that you follow the |
| 1446 | rules of this License for verbatim copying of each of the |
| 1447 | documents in all other respects. |
| 1448 | |
| 1449 | You may extract a single document from such a collection, and |
| 1450 | distribute it individually under this License, provided you insert |
| 1451 | a copy of this License into the extracted document, and follow |
| 1452 | this License in all other respects regarding verbatim copying of |
| 1453 | that document. |
| 1454 | |
| 1455 | 7. AGGREGATION WITH INDEPENDENT WORKS |
| 1456 | |
| 1457 | A compilation of the Document or its derivatives with other |
| 1458 | separate and independent documents or works, in or on a volume of |
| 1459 | a storage or distribution medium, is called an "aggregate" if the |
| 1460 | copyright resulting from the compilation is not used to limit the |
| 1461 | legal rights of the compilation's users beyond what the individual |
| 1462 | works permit. When the Document is included an aggregate, this |
| 1463 | License does not apply to the other works in the aggregate which |
| 1464 | are not themselves derivative works of the Document. |
| 1465 | |
| 1466 | If the Cover Text requirement of section 3 is applicable to these |
| 1467 | copies of the Document, then if the Document is less than one half |
| 1468 | of the entire aggregate, the Document's Cover Texts may be placed |
| 1469 | on covers that bracket the Document within the aggregate, or the |
| 1470 | electronic equivalent of covers if the Document is in electronic |
| 1471 | form. Otherwise they must appear on printed covers that bracket |
| 1472 | the whole aggregate. |
| 1473 | |
| 1474 | 8. TRANSLATION |
| 1475 | |
| 1476 | Translation is considered a kind of modification, so you may |
| 1477 | distribute translations of the Document under the terms of section |
| 1478 | 4. Replacing Invariant Sections with translations requires special |
| 1479 | permission from their copyright holders, but you may include |
| 1480 | translations of some or all Invariant Sections in addition to the |
| 1481 | original versions of these Invariant Sections. You may include a |
| 1482 | translation of this License, and all the license notices in the |
| 1483 | Document, and any Warrany Disclaimers, provided that you also |
| 1484 | include the original English version of this License and the |
| 1485 | original versions of those notices and disclaimers. In case of a |
| 1486 | disagreement between the translation and the original version of |
| 1487 | this License or a notice or disclaimer, the original version will |
| 1488 | prevail. |
| 1489 | |
| 1490 | If a section in the Document is Entitled "Acknowledgements", |
| 1491 | "Dedications", or "History", the requirement (section 4) to |
| 1492 | Preserve its Title (section 1) will typically require changing the |
| 1493 | actual title. |
| 1494 | |
| 1495 | 9. TERMINATION |
| 1496 | |
| 1497 | You may not copy, modify, sublicense, or distribute the Document |
| 1498 | except as expressly provided for under this License. Any other |
| 1499 | attempt to copy, modify, sublicense or distribute the Document is |
| 1500 | void, and will automatically terminate your rights under this |
| 1501 | License. However, parties who have received copies, or rights, |
| 1502 | from you under this License will not have their licenses |
| 1503 | terminated so long as such parties remain in full compliance. |
| 1504 | |
| 1505 | 10. FUTURE REVISIONS OF THIS LICENSE |
| 1506 | |
| 1507 | The Free Software Foundation may publish new, revised versions of |
| 1508 | the GNU Free Documentation License from time to time. Such new |
| 1509 | versions will be similar in spirit to the present version, but may |
| 1510 | differ in detail to address new problems or concerns. See |
| 1511 | `http://www.gnu.org/copyleft/'. |
| 1512 | |
| 1513 | Each version of the License is given a distinguishing version |
| 1514 | number. If the Document specifies that a particular numbered |
| 1515 | version of this License "or any later version" applies to it, you |
| 1516 | have the option of following the terms and conditions either of |
| 1517 | that specified version or of any later version that has been |
| 1518 | published (not as a draft) by the Free Software Foundation. If |
| 1519 | the Document does not specify a version number of this License, |
| 1520 | you may choose any version ever published (not as a draft) by the |
| 1521 | Free Software Foundation. |
| 1522 | |
| 1523 | A.1.1 ADDENDUM: How to use this License for your documents |
| 1524 | ---------------------------------------------------------- |
| 1525 | |
| 1526 | To use this License in a document you have written, include a copy of |
| 1527 | the License in the document and put the following copyright and license |
| 1528 | notices just after the title page: |
| 1529 | |
| 1530 | Copyright (C) YEAR YOUR NAME. |
| 1531 | Permission is granted to copy, distribute and/or modify this document |
| 1532 | under the terms of the GNU Free Documentation License, Version 1.2 |
| 1533 | or any later version published by the Free Software Foundation; |
| 1534 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. |
| 1535 | A copy of the license is included in the section entitled ``GNU |
| 1536 | Free Documentation License''. |
| 1537 | |
| 1538 | If you have Invariant Sections, Front-Cover Texts and Back-Cover |
| 1539 | Texts, replace the "with...Texts." line with this: |
| 1540 | |
| 1541 | with the Invariant Sections being LIST THEIR TITLES, with |
| 1542 | the Front-Cover Texts being LIST, and with the Back-Cover Texts |
| 1543 | being LIST. |
| 1544 | |
| 1545 | If you have Invariant Sections without Cover Texts, or some other |
| 1546 | combination of the three, merge those two alternatives to suit the |
| 1547 | situation. |
| 1548 | |
| 1549 | If your document contains nontrivial examples of program code, we |
| 1550 | recommend releasing these examples in parallel under your choice of |
| 1551 | free software license, such as the GNU General Public License, to |
| 1552 | permit their use in free software. |
| 1553 | |
| 1554 | |
| 1555 | File: commoncpp2.info, Node: GNU General Public License, Next: GNU Common C++ Linking Exception, Prev: GNU Free Documentation License, Up: Licenses |
| 1556 | |
| 1557 | A.2 GNU GENERAL PUBLIC LICENSE |
| 1558 | ============================== |
| 1559 | |
| 1560 | Version 2, June 1991 |
| 1561 | |
| 1562 | Copyright (C) 1989, 1991 Free Software Foundation, Inc. |
| 1563 | 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA |
| 1564 | |
| 1565 | Everyone is permitted to copy and distribute verbatim copies |
| 1566 | of this license document, but changing it is not allowed. |
| 1567 | |
| 1568 | A.2.1 Preamble |
| 1569 | -------------- |
| 1570 | |
| 1571 | The licenses for most software are designed to take away your freedom |
| 1572 | to share and change it. By contrast, the GNU General Public License is |
| 1573 | intended to guarantee your freedom to share and change free |
| 1574 | software--to make sure the software is free for all its users. This |
| 1575 | General Public License applies to most of the Free Software |
| 1576 | Foundation's software and to any other program whose authors commit to |
| 1577 | using it. (Some other Free Software Foundation software is covered by |
| 1578 | the GNU Library General Public License instead.) You can apply it to |
| 1579 | your programs, too. |
| 1580 | |
| 1581 | When we speak of free software, we are referring to freedom, not |
| 1582 | price. Our General Public Licenses are designed to make sure that you |
| 1583 | have the freedom to distribute copies of free software (and charge for |
| 1584 | this service if you wish), that you receive source code or can get it |
| 1585 | if you want it, that you can change the software or use pieces of it in |
| 1586 | new free programs; and that you know you can do these things. |
| 1587 | |
| 1588 | To protect your rights, we need to make restrictions that forbid |
| 1589 | anyone to deny you these rights or to ask you to surrender the rights. |
| 1590 | These restrictions translate to certain responsibilities for you if you |
| 1591 | distribute copies of the software, or if you modify it. |
| 1592 | |
| 1593 | For example, if you distribute copies of such a program, whether |
| 1594 | gratis or for a fee, you must give the recipients all the rights that |
| 1595 | you have. You must make sure that they, too, receive or can get the |
| 1596 | source code. And you must show them these terms so they know their |
| 1597 | rights. |
| 1598 | |
| 1599 | We protect your rights with two steps: (1) copyright the software, |
| 1600 | and (2) offer you this license which gives you legal permission to copy, |
| 1601 | distribute and/or modify the software. |
| 1602 | |
| 1603 | Also, for each author's protection and ours, we want to make certain |
| 1604 | that everyone understands that there is no warranty for this free |
| 1605 | software. If the software is modified by someone else and passed on, we |
| 1606 | want its recipients to know that what they have is not the original, so |
| 1607 | that any problems introduced by others will not reflect on the original |
| 1608 | authors' reputations. |
| 1609 | |
| 1610 | Finally, any free program is threatened constantly by software |
| 1611 | patents. We wish to avoid the danger that redistributors of a free |
| 1612 | program will individually obtain patent licenses, in effect making the |
| 1613 | program proprietary. To prevent this, we have made it clear that any |
| 1614 | patent must be licensed for everyone's free use or not licensed at all. |
| 1615 | |
| 1616 | The precise terms and conditions for copying, distribution and |
| 1617 | modification follow. |
| 1618 | |
| 1619 | TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION |
| 1620 | 0. This License applies to any program or other work which contains a |
| 1621 | notice placed by the copyright holder saying it may be distributed |
| 1622 | under the terms of this General Public License. The "Program", |
| 1623 | below, refers to any such program or work, and a "work based on |
| 1624 | the Program" means either the Program or any derivative work under |
| 1625 | copyright law: that is to say, a work containing the Program or a |
| 1626 | portion of it, either verbatim or with modifications and/or |
| 1627 | translated into another language. (Hereinafter, translation is |
| 1628 | included without limitation in the term "modification".) Each |
| 1629 | licensee is addressed as "you". |
| 1630 | |
| 1631 | Activities other than copying, distribution and modification are |
| 1632 | not covered by this License; they are outside its scope. The act |
| 1633 | of running the Program is not restricted, and the output from the |
| 1634 | Program is covered only if its contents constitute a work based on |
| 1635 | the Program (independent of having been made by running the |
| 1636 | Program). Whether that is true depends on what the Program does. |
| 1637 | |
| 1638 | 1. You may copy and distribute verbatim copies of the Program's |
| 1639 | source code as you receive it, in any medium, provided that you |
| 1640 | conspicuously and appropriately publish on each copy an appropriate |
| 1641 | copyright notice and disclaimer of warranty; keep intact all the |
| 1642 | notices that refer to this License and to the absence of any |
| 1643 | warranty; and give any other recipients of the Program a copy of |
| 1644 | this License along with the Program. |
| 1645 | |
| 1646 | You may charge a fee for the physical act of transferring a copy, |
| 1647 | and you may at your option offer warranty protection in exchange |
| 1648 | for a fee. |
| 1649 | |
| 1650 | 2. You may modify your copy or copies of the Program or any portion |
| 1651 | of it, thus forming a work based on the Program, and copy and |
| 1652 | distribute such modifications or work under the terms of Section 1 |
| 1653 | above, provided that you also meet all of these conditions: |
| 1654 | |
| 1655 | a. You must cause the modified files to carry prominent notices |
| 1656 | stating that you changed the files and the date of any change. |
| 1657 | |
| 1658 | b. You must cause any work that you distribute or publish, that |
| 1659 | in whole or in part contains or is derived from the Program |
| 1660 | or any part thereof, to be licensed as a whole at no charge |
| 1661 | to all third parties under the terms of this License. |
| 1662 | |
| 1663 | c. If the modified program normally reads commands interactively |
| 1664 | when run, you must cause it, when started running for such |
| 1665 | interactive use in the most ordinary way, to print or display |
| 1666 | an announcement including an appropriate copyright notice and |
| 1667 | a notice that there is no warranty (or else, saying that you |
| 1668 | provide a warranty) and that users may redistribute the |
| 1669 | program under these conditions, and telling the user how to |
| 1670 | view a copy of this License. (Exception: if the Program |
| 1671 | itself is interactive but does not normally print such an |
| 1672 | announcement, your work based on the Program is not required |
| 1673 | to print an announcement.) |
| 1674 | |
| 1675 | These requirements apply to the modified work as a whole. If |
| 1676 | identifiable sections of that work are not derived from the |
| 1677 | Program, and can be reasonably considered independent and separate |
| 1678 | works in themselves, then this License, and its terms, do not |
| 1679 | apply to those sections when you distribute them as separate |
| 1680 | works. But when you distribute the same sections as part of a |
| 1681 | whole which is a work based on the Program, the distribution of |
| 1682 | the whole must be on the terms of this License, whose permissions |
| 1683 | for other licensees extend to the entire whole, and thus to each |
| 1684 | and every part regardless of who wrote it. |
| 1685 | |
| 1686 | Thus, it is not the intent of this section to claim rights or |
| 1687 | contest your rights to work written entirely by you; rather, the |
| 1688 | intent is to exercise the right to control the distribution of |
| 1689 | derivative or collective works based on the Program. |
| 1690 | |
| 1691 | In addition, mere aggregation of another work not based on the |
| 1692 | Program with the Program (or with a work based on the Program) on |
| 1693 | a volume of a storage or distribution medium does not bring the |
| 1694 | other work under the scope of this License. |
| 1695 | |
| 1696 | 3. You may copy and distribute the Program (or a work based on it, |
| 1697 | under Section 2) in object code or executable form under the terms |
| 1698 | of Sections 1 and 2 above provided that you also do one of the |
| 1699 | following: |
| 1700 | |
| 1701 | a. Accompany it with the complete corresponding machine-readable |
| 1702 | source code, which must be distributed under the terms of |
| 1703 | Sections 1 and 2 above on a medium customarily used for |
| 1704 | software interchange; or, |
| 1705 | |
| 1706 | b. Accompany it with a written offer, valid for at least three |
| 1707 | years, to give any third party, for a charge no more than your |
| 1708 | cost of physically performing source distribution, a complete |
| 1709 | machine-readable copy of the corresponding source code, to be |
| 1710 | distributed under the terms of Sections 1 and 2 above on a |
| 1711 | medium customarily used for software interchange; or, |
| 1712 | |
| 1713 | c. Accompany it with the information you received as to the offer |
| 1714 | to distribute corresponding source code. (This alternative is |
| 1715 | allowed only for noncommercial distribution and only if you |
| 1716 | received the program in object code or executable form with |
| 1717 | such an offer, in accord with Subsection b above.) |
| 1718 | |
| 1719 | The source code for a work means the preferred form of the work for |
| 1720 | making modifications to it. For an executable work, complete |
| 1721 | source code means all the source code for all modules it contains, |
| 1722 | plus any associated interface definition files, plus the scripts |
| 1723 | used to control compilation and installation of the executable. |
| 1724 | However, as a special exception, the source code distributed need |
| 1725 | not include anything that is normally distributed (in either |
| 1726 | source or binary form) with the major components (compiler, |
| 1727 | kernel, and so on) of the operating system on which the executable |
| 1728 | runs, unless that component itself accompanies the executable. |
| 1729 | |
| 1730 | If distribution of executable or object code is made by offering |
| 1731 | access to copy from a designated place, then offering equivalent |
| 1732 | access to copy the source code from the same place counts as |
| 1733 | distribution of the source code, even though third parties are not |
| 1734 | compelled to copy the source along with the object code. |
| 1735 | |
| 1736 | 4. You may not copy, modify, sublicense, or distribute the Program |
| 1737 | except as expressly provided under this License. Any attempt |
| 1738 | otherwise to copy, modify, sublicense or distribute the Program is |
| 1739 | void, and will automatically terminate your rights under this |
| 1740 | License. However, parties who have received copies, or rights, |
| 1741 | from you under this License will not have their licenses |
| 1742 | terminated so long as such parties remain in full compliance. |
| 1743 | |
| 1744 | 5. You are not required to accept this License, since you have not |
| 1745 | signed it. However, nothing else grants you permission to modify |
| 1746 | or distribute the Program or its derivative works. These actions |
| 1747 | are prohibited by law if you do not accept this License. |
| 1748 | Therefore, by modifying or distributing the Program (or any work |
| 1749 | based on the Program), you indicate your acceptance of this |
| 1750 | License to do so, and all its terms and conditions for copying, |
| 1751 | distributing or modifying the Program or works based on it. |
| 1752 | |
| 1753 | 6. Each time you redistribute the Program (or any work based on the |
| 1754 | Program), the recipient automatically receives a license from the |
| 1755 | original licensor to copy, distribute or modify the Program |
| 1756 | subject to these terms and conditions. You may not impose any |
| 1757 | further restrictions on the recipients' exercise of the rights |
| 1758 | granted herein. You are not responsible for enforcing compliance |
| 1759 | by third parties to this License. |
| 1760 | |
| 1761 | 7. If, as a consequence of a court judgment or allegation of patent |
| 1762 | infringement or for any other reason (not limited to patent |
| 1763 | issues), conditions are imposed on you (whether by court order, |
| 1764 | agreement or otherwise) that contradict the conditions of this |
| 1765 | License, they do not excuse you from the conditions of this |
| 1766 | License. If you cannot distribute so as to satisfy simultaneously |
| 1767 | your obligations under this License and any other pertinent |
| 1768 | obligations, then as a consequence you may not distribute the |
| 1769 | Program at all. For example, if a patent license would not permit |
| 1770 | royalty-free redistribution of the Program by all those who |
| 1771 | receive copies directly or indirectly through you, then the only |
| 1772 | way you could satisfy both it and this License would be to refrain |
| 1773 | entirely from distribution of the Program. |
| 1774 | |
| 1775 | If any portion of this section is held invalid or unenforceable |
| 1776 | under any particular circumstance, the balance of the section is |
| 1777 | intended to apply and the section as a whole is intended to apply |
| 1778 | in other circumstances. |
| 1779 | |
| 1780 | It is not the purpose of this section to induce you to infringe any |
| 1781 | patents or other property right claims or to contest validity of |
| 1782 | any such claims; this section has the sole purpose of protecting |
| 1783 | the integrity of the free software distribution system, which is |
| 1784 | implemented by public license practices. Many people have made |
| 1785 | generous contributions to the wide range of software distributed |
| 1786 | through that system in reliance on consistent application of that |
| 1787 | system; it is up to the author/donor to decide if he or she is |
| 1788 | willing to distribute software through any other system and a |
| 1789 | licensee cannot impose that choice. |
| 1790 | |
| 1791 | This section is intended to make thoroughly clear what is believed |
| 1792 | to be a consequence of the rest of this License. |
| 1793 | |
| 1794 | 8. If the distribution and/or use of the Program is restricted in |
| 1795 | certain countries either by patents or by copyrighted interfaces, |
| 1796 | the original copyright holder who places the Program under this |
| 1797 | License may add an explicit geographical distribution limitation |
| 1798 | excluding those countries, so that distribution is permitted only |
| 1799 | in or among countries not thus excluded. In such case, this |
| 1800 | License incorporates the limitation as if written in the body of |
| 1801 | this License. |
| 1802 | |
| 1803 | 9. The Free Software Foundation may publish revised and/or new |
| 1804 | versions of the General Public License from time to time. Such |
| 1805 | new versions will be similar in spirit to the present version, but |
| 1806 | may differ in detail to address new problems or concerns. |
| 1807 | |
| 1808 | Each version is given a distinguishing version number. If the |
| 1809 | Program specifies a version number of this License which applies |
| 1810 | to it and "any later version", you have the option of following |
| 1811 | the terms and conditions either of that version or of any later |
| 1812 | version published by the Free Software Foundation. If the Program |
| 1813 | does not specify a version number of this License, you may choose |
| 1814 | any version ever published by the Free Software Foundation. |
| 1815 | |
| 1816 | 10. If you wish to incorporate parts of the Program into other free |
| 1817 | programs whose distribution conditions are different, write to the |
| 1818 | author to ask for permission. For software which is copyrighted |
| 1819 | by the Free Software Foundation, write to the Free Software |
| 1820 | Foundation; we sometimes make exceptions for this. Our decision |
| 1821 | will be guided by the two goals of preserving the free status of |
| 1822 | all derivatives of our free software and of promoting the sharing |
| 1823 | and reuse of software generally. |
| 1824 | |
| 1825 | NO WARRANTY |
| 1826 | 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO |
| 1827 | WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE |
| 1828 | LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT |
| 1829 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT |
| 1830 | WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT |
| 1831 | NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND |
| 1832 | FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE |
| 1833 | QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE |
| 1834 | PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY |
| 1835 | SERVICING, REPAIR OR CORRECTION. |
| 1836 | |
| 1837 | 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN |
| 1838 | WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY |
| 1839 | MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE |
| 1840 | LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, |
| 1841 | INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR |
| 1842 | INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF |
| 1843 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU |
| 1844 | OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY |
| 1845 | OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN |
| 1846 | ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. |
| 1847 | |
| 1848 | END OF TERMS AND CONDITIONS |
| 1849 | A.2.2 Appendix: How to Apply These Terms to Your New Programs |
| 1850 | ------------------------------------------------------------- |
| 1851 | |
| 1852 | If you develop a new program, and you want it to be of the greatest |
| 1853 | possible use to the public, the best way to achieve this is to make it |
| 1854 | free software which everyone can redistribute and change under these |
| 1855 | terms. |
| 1856 | |
| 1857 | To do so, attach the following notices to the program. It is safest |
| 1858 | to attach them to the start of each source file to most effectively |
| 1859 | convey the exclusion of warranty; and each file should have at least |
| 1860 | the "copyright" line and a pointer to where the full notice is found. |
| 1861 | |
| 1862 | ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. |
| 1863 | Copyright (C) YYYY NAME OF AUTHOR |
| 1864 | |
| 1865 | This program is free software; you can redistribute it and/or modify |
| 1866 | it under the terms of the GNU General Public License as published by |
| 1867 | the Free Software Foundation; either version 2 of the License, or |
| 1868 | (at your option) any later version. |
| 1869 | |
| 1870 | This program is distributed in the hope that it will be useful, |
| 1871 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 1872 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 1873 | GNU General Public License for more details. |
| 1874 | |
| 1875 | You should have received a copy of the GNU General Public License |
| 1876 | along with this program; if not, write to the Free Software |
| 1877 | Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
| 1878 | |
| 1879 | Also add information on how to contact you by electronic and paper |
| 1880 | mail. |
| 1881 | |
| 1882 | If the program is interactive, make it output a short notice like |
| 1883 | this when it starts in an interactive mode: |
| 1884 | |
| 1885 | Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR |
| 1886 | Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. |
| 1887 | This is free software, and you are welcome to redistribute it |
| 1888 | under certain conditions; type `show c' for details. |
| 1889 | |
| 1890 | The hypothetical commands `show w' and `show c' should show the |
| 1891 | appropriate parts of the General Public License. Of course, the |
| 1892 | commands you use may be called something other than `show w' and `show |
| 1893 | c'; they could even be mouse-clicks or menu items--whatever suits your |
| 1894 | program. |
| 1895 | |
| 1896 | You should also get your employer (if you work as a programmer) or |
| 1897 | your school, if any, to sign a "copyright disclaimer" for the program, |
| 1898 | if necessary. Here is a sample; alter the names: |
| 1899 | |
| 1900 | Yoyodyne, Inc., hereby disclaims all copyright interest in the program |
| 1901 | `Gnomovision' (which makes passes at compilers) written by James Hacker. |
| 1902 | |
| 1903 | SIGNATURE OF TY COON, 1 April 1989 |
| 1904 | Ty Coon, President of Vice |
| 1905 | |
| 1906 | This General Public License does not permit incorporating your |
| 1907 | program into proprietary programs. If your program is a subroutine |
| 1908 | library, you may consider it more useful to permit linking proprietary |
| 1909 | applications with the library. If this is what you want to do, use the |
| 1910 | GNU Library General Public License instead of this License. |
| 1911 | |
| 1912 | |
| 1913 | File: commoncpp2.info, Node: GNU Common C++ Linking Exception, Prev: GNU General Public License, Up: Licenses |
| 1914 | |
| 1915 | A.3 GNU Common C++ Linking Exception |
| 1916 | ==================================== |
| 1917 | |
| 1918 | As a special exception to the GNU General Public License, permission is |
| 1919 | granted for additional uses of the text contained in its release of |
| 1920 | Common C++. |
| 1921 | |
| 1922 | The exception is that, if you link the Common C++ library with other |
| 1923 | files to produce an executable, this does not by itself cause the |
| 1924 | resulting executable to be covered by the GNU General Public License. |
| 1925 | Your use of that executable is in no way restricted on account of |
| 1926 | linking the Common C++ library code into it. |
| 1927 | |
| 1928 | This exception does not however invalidate any other reasons why the |
| 1929 | executable file might be covered by the GNU General Public License. |
| 1930 | |
| 1931 | This exception applies only to the code released under the name |
| 1932 | Common C++. If you copy code from other releases into a copy of Common |
| 1933 | C++, as the General Public License permits, the exception does not |
| 1934 | apply to the code that you add in this way. To avoid misleading anyone |
| 1935 | as to the status of such modified files, you must delete this exception |
| 1936 | notice from them. |
| 1937 | |
| 1938 | If you write modifications of your own for Common C++, it is your |
| 1939 | choice whether to permit this exception to apply to your modifications. |
| 1940 | If you do not wish that, delete this exception notice. |
| 1941 | |
| 1942 | |
| 1943 | File: commoncpp2.info, Node: Class and Data Type Index, Next: Method and Function Index, Prev: Licenses, Up: Top |
| 1944 | |
| 1945 | Class and Data Type Index |
| 1946 | ************************* |
| 1947 | |
| 1948 | [index] |
| 1949 | * Menu: |
| 1950 | |
| 1951 | * AtomicCounter: Synchronization. (line 54) |
| 1952 | * BroadcastAddress: Sockets. (line 11) |
| 1953 | * cistring: Templates. (line 6) |
| 1954 | * Counter: Templates. (line 6) |
| 1955 | * cstring: Templates. (line 6) |
| 1956 | * Date: Numbers and Dates. (line 6) |
| 1957 | * DateNumber: Numbers and Dates. (line 6) |
| 1958 | * DirException: Exceptions. (line 9) |
| 1959 | * DSOException: Exceptions. (line 9) |
| 1960 | * Event: Synchronization. (line 48) |
| 1961 | * Exception: Exceptions. (line 6) |
| 1962 | * FIFOException: Exceptions. (line 9) |
| 1963 | * FileException: Exceptions. (line 9) |
| 1964 | * FTPException: Exceptions. (line 9) |
| 1965 | * InetAddress: Sockets. (line 11) |
| 1966 | * InetHostAddress: Sockets. (line 11) |
| 1967 | * InetMaskAddress: Sockets. (line 11) |
| 1968 | * IOException: Exceptions. (line 9) |
| 1969 | * Keydata: Configuration and Misc.. |
| 1970 | (line 13) |
| 1971 | * keyMap]: Templates. (line 6) |
| 1972 | * MappedFile: Block I/O. (line 27) |
| 1973 | * MemPager: Configuration and Misc.. |
| 1974 | (line 6) |
| 1975 | * Mutex: Synchronization. (line 11) |
| 1976 | * Number: Numbers and Dates. (line 6) |
| 1977 | * objCounter: Templates. (line 6) |
| 1978 | * objList: Templates. (line 6) |
| 1979 | * objMap: Templates. (line 6) |
| 1980 | * objSync: Templates. (line 6) |
| 1981 | * Persistence::BaseObject: Persistence. (line 13) |
| 1982 | * PersistException: Exceptions. (line 9) |
| 1983 | * PipeException: Exceptions. (line 9) |
| 1984 | * Pointer: Templates. (line 6) |
| 1985 | * RandomFile: Block I/O. (line 6) |
| 1986 | * Semaphore: Synchronization. (line 41) |
| 1987 | * SerException: Exceptions. (line 9) |
| 1988 | * SharedFile: Block I/O. (line 22) |
| 1989 | * Slog: Daemons. (line 11) |
| 1990 | * Socket: Sockets. (line 21) |
| 1991 | * SocketPort: Sockets. (line 73) |
| 1992 | * SocketService: Sockets. (line 73) |
| 1993 | * SockException: Exceptions. (line 9) |
| 1994 | * std::exception: Exceptions. (line 6) |
| 1995 | * TCPSession: Threading Concepts. (line 138) |
| 1996 | * TCPStream <1>: Sockets. (line 28) |
| 1997 | * TCPStream: Threading Concepts. (line 138) |
| 1998 | * Thread: Threading Concepts. (line 37) |
| 1999 | * ThreadFile: Block I/O. (line 13) |
| 2000 | * ThreadKey: Synchronization. (line 54) |
| 2001 | * ThreadLock: Synchronization. (line 32) |
| 2002 | * ThrException: Exceptions. (line 9) |
| 2003 | * TTYPort: Serial I/O. (line 42) |
| 2004 | * TTYService: Serial I/O. (line 42) |
| 2005 | * TTYSession: Serial I/O. (line 37) |
| 2006 | * ttystream: Serial I/O. (line 28) |
| 2007 | * TTYStream: Serial I/O. (line 28) |
| 2008 | * UDPBroadcast: Sockets. (line 60) |
| 2009 | * UDPDuplex: Sockets. (line 65) |
| 2010 | * UDPSocket: Sockets. (line 51) |
| 2011 | * URLStream: URL Streams. (line 6) |
| 2012 | * XMLRPC: XML Streams and RPC. (line 6) |
| 2013 | * XMLStream: XML Streams and RPC. (line 6) |
| 2014 | * ZNumber: Numbers and Dates. (line 6) |
| 2015 | |
| 2016 | |
| 2017 | File: commoncpp2.info, Node: Method and Function Index, Next: Concept Index, Prev: Class and Data Type Index, Up: Top |
| 2018 | |
| 2019 | Method and Function Index |
| 2020 | ************************* |
| 2021 | |
| 2022 | [index] |
| 2023 | * Menu: |
| 2024 | |
| 2025 | * abs: Templates. (line 6) |
| 2026 | * b64Decode: URL Streams. (line 15) |
| 2027 | * b64Encode: URL Streams. (line 17) |
| 2028 | * DECLARE_PERSISTENCE: Persistence. (line 13) |
| 2029 | * getThread: Threading Concepts. (line 99) |
| 2030 | * IMPLEMENT_PERSISTENCE: Persistence. (line 13) |
| 2031 | * MappedFile::sync: Block I/O. (line 27) |
| 2032 | * operator new: Threading Concepts. (line 92) |
| 2033 | * pdetach: Daemons. (line 6) |
| 2034 | * pwread: Block I/O. (line 13) |
| 2035 | * pwwrite: Block I/O. (line 13) |
| 2036 | * Slog::operator<<: Daemons. (line 11) |
| 2037 | * TCPSocket::onAccept: Sockets. (line 45) |
| 2038 | * TCPStream::operator<<: Sockets. (line 28) |
| 2039 | * TCPStream::operator>>: Sockets. (line 28) |
| 2040 | * Thread::exit: Threading Concepts. (line 66) |
| 2041 | * Thread::final: Threading Concepts. (line 92) |
| 2042 | * Thread::onDisconnect: Threading Concepts. (line 124) |
| 2043 | * Thread::onHangup: Threading Concepts. (line 124) |
| 2044 | * Thread::run: Threading Concepts. (line 37) |
| 2045 | * Thread::setCancellation: Threading Concepts. (line 66) |
| 2046 | * Thread::signal: Threading Concepts. (line 124) |
| 2047 | * Thread::terminate: Threading Concepts. (line 74) |
| 2048 | * TTYStream::operator<<: Serial I/O. (line 28) |
| 2049 | * TTYStream::operator>>: Serial I/O. (line 28) |
| 2050 | * urlDecode: URL Streams. (line 11) |
| 2051 | * urlEncode: URL Streams. (line 13) |
| 2052 | * URLStream: URL Streams. (line 9) |
| 2053 | |
| 2054 | |
| 2055 | File: commoncpp2.info, Node: Concept Index, Prev: Method and Function Index, Up: Top |
| 2056 | |
| 2057 | Concept Index |
| 2058 | ************* |
| 2059 | |
| 2060 | [index] |
| 2061 | * Menu: |
| 2062 | |
| 2063 | * APE: Threading Concepts. (line 6) |
| 2064 | * autoconf <1>: Compiler Options. (line 6) |
| 2065 | * autoconf: Threading Concepts. (line 14) |
| 2066 | * automake: Compiler Options. (line 6) |
| 2067 | * automake macros: Automake Services. (line 6) |
| 2068 | * automake services: Automake Services. (line 6) |
| 2069 | * Automake Services: Automake Services. (line 6) |
| 2070 | * Block I/O: Block I/O. (line 6) |
| 2071 | * cancelable threads: Threading Concepts. (line 61) |
| 2072 | * cancellation: Threading Concepts. (line 66) |
| 2073 | * cancellation point: Threading Concepts. (line 66) |
| 2074 | * ccgnu2-config: Compiler Options. (line 6) |
| 2075 | * Class Encapsulation: Class Encapsulation. (line 6) |
| 2076 | * clog: Daemons. (line 11) |
| 2077 | * Coding Style: Coding Style. (line 6) |
| 2078 | * Compiler Options: Compiler Options. (line 6) |
| 2079 | * config.h: Compiler Options. (line 6) |
| 2080 | * configuration: Compiler Options. (line 6) |
| 2081 | * Configuration and Misc.: Configuration and Misc.. |
| 2082 | (line 6) |
| 2083 | * configure.ac: Automake Services. (line 6) |
| 2084 | * configure.in: Automake Services. (line 6) |
| 2085 | * Configuring Sources: Configuring Sources. (line 6) |
| 2086 | * Daemons: Daemons. (line 6) |
| 2087 | * detached thread: Threading Concepts. (line 92) |
| 2088 | * Developer Documentation: Developer Documentation. |
| 2089 | (line 6) |
| 2090 | * distribution: Distribution. (line 6) |
| 2091 | * DLL: Porting. (line 14) |
| 2092 | * Dont-Route: Sockets. (line 21) |
| 2093 | * Exceptions: Exceptions. (line 6) |
| 2094 | * execution context: Threading Concepts. (line 37) |
| 2095 | * Extras: Extras. (line 6) |
| 2096 | * FDL, GNU Free Documentation License: GNU Free Documentation License. |
| 2097 | (line 6) |
| 2098 | * Framework Description: Framework Description. |
| 2099 | (line 6) |
| 2100 | * free software: Distribution. (line 6) |
| 2101 | * FreeBSD: Porting. (line 8) |
| 2102 | * GCC: Porting. (line 20) |
| 2103 | * GNU Common C++ Linking Exception: GNU Common C++ Linking Exception. |
| 2104 | (line 6) |
| 2105 | * GNU FDL: Distribution. (line 6) |
| 2106 | * GNU GPL: Distribution. (line 6) |
| 2107 | * GNU pth: Threading Concepts. (line 23) |
| 2108 | * Introduction: Introduction. (line 6) |
| 2109 | * Java sockets: Sockets. (line 6) |
| 2110 | * Java threading: Threading Concepts. (line 6) |
| 2111 | * Keep-Alive: Sockets. (line 21) |
| 2112 | * linking exception: Distribution. (line 6) |
| 2113 | * linux threads: Threading Concepts. (line 53) |
| 2114 | * MSVC: Porting. (line 14) |
| 2115 | * namespace: Overall Concepts. (line 6) |
| 2116 | * Naming Convention: Naming Convention. (line 6) |
| 2117 | * Numbers and Dates: Numbers and Dates. (line 6) |
| 2118 | * ost: Overall Concepts. (line 6) |
| 2119 | * ost namespace: Overall Concepts. (line 6) |
| 2120 | * OST_CCXX2_FOX: Automake Services. (line 33) |
| 2121 | * OST_CCXX2_HOARD: Automake Services. (line 29) |
| 2122 | * OST_CCXX2_VERSION: Automake Services. (line 22) |
| 2123 | * OST_CCXX2_XML: Automake Services. (line 25) |
| 2124 | * ost_commoncxx.m4: Automake Services. (line 6) |
| 2125 | * ost_pthread.m4: Threading Concepts. (line 14) |
| 2126 | * Overall Concepts: Overall Concepts. (line 6) |
| 2127 | * Persistence: Persistence. (line 6) |
| 2128 | * philosophy: Distribution. (line 6) |
| 2129 | * Porting: Porting. (line 6) |
| 2130 | * priority: Threading Concepts. (line 44) |
| 2131 | * pth: Threading Concepts. (line 23) |
| 2132 | * pthread: Threading Concepts. (line 14) |
| 2133 | * pthread_join: Porting. (line 8) |
| 2134 | * pthread_self: Threading Concepts. (line 99) |
| 2135 | * QoS: Sockets. (line 21) |
| 2136 | * reference counting: Synchronization. (line 54) |
| 2137 | * reference manual: Introduction. (line 10) |
| 2138 | * resumed: Threading Concepts. (line 53) |
| 2139 | * Serial I/O: Serial I/O. (line 6) |
| 2140 | * Serverlets: Serverlets. (line 6) |
| 2141 | * SIGCONT: Threading Concepts. (line 53) |
| 2142 | * SIGHUP: Threading Concepts. (line 124) |
| 2143 | * SIGPIPE: Threading Concepts. (line 124) |
| 2144 | * SIGSTOP: Threading Concepts. (line 53) |
| 2145 | * SIGUSR1: Threading Concepts. (line 53) |
| 2146 | * slog: Daemons. (line 6) |
| 2147 | * Sockets: Sockets. (line 6) |
| 2148 | * sockopt: Sockets. (line 21) |
| 2149 | * Solaris: Porting. (line 11) |
| 2150 | * solaris threads: Threading Concepts. (line 53) |
| 2151 | * suspended: Threading Concepts. (line 53) |
| 2152 | * Synchronization: Synchronization. (line 6) |
| 2153 | * TCPSocket: Sockets. (line 35) |
| 2154 | * Templates: Templates. (line 6) |
| 2155 | * termination: Threading Concepts. (line 37) |
| 2156 | * thread destruction: Threading Concepts. (line 74) |
| 2157 | * thread initialization: Threading Concepts. (line 74) |
| 2158 | * thread join: Threading Concepts. (line 84) |
| 2159 | * thread priority: Threading Concepts. (line 44) |
| 2160 | * thread termination: Threading Concepts. (line 37) |
| 2161 | * threading: Threading Concepts. (line 6) |
| 2162 | * Threading Concepts: Threading Concepts. (line 6) |
| 2163 | * threading model: Threading Concepts. (line 31) |
| 2164 | * URL related functions: URL Streams. (line 6) |
| 2165 | * URL Streams: URL Streams. (line 6) |
| 2166 | * Win32: Porting. (line 14) |
| 2167 | * XML Streams and RPC: XML Streams and RPC. (line 6) |
| 2168 | |
| 2169 | |
| 2170 | |
| 2171 | Tag Table: |
| 2172 | Node: Top1002 |
| 2173 | Node: Introduction2369 |
| 2174 | Node: Distribution4700 |
| 2175 | Node: Framework Description7103 |
| 2176 | Node: Overall Concepts8272 |
| 2177 | Ref: Overall Concepts-Footnote-19367 |
| 2178 | Ref: Overall Concepts-Footnote-29494 |
| 2179 | Node: Threading Concepts9678 |
| 2180 | Node: Synchronization17623 |
| 2181 | Node: Sockets20766 |
| 2182 | Node: Serial I/O25171 |
| 2183 | Node: Block I/O27927 |
| 2184 | Node: Daemons29404 |
| 2185 | Node: Persistence30124 |
| 2186 | Node: Configuration and Misc.31042 |
| 2187 | Node: Numbers and Dates32767 |
| 2188 | Node: URL Streams33100 |
| 2189 | Node: XML Streams and RPC33576 |
| 2190 | Node: Exceptions33996 |
| 2191 | Node: Templates34614 |
| 2192 | Node: Extras34808 |
| 2193 | Node: Serverlets37045 |
| 2194 | Node: Compiler Options38506 |
| 2195 | Ref: Compiler Options-Footnote-142147 |
| 2196 | Node: Automake Services42258 |
| 2197 | Node: Configuring Sources43393 |
| 2198 | Node: Developer Documentation44150 |
| 2199 | Node: Coding Style44589 |
| 2200 | Node: Naming Convention44910 |
| 2201 | Node: Class Encapsulation46616 |
| 2202 | Node: Porting48896 |
| 2203 | Node: Licenses49848 |
| 2204 | Node: GNU Free Documentation License50234 |
| 2205 | Node: GNU General Public License72666 |
| 2206 | Node: GNU Common C++ Linking Exception91941 |
| 2207 | Node: Class and Data Type Index93312 |
| 2208 | Node: Method and Function Index98165 |
| 2209 | Node: Concept Index100409 |
| 2210 | |
| 2211 | End Tag Table |