1This is assuan.info, produced by makeinfo version 6.5 from assuan.texi. 2 3INFO-DIR-SECTION GNU Libraries 4START-INFO-DIR-ENTRY 5* Assuan: (assuan). An IPC library for non-persistent servers. 6END-INFO-DIR-ENTRY 7 8This file documents the use and the internals of Assuan. 9 10 This is Edition 2.5.5, last updated 7 December 2017, of 'The 11'Developing with Assuan' Manual', for Version 2.5.5. 12 13 Published by the Free Software Foundation 1451 Franklin Street, Fifth Floor 15Boston, MA 02110-1301 USA 16 17 Copyright (C) 2001-2013 Free Software Foundation, Inc. 18Copyright (C) 2001-2015 g10 Code GmbH 19 20 Permission is granted to copy, distribute and/or modify this document 21under the terms of the GNU General Public License as published by the 22Free Software Foundation; either version 3 of the License, or (at your 23option) any later version. The text of the license can be found in the 24section entitled "Copying". 25 26 27File: assuan.info, Node: Top, Next: Introduction, Up: (dir) 28 29Introduction 30************ 31 32This manual documents how to exploit the Assuan library, a simple 33interprocess communcation library. 34 35* Menu: 36 37* Introduction:: An introduction to and the motivation behind Assuan. 38* Assuan:: Description of the Assuan protocol. 39* Implementation:: Overview of the implementation. 40* Preparation:: What you should do before using the library. 41* Generalities:: Initialization code and data types used. 42* Client code:: How to develop an Assuan client. 43* Server code:: How to develop an Assuan server. 44* External I/O Loop:: How to use external I/O event loops. 45* Utilities:: Utility functions. 46* Socket wrappers:: Socket wrapper functions. 47 48Miscellaneous 49 50* Library Copying:: GNU Lesser General Public License says 51 how you can copy and share Assuan. 52* Copying:: How you can copy and share this manual. 53 54Indices 55 56* Index:: Index of concepts and symbol names. 57 58 59File: assuan.info, Node: Introduction, Next: Assuan, Prev: Top, Up: Top 60 611 Introduction to Assuan 62************************ 63 64Assuan is an extensible inter-process communication (IPC) protocol and 65library. It is designed for point-to-point communication and it doesn't 66provide a naming system. To contact a server, either the client must 67know how to locate the server, e.g., via a well-known Unix domain 68socket, or, if the server is transient, how to start it. In the latter 69case, Assuan provides functionality to start the server process. 70 71 In Assuan, communication is typically either via a pipe or a Unix 72domain socket. This method is neither elegant nor efficient, especially 73when there is a lot of data spread across several transactions. Not 74only is there a penalty for an increased number of context switches, but 75a significant amount of data is MEMCPYed from the client to a file 76descriptor and from the file descriptor to the server. Despite these 77and other disadvantages, this type of client/server communication is 78useful: the client is separated from the server: they run in different 79address spaces. This is especially important in situations where the 80server must have a known degree of reliability and data must be 81protected: as the Assuan protocol is well defined and clients cannot 82corrupt the servers' address space, auditing becomes much easier. 83 84 Assuan was developed for use by the GNU Privacy Guard (GnuPG) to 85prevent potentially buggy clients from unwittingly corrupting sensitive 86transactions or compromising data such as a secret key. Assuan permits 87the servers, which do the actual work, e.g., encryption and decryption 88of data using a secret key, to be developed independently of the user 89interfaces, e.g., mail clients and other encryption front ends. Like a 90shared library, the interface is well defined and any number of front 91ends can use it; however, unlike a shared library, the client cannot see 92or touch the server's data. As with any modular system, Assuan helps 93keep the components small, understandable and less error prone. 94 95 Assuan is not, however, limited to use with GnuPG servers and 96clients: it was designed to be flexible enough to meet the demands of 97many transaction-based environments. 98 99 100File: assuan.info, Node: Assuan, Next: Implementation, Prev: Introduction, Up: Top 101 1022 Description of the Assuan protocol. 103************************************* 104 105The architecture of the modular GnuPG system is based on several highly 106specialized modules which form a network of clients and servers. A 107common framework for intermodule communication is therefore needed and 108implemented as a library. 109 110 Goals: 111 112 * Common framework for module communication 113 * Easy debugging 114 * Easy module testing 115 * Extensible 116 * Optional authentication and encryption facility 117 * Usable to access external hardware 118 119 Design criteria: 120 121 * Client/Server with back channel 122 * Use a mainly text based protocol 123 * Escape certain control characters 124 * Allow indefinite data length 125 * Request confidentiality for parts of the communication 126 * Dummy module to allow direct linking of client and server 127 * Inline data or descriptor passing for bulk data 128 * No protection against DoS needed 129 * Subliminal channels are not an issue 130 131 132File: assuan.info, Node: Implementation, Next: Preparation, Prev: Assuan, Up: Top 133 1343 Implementation 135**************** 136 137The implementation is line based with a maximum line size of 1000 138octets. The default IPC mechanism is Unix Domain Sockets. 139 140 On connect, the server responds either with okay or an error status. 141To perform an authentication check, the server may send an Inquiry 142response prior to the first Okay. It may also issue Status messages. 143The server must check that the client is allowed to connect. This is 144done by requesting the credentials for the peer and comparing them with 145the server's credentials. This avoids attacks based on wrong socket 146permissions. 147 148 The server may choose to delay the first response in case of an 149error. The server, however, never closes the connection, however, the 150lower protocol may do so after some time of inactivity or when the 151connection enters an error state. 152 153 All textual messages are assumed to be in UTF-8 unless otherwise 154noted. 155 156* Menu: 157 158* Server responses:: Description of server responses. 159* Client requests:: Description of client requests. 160* Error codes:: List of error and status codes. 161 162 163File: assuan.info, Node: Server responses, Next: Client requests, Up: Implementation 164 1653.1 Server responses 166==================== 167 168'OK [<arbitrary debugging information>]' 169 Request was successful. 170 171'ERR ERRORCODE [<human readable error description>]' 172 Request could not be fulfilled. The possible error codes are 173 defined by 'libgpg-error'. 174 175'S KEYWORD <status information depending on keyword>' 176 Informational output by the server, which is still processing the 177 request. A client may not send such lines to the server while 178 processing an Inquiry command. KEYWORD shall start with a letter 179 or an underscore. 180 181'# <string>' 182 Comment line issued only for debugging purposes. Totally ignored. 183 184'D <raw data>' 185 Raw data returned to client. There must be exactly one space after 186 the 'D'. The values for '%', CR and LF must be percent escaped; 187 these are encoded as %25, %0D and %0A, respectively. Only 188 uppercase letters should be used in the hexadecimal representation. 189 Other characters may be percent escaped for easier debugging. All 190 Data lines are considered one data stream up to the OK or ERR 191 response. Status and Inquiry Responses may be mixed with the Data 192 lines. 193 194'INQUIRE KEYWORD <parameters>' 195 The server needs further information from the client. The client 196 should respond with data (using the "D" command and terminated by 197 "END"). Alternatively, the client may cancel the current operation 198 by responding with "CAN". 199 200 Consider the following examples (lines prefixed with S indicate text 201that the server sends; lines prefixed with C indicate text that the 202client sends): 203 204 S: INQUIRE foo 205 C: D foo bar 206 C: D bar baz 207 C: END 208 [Server continues normal work] 209 210 This implements a callback to the client: 211 212 S: INQUIRE foo 213 C: END 214 [Server continues] 215 216 and: 217 218 S: INQUIRE foo 219 C: CAN 220 [Server terminates the operaion and in most cases returns an ERR to the client.] 221 222 But, CAN may also mean "I have no data for you, try to get it from 223elsewhere." 224 225 Note: lines longer than 1000 bytes should be treated as a 226communication error. (The rationale for having a line length limit is 227to allow for easier multiplexing of several channels.) 228 229 230File: assuan.info, Node: Client requests, Next: Error codes, Prev: Server responses, Up: Implementation 231 2323.2 Client requests 233=================== 234 235The server waits for client requests after sending an Okay or Error. 236The client should not issue a request in other cases. 237 238 COMMAND <parameters> 239 240 COMMAND is a one word string without preceding white space. 241Parameters are command specific, CR, LF and the percent signs should be 242percent escaped as described above. To send a backslash as the last 243character it should also be percent escaped. Percent escaping is 244allowed anywhere in the parameters but not in the command. The line 245ends with a CR, LF pair or just a LF. 246 247 Not yet implemented feature: If there is a need for a parameter list 248longer than the line length limit (1000 characters including command and 249CR, LF), the last character of the line (right before the CR/LF or LF) 250must be a unescaped (i.e., literal) backslash. The following line is 251then expected to be a continuation of the line with the backslash 252replaced by a blank and the line ending removed. 253 254 D <raw data> 255 256 Sends raw data to the server. There must be exactly one space after 257the 'D'. The values for '%', CR and LF must be percent escaped. These 258are encoded as %25, %0D and %0A, respectively. Only uppercase letters 259should be used in the hexadecimal representation. Other characters may 260be percent escaped for easier debugging. All Data lines are considered 261one data stream up to the 'OK' or 'ERR' response. Status and Inquiry 262Responses may be mixed with the Data lines. 263 264 END 265 266 Lines beginning with a '#' or empty lines are ignored. This is 267useful to comment test scripts. 268 269 Although the commands are application specific, some of them are used 270by all protocols and partly supported by the Assuan library: 271 272'BYE' 273 Close the connection. The server will respond with 'OK'. 274 275'RESET' 276 Reset the connection but not any existing authentication. The 277 server should release all resources associated with the connection. 278 279'END' 280 Used by a client to mark the end of raw data. The server may send 281 'END' to indicate a partial end of data. 282 283'HELP' 284 Lists all commands that the server understands as comment lines on 285 the status channel. 286 287'QUIT' 288 Reserved for future extensions. 289 290'OPTION' 291 Set options for the connection. The syntax of such a line is 292 OPTION NAME [ [=] VALUE ] 293 Leading and trailing spaces around NAME and VALUE are allowed but 294 should be ignored. For compatibility reasons, NAME may be prefixed 295 with two dashes. The use of the equal sign is optional but 296 suggested if VALUE is given. 297 298'CANCEL' 299 This command is reserved for future extensions. 300 301'AUTH' 302 This command is reserved for future extensions. Not yet specified 303 as we don't implement it in the first phase. See Werner's mail to 304 gpa-dev on 2001-10-25 about the rationale for measurements against 305 local attacks. 306 307'NOP' 308 No operation. Returns OK without any action. 309 310 311File: assuan.info, Node: Error codes, Prev: Client requests, Up: Implementation 312 3133.3 Error codes 314=============== 315 316Libassuan is used with gpg-error style error codes. It is recommended 317to set the error source to a different value from the default 318'GPG_ERR_SOURCE_UNKNOWN' by calling *note function 319assuan_set_gpg_err_source:: early. 320 321 322File: assuan.info, Node: Preparation, Next: Generalities, Prev: Implementation, Up: Top 323 3244 Preparation 325************* 326 327To use ASSUAN, you have to make some changes to your sources and the 328build system. The necessary changes are small and explained in the 329following sections. 330 331* Menu: 332 333* Header:: What header file you need to include. 334* Building sources:: How to build sources using the library. 335* Automake:: How to build sources with the help of Automake. 336* Multi Threading:: How 'libassuan' can be used in a MT environment. 337 338 339File: assuan.info, Node: Header, Next: Building sources, Up: Preparation 340 3414.1 Header 342========== 343 344All interfaces (data types and functions) of 'libassuan' are defined in 345the header file 'assuan.h'. You must include this in all source files 346using the library, either directly or through some other header file, 347like this: 348 349 #include <assuan.h> 350 351 The namespace of 'libassuan' is 'assuan_*' for function and type 352names and 'ASSUAN*' for other symbols. In addition the same name 353prefixes with one prepended underscore are reserved for internal use and 354should never be used by an application. 355 356 Because 'libassuan' makes use of the GPG Error library, using 357'libassuan' will also use the 'GPG_ERR_*' namespace directly, and the 358'gpg_err*' and 'gpg_str*' namespaces indirectly. 359 360 361File: assuan.info, Node: Building sources, Next: Automake, Prev: Header, Up: Preparation 362 3634.2 Building sources 364==================== 365 366If you want to compile a source file including the 'assuan.h' header 367file, you must make sure that the compiler can find it in the directory 368hierarchy. This is accomplished by adding the path to the directory in 369which the header file is located to the compilers include file search 370path (via the '-I' option). 371 372 However, the path to the include file is determined at the time the 373source is configured. To solve this problem, 'libassuan' ships with a 374small helper program 'libassuan-config' that knows the path to the 375include file and other configuration options. The options that need to 376be added to the compiler invocation at compile time are output by the 377'--cflags' option to 'libassuan-config'. The following example shows 378how it can be used at the command line: 379 380 gcc -c foo.c $(libassuan-config --cflags) 381 382 Adding the output of 'libassuan-config --cflags' to the compiler's 383command line will ensure that the compiler can find the 'assuan.h' 384header file. 385 386 A similar problem occurs when linking the program with the library. 387Again, the compiler/linker has to find the library files. For this to 388work, the path to the library files has to be added to the library 389search path (via the '-L' option). For this, the option '--libs' to 390'libassuan-config' can be used. For convenience, this option also 391outputs all other options that are required to link the program with the 392'libassuan' libraries (in particular, the '-lassuan' option). The 393example shows how to link 'foo.o' with the 'libassuan' library to a 394program 'foo'. 395 396 gcc -o foo foo.o $(libassuan-config --libs) 397 398 You can also combine both examples to a single command by specifying 399both options to 'libassuan-config': 400 401 gcc -o foo foo.c $(libassuan-config --cflags --libs) 402 403 404File: assuan.info, Node: Automake, Next: Multi Threading, Prev: Building sources, Up: Preparation 405 4064.3 Building sources using Automake 407=================================== 408 409It is much easier if you use GNU Automake instead of writing your own 410Makefiles. If you do that you do not have to worry about finding and 411invoking the 'libassuan-config' script at all. 'libassuan' provides an 412Automake macro that does all the work for you. 413 414 -- Macro: AM_PATH_LIBASSUAN ([MINIMUM-VERSION], [ACTION-IF-FOUND], 415 [ACTION-IF-NOT-FOUND]) 416 Check whether 'libassuan' (at least version MINIMUM-VERSION, if 417 given) exists on the host system. If it is found, execute 418 ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given. 419 420 Additionally, the function defines 'LIBASSUAN_CFLAGS' to the flags 421 needed for compilation of the program to find the 'assuan.h' header 422 file, and 'LIBASSUAN_LIBS' to the linker flags needed to link the 423 program to the 'libassuan' library. 424 425 You can use the defined Autoconf variables like this in your 426'Makefile.am': 427 428 AM_CPPFLAGS = $(LIBASSUAN_CFLAGS) 429 LDADD = $(LIBASSUAN_LIBS) 430 431 432File: assuan.info, Node: Multi Threading, Prev: Automake, Up: Preparation 433 4344.4 Multi Threading 435=================== 436 437The 'libassuan' library is designed so that it can be used in a threaded 438application, if some rules are followed. 439 440 * Run the initialization functions before you actually start to use 441 threads. Specifically, the functions 'assuan_set_gpg_err_source', 442 'assuan_set_malloc_hooks' and 'assuan_set_log_cb' should not be 443 called concurrently with 'assuan_new'. Use 'assuan_new_ext' 444 instead or ensure proper serialization. 445 * Only one thread at a time may access an 'libassuan' context. 446 * If you use the default log handler, use 447 'assuan_set_assuan_log_stream' to setup a default log stream. 448 * If you have callback functions shared by multiple functions, the 449 callback function must be reentrant for that purpose. 'libassuan' 450 does not serialize invocation of callback functions across 451 contexts. 452 453 454File: assuan.info, Node: Generalities, Next: Client code, Prev: Preparation, Up: Top 455 4565 Generalities 457************** 458 459* Menu: 460 461* Data Types:: Data types used by 'libassuan'. 462* Initializing the library:: How to initialize the library. 463* Default Log Handler:: How to configure the default log handler. 464* Contexts:: How to work with contexts. 465* Reading and Writing:: How to communicate with the peer. 466 467 468File: assuan.info, Node: Data Types, Next: Initializing the library, Up: Generalities 469 4705.1 Data Types used by the library 471================================== 472 473ASSUAN uses a so-called context to store a connection's state. The 474following data type is used for that: 475 476 -- Data type: assuan_context_t 477 The 'assuan_context_t' type is a pointer to an object maintained 478 internally by the library. Contexts are allocated with 479 'assuan_new' or 'assuan_new_ext' and released with 480 'assuan_release'. Other functions take this data type to access 481 the state created by these functions. 482 483 -- Data type: assuan_fd_t 484 The 'assuan_fd_t' is a file descriptor (in Unix) or a system handle 485 (in Windows). The special value 'ASSUAN_INVALID_FD' is used to 486 specify invalid Assuan file descriptors. 487 488 -- Function: assuan_fd_t assuan_fdopen (int FD) 489 Create an assuan file descriptor from a POSIX (libc) file 490 descriptor FD. On Unix, this is equivalent to 'dup', while on 491 Windows this will retrieve the underlying system handle with 492 '_get_osfhandle' and duplicate that. 493 494 495File: assuan.info, Node: Initializing the library, Next: Default Log Handler, Prev: Data Types, Up: Generalities 496 4975.2 Initializing the library 498============================ 499 500Libassuan makes use of Libgpg-error and assumes that Libgpg-error has 501been initialized. In general 'gpgrt_check_version' should be called to 502guarantee this; the Libgpg-error manual for details. 503 504 Libassuan itself requires no initialization. There are however some 505initialization hooks provided which are often useful. These should be 506called as early as possible and in a multi-threaded application before a 507second thread is created. 508 509 These functions initialize default values that are used at context 510creation with 'assuan_new'. As there can only be one default, all 511values can also be set directly with 'assuan_new_ext' or with 512context-specific functions after context creation. 513 514 If your application uses its own memory allocation functions or 515wrappers it is good idea to tell 'libassuan' about it so it can make use 516of the same functions or wrappers: 517 518 -- Data type: struct assuan_malloc_hooks 519 This structure is used to store the memory allocation callback 520 interface functions. It has the following members, whose semantics 521 are identical to the corresponding system functions: 522 523 'void *(*malloc) (size_t cnt)' 524 This is the function called by ASSUAN to allocate memory for a 525 context. 526 527 'void *(*realloc) (void *ptr, size_t cnt)' 528 This is the function called by ASSUAN to reallocate memory for 529 a context. 530 531 'void (*free) (void *ptr)' 532 This is the function called by ASSUAN to release memory for a 533 context. 534 535 -- Data type: assuan_malloc_hooks_t 536 This is a pointer to a 'struct assuan_malloc_hooks'. 537 538 -- Function: void assuan_set_malloc_hooks 539 (assuan_malloc_hooks_t MALLOC_HOOKS) 540 This function sets the default allocation hooks for new contexts 541 allocated with 'assuan_new'. You need to provide all three 542 functions. Those functions need to behave exactly as their 543 standard counterparts 'malloc', 'realloc' and 'free'. If you write 544 your own functions, please take care to set 'errno' whenever an 545 error has occurred. 546 547 -- Function: assuan_malloc_hooks_t assuan_get_malloc_hooks () 548 This function gets the default allocation hooks for new contexts 549 allocated with 'assuan_new'. The result structure is statically 550 allocated and should not be modified. 551 552 The ASSUAN library uses 'libgpg-error' error values, which consist 553and error code and an error source. The default source used by contexts 554allocated with 'assuan_new' can be set with the following function. 555 556 -- Function: void assuan_set_gpg_err_source 557 (gpg_err_source_t ERR_SOURCE) 558 This function sets the default error source for errors generated by 559 contexts allocated with 'assuan_new'. 560 561 One way to call this function is 562 assuan_set_gpg_err_source (GPG_ERR_SOURCE_DEFAULT); 563 564 -- Function: gpg_err_source_t assuan_get_gpg_err_source (void) 565 This function gets the default error source for errors generated by 566 contexts allocated with 'assuan_new'. 567 568To integrate assuan logging and diagnostics into your own logging 569system, you may use the following two functions: 570 571 -- Data type: int (*assuan_log_cb_t) (assuan_context_t CTX, 572 void *HOOK_VALUE, unsigned int CAT, const char *MSG) 573 The user-provided callback function takes a context CTX, for which 574 the message MSG was generated, and a hook value HOOK_VALUE that was 575 supplied when the log handler was registered for the context with 576 'assuan_set_log_cb', and a category CAT. The category is one of: 577 578 'ASSUAN_LOG_INIT' 579 'ASSUAN_LOG_CTX' 580 'ASSUAN_LOG_ENGINE' 581 'ASSUAN_LOG_DATA' 582 RFU 583 'ASSUAN_LOG_SYSIO' 584 Log lowlevel I/O data. 585 'ASSUAN_LOG_CONTROL' 586 Log the control channel. 587 588 The user may then, depending on the category, write the message to 589 a log file or treat it in some other way. 590 591 If MSG is a null pointer, then no message should be logged, but the 592 function should return 1 if it is interested in log messages with 593 the category CAT. If it is not interested, 0 should be returned. 594 This allows 'libassuan' to suppress the generation of expensive 595 debug output. 596 597 -- Function: void assuan_set_log_cb (assuan_log_cb_t LOG_CB, 598 void *LOG_CB_DATA) 599 This function sets the default logging handler for log messages 600 generated by contexts allocated with 'assuan_new'. 601 602 -- Function: void assuan_get_log_cb (assuan_log_cb_t *LOG_CB, 603 void **LOG_CB_DATA) 604 This function gets the default logging handler for log messages 605 generated by contexts allocated with 'assuan_new'. 606 607 You do not need to set a log handler, as ASSUAN provides a 608configurable default log handler that should be suitable for most 609purposes. Logging can be disabled completely by setting the log handler 610to a null pointer. 611 612 613File: assuan.info, Node: Default Log Handler, Next: Contexts, Prev: Initializing the library, Up: Generalities 614 6155.3 Default Log Handler 616======================= 617 618The default log handler can be configured by the following functions: 619 620 -- Function: void assuan_set_assuan_log_prefix (const char *TEXT) 621 Set the prefix to be used at the start of a line emitted by assuan 622 on the log stream to TEXT. The default is the empty string. 623 624 -- Function: const char * assuan_get_assuan_log_prefix (void) 625 Return the prefix to be used at the start of a line emitted by 626 assuan on the log stream. The default implementation returns the 627 empty string. 628 629 -- Function: void assuan_set_assuan_log_stream (FILE *FP) 630 This sets the default log stream to which 'libassuan' should log 631 messages not associated with a specific context to FP. The default 632 is to log to 'stderr'. This default value is also changed by using 633 'assuan_set_log_stream' (to set a logging stream for a specific 634 context) unless this function has been used. Obviously this is not 635 thread-safe and thus it is highly recommended to use this function 636 to setup a proper default. 637 638 -- Function: FILE * assuan_get_assuan_log_stream (void) 639 Return the stream which is currently being using for global 640 logging. 641 642 The log stream used by the default log handler can also be set on a 643per context basis. 644 645 -- Function: void assuan_set_log_stream (assuan_context_t CTX, 646 FILE *FP) 647 Enable debugging for the context CTX and write all debugging output 648 to the stdio stream FP. If the default log stream (used for 649 non-context specific events) has not yet been set, a call to this 650 functions implicitly sets this stream also to FP. 651 652 653File: assuan.info, Node: Contexts, Next: Reading and Writing, Prev: Default Log Handler, Up: Generalities 654 6555.4 How to work with contexts 656============================= 657 658Some operations work globally on the library, but most operate in a 659context, which saves state across operations. To allow the use of 660'libassuan' in mixed environments, such as in a library using GPGME and 661an application using GPGME, the context is very extensive and covers 662utilitary information like memory allocation callbacks as well as 663specific information associated with client/server operations. 664 665 -- Function: gpg_error_t assuan_new (assuan_context_t *CTX_P) 666 The function 'assuan_new' creates a new context, using the global 667 default memory allocation, log handler and 'libgpg-error' source. 668 It is equivalent to 669 670 gpg_error_t err; 671 assuan_log_cb_t log_cb; 672 void *log_cb_data; 673 674 assuan_get_log_cb (&log_cb, &log_cb_data); 675 err = assuan_new_ext (ctx_p, assuan_get_gpg_err_source (), 676 assuan_get_malloc_hooks (), log_cb, log_cb_data); 677 678 As you can see, this is not thread-safe. Take care not to modify 679 the memory allocation hooks or log callback handler concurrently 680 with 'assuan_new'. 681 682 The function returns an error if a memory allocation error occurs, 683 and 0 with the new context in CTX_P otherwise. 684 685 -- Function: gpg_error_t assuan_new_ext (assuan_context_t *CTX_P, 686 gpg_err_source_t ERR_SOURCE, 687 assuan_malloc_hooks_t MALLOC_HOOKS, assuan_log_cb_t LOG_CB, 688 void *LOG_CB_DATA) 689 The function 'assuan_new_ext' creates a new context using the 690 supplied 'libgpg-error' error source ERR_SOURCE, the memory 691 allocation hooks MALLOC_HOOKS and the log handler LOG_CB with the 692 user data LOG_CB_DATA. 693 694 After the context has been used, it can be destroyed again. 695 696 -- Function: void assuan_release (assuan_context_t ctx) 697 The function 'assuan_release' destroys the context CTX and releases 698 all associated resources. 699 700 Other properties of the context beside the memory allocation handler, 701the log handler, and the 'libgpg-error' source can be set after context 702creation. Here are some of them: 703 704 -- Function: void assuan_set_pointer (assuan_context_t CTX, 705 void *POINTER) 706 707 Store the arbitrary pointer value POINTER into the context CTX. 708 This is useful to provide command handlers with additional 709 application context. 710 711 -- Function: void* assuan_get_pointer (assuan_context_t CTX) 712 713 This returns the pointer for context CTX which has been set using 714 the above function. A common way to use it is by setting the 715 pointer before starting the processing loop and to retrieve it 716 right at the start of a command handler: 717 static int 718 cmd_foo (assuan_context_t ctx, char *line) 719 { 720 ctrl_t ctrl = assuan_get_pointer (ctx); 721 ... 722 } 723 724 -- Function: void assuan_set_flag (assuan_context_t CTX, 725 assuan_flag_t FLAG, int VALUE) 726 727 Set the the FLAG for context CTX to VALUE. Values for flags are 728 usually 1 or 0 but certain flags might need other values. 729 730 -- Data type: assuan_flag_t 731 The flags are all named and collected in an 'enum' for better 732 readability. Available flags are: 733 734 'ASSUAN_NO_WAITPID' 735 When using a pipe server, by default Libassuan will wait 736 for the forked process to die in 'assuan_release'. In 737 certain cases this is not desirable. By setting this 738 flag, a call to 'waitpid' will be suppressed and the 739 caller is responsible to cleanup the child process. 740 'ASSUAN_CONFIDENTIAL' 741 Use to return the state of the confidential logging mode. 742 'ASSUAN_NO_FIXSIGNALS' 743 Do not modify signal handler for 'SIGPIPE'. 744 'ASSUAN_CONVEY_COMMENTS' 745 If enabled comment lines are passed to the status 746 callback of the 'assuan_transact'. 747 'ASSUAN_FORCE_CLOSE' 748 Setting this flag forces the next command to assume that 749 the connection has been closed. This breaks the command 750 processing loop and may be used as an implicit BYE 751 command. VALUE is ignored and thus it is not possible to 752 clear this flag. 753 754 -- Function: int assuan_get_flag (assuan_context_t CTX, 755 assuan_flag_t FLAG) 756 Return the value of FLAG in context CTX. 757 758 -- Function: void assuan_begin_confidential (assuan_context_t CTX) 759 Put the logging feature into confidential mode. This is to avoid 760 logging of sensitive data. 761 762 This is identical to: 763 assuan_set_flag (ctx, ASSUAN_CONFIDENTIAL, 1); 764 765 -- Function: void assuan_end_confidential (assuan_context_t CTX) 766 Get the logging feature out of confidential mode. All data will be 767 logged again (if logging is enabled). 768 769 This is identical to: 770 assuan_set_flag (ctx, ASSUAN_CONFIDENTIAL, 0); 771 772 -- Data type: struct assuan_system_hooks 773 This structure is used to store the system callback interface 774 functions. It has the following members, whose semantics are 775 similar to the corresponding system functions, but not exactly 776 equivalent. 777 778 'int version' 779 The user should set this to 'ASSUAN_SYSTEM_HOOKS_VERSION'. 780 This indicates to the library which members of this structure 781 are present in case of future extensions. The user should 782 initialize the whole structure with zero bytes. 783 784 'void (*usleep) (assuan_context_t ctx, unsigned int usec)' 785 This is the function called by ASSUAN to sleep for 'USEC' 786 microseconds. 787 788 'int (*pipe) (assuan_context_t ctx, assuan_fd_t fd[2], int inherit_idx)' 789 This is the function called by ASSUAN to create a pipe. The 790 returned file descriptor 'fd[inherit_idx]' must be inheritable 791 by the child process (under Windows, this requires some extra 792 work). 793 794 'int (*close) (assuan_context_t ctx, assuan_fd_t fd)' 795 This is the function called by ASSUAN to close a file 796 descriptor created through the system functions. 797 798 'ssize_t (*read) (assuan_context_t ctx, assuan_fd_t fd, void *buffer, size_t size)' 799 This is the function called by ASSUAN to read data from a file 800 descriptor. It is functionally equivalent to the system 801 'read' function. 802 803 'ssize_t (*write) (assuan_context_t ctx, assuan_fd_t fd, const void *buffer, size_t size)' 804 This is the function called by ASSUAN to write data to a file 805 descriptor. It is functionally equivalent to the system 806 'write' function. 807 808 'int (*recvmsg) (assuan_context_t ctx, assuan_fd_t fd, assuan_msghdr_t msg, int flags)' 809 This is the function called by ASSUAN to receive a message 810 from a file descriptor. It is functionally equivalent to the 811 system 'recvmsg' function. 812 813 'int (*sendmsg) (assuan_context_t ctx, assuan_fd_t fd, const assuan_msghdr_t msg, int flags);' 814 This is the function called by ASSUAN to send a message to a 815 file descriptor. It is functionally equivalent to the system 816 'sendmsg' function. 817 818 'int (*spawn) (assuan_context_t ctx, pid_t *r_pid, const char *name, const char **argv, assuan_fd_t fd_in, assuan_fd_t fd_out, assuan_fd_t *fd_child_list, void (*atfork) (void *opaque, int reserved), void *atforkvalue, unsigned int flags)' 819 This is the function called by ASSUAN to spawn a child 820 process. The 'stdin' and 'stdout' file descriptors are 821 provided in 'fd_in' and 'fd_out' respectively, but can be set 822 to 'ASSUAN_INVALID_FD', in which case they are set to 823 '/dev/null'. On systems which use 'fork' and 'exec', the 824 'atfork' function should be called with 'atforkvalue' and '0' 825 for flags in the child process right after 'fork' returns. 826 'fd_child_list' is a 'ASSUAN_INVALID_FD' terminated array (or 827 'NULL') and specifies file descriptors to be inherited by the 828 child process. 829 830 A special situation occurs if 'name' is a null pointer, in 831 which case the process should just fork but not call 'exec'. 832 In this case, '*argv' should be set to '"client"' in the 833 parent process and '"server"' in the child process. 834 835 Flags is the bit-wise OR of some (or none) of the following 836 flags: 837 838 'ASSUAN_SPAWN_DETACHED' 839 If set and there is a need to start the server it will be 840 started as a background process. This flag is useful 841 under W32 systems, so that no new console is created and 842 pops up a console window when starting the server. On 843 W32CE systems this flag is ignored. 844 845 'pid_t (*waitpid) (assuan_context_t ctx, pid_t pid, int action, int *status, int options)' 846 This is the function called by ASSUAN to wait for the spawned 847 child process PID to exit, or, if ACTION is 1, to just release 848 all resources associated with PID (required on Windows 849 platforms). If ACTION is 0, this is equivalent to 'waitpid'. 850 851 'int (*socketpair) (assuan_context_t ctx, int namespace, int style, int protocol, assuan_fd_t filedes[2])' 852 This is the function called by ASSUAN to create a socketpair. 853 It is equivalent to 'socketpair'. 854 855 -- Function: void assuan_set_system_hooks 856 (assuan_system_hooks_t SYSTEM_HOOKS) 857 Set the default system hooks to use. There is currently no way to 858 reset to the default system hooks. 859 860 -- Function: void assuan_sock_set_system_hooks 861 (assuan_system_hooks_t SYSTEM_HOOKS) 862 The socket subsystem uses an internal context which uses the 863 default system hooks. This function allows to change these system 864 hooks. The function is not thread-safe and only useful if a 865 certain order of assuan and assuan socket initializations are 866 required. 867 868 -- Function: void assuan_ctx_set_system_hooks (assuan_context_t CTX, 869 assuan_system_hooks_t SYSTEM_HOOKS) 870 Set the system hooks for context CTX. There is currently no way to 871 reset to the default system hooks, create a new context for that. 872 873 The following system hook collections are defined by the library for 874your convenience: 875 876'ASSUAN_SYSTEM_NPTH' 877 System hooks suitable for use with the nPth library. 878'ASSUAN_SYSTEM_NPTH_IMPL' 879 The implementation of system hooks for use with the nPth library. 880 This must be invoked once somewhere in the application, and defines 881 the structure that is referenced by 'ASSUAN_SYSTEM_NPTH'. 882'ASSUAN_SYSTEM_PTH' 883 System hooks suitable for use with the GNU Pth library. 884'ASSUAN_SYSTEM_PTH_IMPL' 885 The implementation of system hooks for use with the GNU Pth 886 library. This must be invoked once somewhere in the application, 887 and defines the structure that is referenced by 888 'ASSUAN_SYSTEM_PTH'. 889 890 891File: assuan.info, Node: Reading and Writing, Prev: Contexts, Up: Generalities 892 8935.5 How to communicate with the peer 894==================================== 895 896What would be an IPC library without the ability to read and write data? 897Not very useful. Libassuan has high level functions to take care of of 898the more boring stuff, but eventually data needs to be written and read. 899 900The basic read and write functions are: 901 902 -- Function: gpg_error_t assuan_read_line (assuan_context_t CTX, 903 char **LINE, size_t *LINELEN) 904 905 Read the next line written by the peer to the control channel and 906 store a pointer to the buffer holding that line at the address 907 LINE. The valid length of the lines is stored at the address of 908 LINELEN. This buffer is valid until the next read operation on the 909 same context CTX. You may modify the context of this buffer. The 910 buffer is invalid (i.e. must not be used) if an error is returned. 911 This function returns '0' on success or an error value. 912 913 -- Function: gpg_error_t assuan_write_line (assuan_context_t CTX, 914 const char *LINE) 915 916 Write the string LINE to the other end on the control channel. 917 This string needs to be a proper formatted Assuan protocol line and 918 should not include a linefeed. Sending linefeed or 'Nul' 919 characters is not possible and not allowed by the assuan protocol. 920 This function shall not be used for sending data ('D') lines. This 921 function returns '0' on success or an error value. 922 923To actually send bulk data lines a specialized function is available: 924 925 -- Function: gpg_error_t assuan_send_data (assuan_context_t CTX, 926 const void *BUFFER, size_t LENGTH) 927 928 This function is used by a server or a client to send LENGTH bytes 929 of bulk data in BUFFER to the other end on the control channel. 930 The data will be escaped as required by the Assuan protocol and may 931 get buffered until a line is full. To flush any pending data, 932 BUFFER may be passed as 'NULL' and LENGTH be '0'. 933 934 When used by a client, this flush operation does also send the 935 'END' command to terminate the response on an 'INQUIRE' request. 936 Note that the function 'assuan_transact' takes care of sending this 937 'END' itself. 938 939 This function returns '0' on success or an error value. 940 941 The input and output of data can be controlled at a higher level 942using an I/O monitor. 943 944 -- Data type: unsigned int (*assuan_io_monitor_t) 945 (assuan_context_t CTX, void *HOOK_VALUE, int INOUT, 946 const char *LINE, size_t LINELEN) 947 The monitor function is called right after a line has been 948 received, if INOUT is 'ASSUAN_IO_FROM_PEER', or just before it is 949 send, if INOUT is 'ASSUAN_IO_TO_PEER'. The HOOK_VALUE is provided 950 by the user when registering the I/O monitor function with a 951 context using 'assuan_set_io_monitor'. The callback function 952 should return the bitwise OR of some (or none) of the following 953 flags: 954 955 'ASSUAN_IO_MONITOR_NOLOG' 956 Active logging of this line is suppressed. This can reduce 957 debug output in the case of a frequent message. 958 'ASSUAN_IO_MONITOR_IGNORE' 959 The whole output line is discarded. 960 961 -- Function: void assuan_set_io_monitor (assuan_context_t CTX, 962 assuan_io_monitor_t IO_MONITOR, void *HOOK_DATA) 963 This function registers an I/O monitor IO_MONITOR for the context 964 CTX with the hook value HOOK_DATA. 965 966 967File: assuan.info, Node: Client code, Next: Server code, Prev: Generalities, Up: Top 968 9696 How to develop an Assuan client 970********************************* 971 972Depending on the type of the server you want to connect you need to use 973different functions. 974 975 If the peer is not a simple pipe server but one using full-duplex 976sockets, the full-fledged variant of the above function should be used: 977 978 -- Function: gpg_error_t assuan_pipe_connect 979 (assuan_context_t CTX,const char *NAME, const char *ARGV[], 980 assuan_fd_t *FD_CHILD_LIST, void (*ATFORK) (void *, int), 981 void *ATFORKVALUE, unsigned int FLAGS) 982 983 A call to this functions forks the current process and executes the 984 program NAME, passing the arguments given in the NULL-terminated 985 list ARGV. A list of file descriptors not to be closed may be 986 given using the 'ASSUAN_INVALID_FD' terminated array FD_CHILD_LIST. 987 988 If NAME is a null pointer, only a fork but no exec is done. Thus 989 the child continues to run. However all file descriptors are 990 closed and some special environment variables are set. To let the 991 caller detect whether the child or the parent continues, the parent 992 returns with '"client"' returned in ARGV and the child returns with 993 '"server"' in ARGV. This feature is only available on POSIX 994 platforms. 995 996 If ATFORK is not NULL, this function is called in the child right 997 after the fork and the value ATFORKVALUE is passed as the first 998 argument. That function should only act if the second argument it 999 received is '0'. Such a fork callback is useful to release 1000 additional resources not to be used by the child. 1001 1002 FLAGS is a bit vector and controls how the function acts: 1003 1004 'ASSUAN_PIPE_CONNECT_FDPASSING' 1005 If cleared a simple pipe based server is expected. If set a 1006 server based on full-duplex pipes is expected. Such pipes are 1007 usually created using the 'socketpair' function. It also 1008 enables features only available with such servers. 1009 1010 'ASSUAN_PIPE_CONNECT_DETACHED' 1011 If set and there is a need to start the server it will be 1012 started as a background process. This flag is useful under 1013 W32 systems, so that no new console is created and pops up a 1014 console window when starting the server. On W32CE systems 1015 this flag is ignored. 1016 1017 If you are using a long running server listening either on a TCP or a 1018Unix domain socket, the following function is used to connect to the 1019server: 1020 1021 -- Function: gpg_error_t assuan_socket_connect (assuan_context_t CTX, 1022 const char *NAME, pid_t SERVER_PID, unsigned int FLAGS) 1023 1024 Make a connection to the Unix domain socket NAME using the 1025 already-initialized Assuan context at CTX. SERVER_PID is currently 1026 not used but may become handy in the future; if you don't know the 1027 server's process ID (PID), pass 'ASSUAN_INVALID_PID'. With FLAGS 1028 set to 'ASSUAN_SOCKET_CONNECT_FDPASSING', 'sendmsg' and 'recvmesg' 1029 are used for input and output and thereby enable the use of 1030 descriptor passing. 1031 1032 Connecting to a TCP server is not yet implemented. Standard URL 1033 schemes are reserved for NAME specifying a TCP server. 1034 1035 Now that we have a connection to the server, all work may be 1036conveniently done using a couple of callbacks and the transact function: 1037 1038 -- Function: gpg_error_t assuan_transact (assuan_context_t CTX, 1039 const char *COMMAND, 1040 gpg_error_t (*DATA_CB)(void *, const void *, size_t), 1041 void *DATA_CB_ARG, 1042 gpg_error_t (*INQUIRE_CB)(void*, const char *), 1043 void *INQUIRE_CB_ARG, 1044 gpg_error_t (*STATUS_CB)(void*, const char *), 1045 void *STATUS_CB_ARG) 1046 1047 Here CTX is the Assuan context opened by one of the connect calls. 1048 COMMAND is the actual Assuan command string. It shall not end with 1049 a line feed and its length is limited to 'ASSUAN_LINELENGTH' (~1000 1050 bytes) 1051 1052 DATA_CB is called by Libassuan for data lines; DATA_CB_ARG is 1053 passed to it along with the data and the length. [FIXME: needs 1054 more documentation]. 1055 1056 INQUIRE_CB is called by Libassuan when the server requests 1057 additional information from the client while processing the 1058 command. This callback shall check the provided inquiry name and 1059 send the data as requested back using the 'assuan_send_data'. The 1060 server passed INQUIRY_CB_ARG along with the inquiry name to the 1061 callback. 1062 1063 STATUS_CB is called by Libassuan for each status line it receives 1064 from the server. STATUS_CB_ARG is passed along with the status 1065 line to the callback. 1066 1067 The function returns '0' success or an error value. The error 1068 value may be the one one returned by the server in error lines or 1069 one generated by the callback functions. 1070 1071 Libassuan supports descriptor passing on some platforms. The next 1072two functions are used with this feature: 1073 1074 -- Function: gpg_error_t assuan_sendfd (assuan_context_t CTX, 1075 assuan_fd_t FD) 1076 1077 Send the descriptor FD to the peer using the context CTX. The 1078 descriptor must be sent before the command is issued that makes use 1079 of the descriptor. 1080 1081 Note that calling this function with a CTX of 'NULL' and FD of 1082 'ASSUAN_INVALID_FD' can be used as a runtime test to check whether 1083 descriptor passing is available on the platform: '0' is returned if 1084 descriptor passing is available, otherwise an error with the error 1085 code 'GPG_ERR_NOT_IMPLEMENTED' is returned. 1086 1087 -- Function: gpg_error_t assuan_receivefd (assuan_context_t CTX, 1088 assuan_fd_t *FD) 1089 1090 Receive a descriptor pending for the context CTX from the peer. 1091 The descriptor must be pending before this function is called. To 1092 accomplish this, the peer needs to use 'assuan_sendfd' before the 1093 trigger is sent (e.g. using 'assuan_write_line ("INPUT FD")'. 1094 1095 1096File: assuan.info, Node: Server code, Next: External I/O Loop, Prev: Client code, Up: Top 1097 10987 How to develop an Assuan server 1099********************************* 1100 1101Implementing a server for Assuan is a bit more complex than a client. 1102However, it is a straightforward task we are going to explain using a 1103commented example. 1104 1105The list of the implemented server commands is defined by a table like: 1106 1107 static struct { 1108 const char *name; 1109 int (*handler) (assuan_context_t, char *line); 1110 } command_table[] = { 1111 { "FOO", cmd_foo }, 1112 { "BAR", cmd_bar }, 1113 { "INPUT", NULL }, 1114 { "OUTPUT", NULL }, 1115 { NULL }}; 1116 1117 For convenience this table is usually put after the actual command 1118handlers ('cmd_foo', 'cmd_bar') or even put inside 'command_handler' 1119(see below). Note that the commands 'INPUT' and 'OUTPUT' do not require 1120a handler because Libassuan provides a default handler for them. It is 1121however possible to assign a custom handler. 1122 1123 A prerequisite for this example code is that a client has already 1124connected to the server. Often there are two modes combined in one 1125program: A pipe-based server, where a client has forked the server 1126process, or a Unix domain socket based server that is listening on the 1127socket. 1128 1129 void 1130 command_handler (int fd) 1131 { 1132 gpg_error_t rc; 1133 int i; 1134 assuan_context_t ctx; 1135 1136 rc = assuan_new (&ctx); 1137 if (rc) 1138 { 1139 fprintf (stderr, "server context creation failed: %s\n", 1140 gpg_strerror(rc)); 1141 return; 1142 } 1143 1144 if (fd == -1) 1145 { 1146 assuan_fd_t filedes[2]; 1147 1148 filedes[0] = assuan_fd_from_posix_fd (0); 1149 filedes[1] = assuan_fd_from_posix_fd (1); 1150 rc = assuan_init_pipe_server (ctx, filedes); 1151 } 1152 else 1153 rc = assuan_init_socket_server (ctx, fd, ASSUAN_SOCKET_SERVER_ACCEPTED); 1154 if (rc) 1155 { 1156 fprintf (stderr, "server init failed: %s\n", gpg_strerror (rc)); 1157 return; 1158 } 1159 1160This is the first part of the command handler. We start off by 1161allocating a new Assuan context with 'assuan_new'. *Note function 1162assuan_new::. 1163 1164 In case this is called as a pipe based server, FD will be based as FD 1165and the code assumes that the server's 'stdin' and 'stdout' file handles 1166are connected to a pipe. The initialization is thus done using the 1167function: 1168 1169 -- Function: gpg_error_t assuan_init_pipe_server (assuan_context_t CTX, 1170 assuan_fd_t FILEDES[2]) 1171 1172 This function takes the two file descriptors from FILEDES and 1173 returns a new Assuan context at R_CTX. As usual, a return value of 1174 '0' indicates success and a failure is indicated by returning an 1175 error value. In case of error, 'NULL' will be stored at R_CTX. 1176 1177 In case the server has been called using a bi-directional pipe 1178 (socketpair), FILEDES is ignored and the file descriptor is taken 1179 from the environment variable '_assuan_connection_fd'. You 1180 generally don't need to know this, because 'assuan_pipe_connect', 1181 which is called by the client to connect to such a server, 1182 automagically sets this variable. 1183 1184 -- Function: gpg_error_t assuan_init_socket_server 1185 (assuan_context_t CTX, assuan_fd_t FD, unsigned int FLAGS) 1186 1187 This function takes the file descriptor FD, which is expected to be 1188 associated with a socket, and an Assuan context CTX. The following 1189 bits are currently defined for FLAGS: 1190 1191 'ASSUAN_SOCKET_SERVER_FDPASSING' 1192 If set, 'sendmsg' and 'recvmesg' are used for input and 1193 output, which enables the use of descriptor passing. 1194 'ASSUAN_SOCKET_SERVER_ACCEPTED' 1195 If set, FD refers to an already accepted socket. That is, 1196 Libassuan won't call ACCEPT for it. It is suggested to set 1197 this bit as it allows better control of the connection state. 1198 1199 As usual, a return value of '0' indicates success and a failure is 1200 indicated by returning an error value. 1201 1202On the Windows platform the following function needs to be called after 1203'assuan_init_socket_server': 1204 1205 -- Function: void assuan_set_sock_nonce ( assuan_context_t CTX, 1206 assuan_sock_nonce_t *NONCE) 1207 1208 Save a copy of NONCE in context CTX. This should be used to 1209 register the server's nonce with a context established by 1210 'assuan_init_socket_server'. It is technically only needed for 1211 Windows, but it does no harm to use it on other systems. 1212 1213After error checking, the implemented assuan commands are registered 1214with the server. 1215 1216 for (i = 0; command_table[i].name; i++) 1217 { 1218 rc = assuan_register_command (ctx, 1219 command_table[i].name, 1220 command_table[i].handler, NULL); 1221 if (rc) 1222 { 1223 fprintf (stderr, "register failed: %s\n", gpg_strerror (rc)); 1224 assuan_release (ctx); 1225 return; 1226 } 1227 } 1228 1229 -- Data type: gpg_error_t (*assuan_handler_t) (assuan_context_t CTX, 1230 char *LINE) 1231 This is the function invoked by ASSUAN for various command related 1232 callback functions. Some of these callback functions have a 1233 different type, but most use 'assuan_handler_t'. 1234 1235 -- Function: gpg_error_t assuan_register_command (assuan_context_t CTX, 1236 const char *CMD_STRING, assuan_handler_t HANDLER, 1237 const char *HELP_STRING) 1238 1239 This registers the command named CMD_STRING with the Assuan context 1240 CTX. HANDLER is the function called by Libassuan if this command 1241 is received from the client. NULL may be used for HANDLER to use a 1242 default handler (this only works with a few pre-defined commands). 1243 Note that several default handlers have already been registered 1244 when the context has been created: 'NOP', 'CANCEL', 'OPTION', 1245 'BYE', 'AUTH', 'RESET' and 'END'. It is possible, but not 1246 recommended, to override these commands. 1247 1248 HELP_STRING is a help string that is used for automatic 1249 documentation. It should contain a usage line followed by an empty 1250 line and a complete description. 1251 1252 -- Function: gpg_error_t assuan_register_post_cmd_notify 1253 (assuan_context_t CTX, void (*FNC)(assuan_context_t), 1254 gpg_error_t ERR) 1255 1256 Register a function to be called right after a command has been 1257 processed. ERR is the result code from the last internal assuan 1258 operation and not the one returned by the handler. It may be used 1259 for command-related cleanup. 1260 1261 -- Function: gpg_error_t assuan_register_bye_notify 1262 (assuan_context_t CTX, assuan_handler_t HANDLER) 1263 1264 Register function FNC with context CTX to be called right before 1265 the standard handler for the 'BYE' command is being called. 1266 1267 -- Function: gpg_error_t assuan_register_reset_notify 1268 (assuan_context_t CTX, assuan_handler_t HANDLER) 1269 1270 Register function FNC with context CTX to be called right before 1271 the standard handler for the 'RESET' command is being called. 1272 1273 -- Function: gpg_error_t assuan_register_cancel_notify 1274 (assuan_context_t CTX, assuan_handler_t HANDLER) 1275 1276 Register function FNC with context CTX to be called right before 1277 the standard handler for the 'RESET' command is being called. 1278 1279 -- Function: gpg_error_t assuan_register_option_handler 1280 (assuan_context_t CTX, 1281 gpg_error_t (*FNC)(assuan_context_t, const char*, const char*)) 1282 1283 Register function FNC with context CTX for processing options. 1284 That function is being called with the context, the name and the 1285 value of the option. Leading and trailing spaces are removed from 1286 the name and the value. The optional leading two dashes of the 1287 name are removed as well. If no value has been given, an empty 1288 string is passed. The function needs to return '0' on success or 1289 an error code. 1290 1291 -- Function: gpg_error_t assuan_register_input_notify 1292 (assuan_context_t CTX, assuan_handler_t HANDLER) 1293 1294 Although the input function may be overridden with a custom 1295 handler, it is often more convenient to use the default handler and 1296 to know whether an 'INPUT' command has been seen and successfully 1297 parsed. The second argument passed to that function is the entire 1298 line. Because that line has already been parsed when the function 1299 gets called, a file descriptor set with the 'INPUT' command may 1300 already be used. That file descriptor is available by calling 1301 'assuan_get_input_fd'. If the notification function returns an 1302 error, the input fd does not change. 1303 1304 -- Function: gpg_error_t assuan_register_output_notify 1305 (assuan_context_t CTX, assuan_handler_t HANDLER) 1306 1307 Although the output function may be overridden with a custom 1308 handler, it is often more convenient to use the default handler and 1309 to know whether an 'OUTPUT' command has been seen and successfully 1310 parsed. The second argument passed to that function is the entire 1311 line. Because that line has already been parsed when the function 1312 gets called, a file descriptor set with the 'OUTPUT' command may 1313 already be used. That file descriptor is available by calling 1314 'assuan_get_output_fd'. If the notification function returns an 1315 error, the output fd does not change. 1316 1317 -- Function: gpg_error_t assuan_set_hello_line (assuan_context_t CTX, 1318 const char *LINE) 1319 1320 This is not actually a register function but may be called also 1321 after registering commands. It changes the "Hello" line, sent by 1322 the server to the client as a first response, from a default string 1323 to the string LINE. For logging purposes, it is often useful to 1324 use such a custom hello line which may tell version numbers and 1325 such. Linefeeds are allowed in this string, however, each line 1326 needs to be shorter than the Assuan line length limit. 1327 1328Now that everything has been setup, we can start to process our clients 1329requests. 1330 1331 for (;;) 1332 { 1333 rc = assuan_accept (ctx); 1334 if (rc == -1) 1335 break; 1336 else if (rc) 1337 { 1338 fprintf (stderr, "accept problem: %s\n", gpg_strerror (rc)); 1339 break; 1340 } 1341 1342 rc = assuan_process (ctx); 1343 if (rc) 1344 { 1345 fprintf (stderr, "processing failed: %s\n", gpg_strerror (rc)); 1346 continue; 1347 } 1348 } 1349 assuan_release (ctx); 1350 } 1351 1352For future extensibility and to properly detect the end of the 1353connection the core of the server should loop over the accept and 1354process calls. 1355 1356 -- Function: gpg_error_t assuan_accept (assuan_context_t CTX) 1357 1358 A call to this function cancel any existing connection and waits 1359 for a connection from a client (that might be skipped, depending on 1360 the type of the server). The initial handshake is performed which 1361 may include an initial authentication or encryption negotiation. 1362 On success '0' is returned. An error value will be returned if the 1363 connection could for some reason not be established. An error code 1364 of 'GPG_ERR_EOF' indicates the end of the connection. 1365 1366 -- Function: gpg_error_t assuan_process (assuan_context_t CTX) 1367 1368 This function is used to handle the Assuan protocol after a 1369 connection has been established using 'assuan_accept'. It is the 1370 main protocol handler responsible for reading the client commands 1371 and calling the appropriate handlers. The function returns '0' on 1372 success or an error value if something went seriously wrong. Error 1373 values from the individual command handlers, i.e. operational 1374 error, are not seen here. 1375 1376That is all needed for the server code. You only need to come up with 1377the code for the individual command handlers. Take care that the line 1378passed to the command handlers is allocated statically within the 1379context and calls to Assuan functions may modify that line. You are 1380also allowed to modify that line which makes parsing much easier. 1381 1382 1383File: assuan.info, Node: External I/O Loop, Next: Utilities, Prev: Server code, Up: Top 1384 13858 How to use external I/O event loops 1386************************************* 1387 1388The above implementations of an Assuan client and server are 1389synchronous, insofar as the main routines block until a request or 1390client connection is completely processed. In some programs, for 1391example GUI applications, this is undesirable. Instead, Assuan 1392operations should be non-blocking, and the caller should be able to poll 1393all involved file descriptors to determine when the next Assuan function 1394can be invoked without blocking. 1395 1396 To make this possible, client and server have to adhere to some 1397rules: 1398 * Either partner should always write full lines. If partial lines 1399 are written, the remainder of the line should be sent without 1400 delay. 1401 * Either partner should eagerly receive status messages. While 1402 receiving and sending bulk data may be delayed, the status 1403 communication channel is different: Both partners may send status 1404 messages in blocking mode at any time the protocol allows them to 1405 send such status messages. To ensure that these send operations do 1406 not actually block the sender, the recipient must be ready to 1407 receive without undue delay. 1408 * If descriptor passing is used over a socket, the descriptor must be 1409 sent after the corresponding command without undue delay. 1410 1411 Together, these restrictions allow to limit the need for asynchronous 1412I/O operations to bulk data and the inbound status file descriptor. 1413 1414 In addition to the above rules, client and server should adhere to 1415the following implementation guidelines. 1416 1417* Menu: 1418 1419* External I/O Loop Client:: External I/O event loops in the client. 1420* External I/O Loop Server:: External I/O event loops in the server. 1421 1422 1423File: assuan.info, Node: External I/O Loop Client, Next: External I/O Loop Server, Up: External I/O Loop 1424 14258.1 External I/O event loops in the client. 1426=========================================== 1427 1428The reference implementation for using external I/O event loops in the 1429client is the GPGME library, which exports its own external I/O event 1430loop mechanism and utilizes the Assuan library transparently for the 1431user. The following steps document how GPGME achieves this. 1432 1433 1. Before connecting, set up pipes for bulk data transfer (using the 1434 INPUT/OUTPUT commands, for example). These are passed to the 1435 server either by inheritance (using a pipe server) or by FD passing 1436 (using a socket server). 1437 1438 2. Then you need to connect to the server. GPGME uses a pipe server, 1439 so it just spawns a server process, which is a non-blocking 1440 operation. FIXME: Currently, using a client with external event 1441 loop over a socket connection is not supported. It is easy to 1442 support (we just need a variation of 'assuan_socket_connect' which 1443 takes an already connected socket FD and turns it into an Assuan 1444 context), so if you need this let us know. 1445 1446 3. After connecting, get the inbound status FD with 1447 'assuan_get_active_fds' (the first one returned is the status FD). 1448 This FD can be duplicated if it is convenient (GPGME does this to 1449 be able to close this FD and associated callback handlers without 1450 disrupting Assuan's internals). 1451 1452 4. Then register the Assuan inbound status FD and all bulk data FDs 1453 with the I/O event mechanism. In general, this requires setting up 1454 callback handlers for these FDs and registering them with the main 1455 event loop. 1456 1457 5. When bulk data FDs become ready, you can simply perform the 1458 corresponding read or write operations. When the inbound status FD 1459 becomes ready, you can receive the next server line with 1460 assuan_read_line(). 1461 1462 6. You should close and unregister the bulk data FDs when you wrote 1463 all data (for outbound FDs) or receive an EOF (for inbound FDs). 1464 When you receive an ERR from the server, or an OK for the final 1465 operation, you can unregister the inbound status FD and call 1466 'assuan_release'. 1467 1468 7. As noted above, all send operations on the outbound status FD are 1469 done immediate with blocking. In GPGME, this has never caused any 1470 problems. 1471 1472 8. The 'INQUIRE' function can be handled in two ways: If the requested 1473 data is immediately available, the client can just send the data 1474 blockingly. If the requested data needs to be fetched from a 1475 blocking source, a callback handler can be registered for the FD 1476 with the main event loop. GPGME does not support the 'INQUIRE' 1477 function, so we do not have any practical experience with this. 1478 1479 Currently, the client can not cancel a pending operation gracefully. 1480It can, however, disconnect from the server at any time. It is the 1481responsibility of the server to periodically send status messages to the 1482client to probe if the connection remains alive. 1483 1484 1485File: assuan.info, Node: External I/O Loop Server, Prev: External I/O Loop Client, Up: External I/O Loop 1486 14878.2 External I/O event loops in the server. 1488=========================================== 1489 1490Currently, no Assuan server exists which uses external I/O event loops. 1491However, the following guidelines should lead to a usable 1492implementation: 1493 1494 1. For socket servers: You can not use 'assuan_accept', so you should 1495 just implement the bind/connect/listen/accept stage yourself. You 1496 can register the listen FD with your main event loop, accept the 1497 connection when it becomes ready, and finally call 1498 'assuan_init_socket_server' with the final argument being 1499 'ASSUAN_SOCKET_SERVER_ACCEPTED' to create an Assuan context for 1500 this connection. This way you can also handle multiple connections 1501 in parallel. The reference implementation for this approach is 1502 DirMngr. 1503 1504 For pipe servers: 'assuan_init_pipe_server' creates an Assuan 1505 context valid for the pipe FDs. 1506 1507 2. Once you have a context for a single connection, you can get the 1508 inbound status FD with 'assuan_get_active_fds' (the first one 1509 returned is the status FD). This FD can be duplicated if it is 1510 convenient. Every time the inbound status FD is readable, you 1511 should invoke the function 'assuan_process_next' (see below) to 1512 process the next incoming message. 'assuan_process_next' processes 1513 as many status lines as can be received by a single 'read' 1514 operation. When it returns, the inbound status FD may still be 1515 readable, but Assuan does not check this. 1516 1517 The function 'assuan_process_next' returns 0 if it can not make 1518 progress reliably, and it returns true in 'done' if the client 1519 closed the connection. See below for more information on this 1520 function. 1521 1522 3. The command will be dispatched by 'assuan_process_next' just as 1523 with 'assuan_process', however, you will want to implement the 1524 command handlers in such a way that they do not block. For 1525 example, the command handler may just register the bulk data FDs 1526 with the main event loop and return. 1527 1528 When the command is finished, irregardless if this happens directly 1529 in the command handler or later, you must call 1530 'assuan_process_done' with an appropriate error value (or 0 for 1531 success) to return an appropriate status line to the client. You 1532 can do this at the end of the command handler, for example by 1533 ending it with 'return assuan_process_done (error_code);'. Another 1534 possibility is to invoke 'assuan_process_done' from the place in 1535 the code which closes the last active bulk FD registered with the 1536 main event loop for this operation. 1537 1538 It is not possible to use 'assuan_inquire' in a command handler, as 1539this function blocks on receiving the inquired data from the client. 1540Instead, the asynchronous version 'assuan_inquire_ext' needs to be used 1541(see below), which invokes a callback when the client provided the 1542inquired data. A typical usage would be for the command handler to 1543register a continuation with 'assuan_inquire_ext' and return 0. 1544Eventually, the continuation would be invoked by 'assuan_process_next' 1545when the client data arrived. The continuation could complete the 1546command and eventually call 'assuan_process_done'. 1547 1548 Cancellation is supported by returning an appropriate error value to 1549the client with 'assuan_process_done'. For long running operations, the 1550server should send progress status messages to the client in regular 1551intervals to notice when the client disconnects. 1552 1553 -- Function: gpg_error_t assuan_process_next (assuan_context_t CTX, 1554 int *DONE) 1555 This is the same as 'assuan_process' but the caller has to provide 1556 the outer loop. He should loop as long as the return code is zero 1557 and DONE is false. 1558 1559 -- Function: gpg_error_t assuan_process_done (assuan_context_t CTX, 1560 gpg_error_t RC) 1561 Finish a pending command and return the error code RC to the 1562 client. 1563 1564 -- Function: gpg_error_t assuan_inquire_ext (assuan_context_t CTX, 1565 const char *KEYWORD, size_t MAXLEN, 1566 gpg_error_t (*CB) (void *cb_data, gpg_error_t rc, unsigned char *buffer, size_t buffer_len), 1567 void *CB_DATA) 1568 This is similar to 'assuan_inquire' but the caller has to provide 1569 the outer loop (using 'assuan_process_next'). The caller should 1570 specify a continuation with CB, which receives CB_DATA as its first 1571 argument, and the error value as well as the inquired data as its 1572 remaining arguments. 1573 1574 1575File: assuan.info, Node: Utilities, Next: Socket wrappers, Prev: External I/O Loop, Up: Top 1576 15779 Utility functions 1578******************* 1579 1580There are a lot of helper functions to make writing Assuan code easier. 1581Some of these functions provide information not available with the 1582general functions. 1583 1584 -- Function: gpg_error_t assuan_write_status (assuan_context_t CTX, 1585 const char *KEYWORD, const char *TEXT) 1586 1587 This is a convenience function for a server to send a status line. 1588 You need to pass it the KEYWORD and the content of the status line 1589 in TEXT. 1590 1591 -- Function: gpg_error_t assuan_inquire (assuan_context_t CTX, 1592 const char *KEYWORD, unsigned char **R_BUFFER, 1593 size_t *R_LENGTH, size_t MAXLEN) 1594 1595 A server may use this function to request specific data from a 1596 client. This function sends an 'INQUIRE' command back to the 1597 client and returns the client's response in a newly allocated 1598 buffer. You need to pass at least the server's context (CTX) and a 1599 description of the required data (KEYWORD). All other parameters 1600 may be 'NULL' or '0', but this is rarely useful. 1601 1602 On success the result is stored in a newly allocated buffer stored 1603 at R_BUFFER. The length of the data is stored at R_LENGTH. If 1604 MAXLEN has not been given as '0', it specifies an upper size limit 1605 of the expected data. If the client returns too much data the 1606 function fails and an error with the error code 1607 'GPG_ERR_ASS_TOO_MUCH_DATA' will be returned. 1608 1609 -- Function: FILE* assuan_get_data_fp (assuan_context_t CTX) 1610 1611 Return a stdio stream for the Assuan context CTX. This stream may 1612 then be used for data output (assuan_write_data). The stream is 1613 valid until the end of the current handler. Calling 'fclose' for 1614 that stream is not required. Assuan does all the buffering needed 1615 to insert the status line as well as the required line wrapping and 1616 quoting for data lines. 1617 1618 This function is only available on systems supporting either 1619 'funopen' or 'fopencookie'. If it is not supported 'NULL' is 1620 returned and 'errno' is set to 'ENOSYS'. 1621 1622 -- Function: gpg_error_t assuan_set_okay_line (assuan_context_t CTX, 1623 const char *LINE) 1624 1625 Set the text used for the next 'OK' response to LINE. This is 1626 sometimes useful to send additional human readable information 1627 along with the OK line. The string is automatically reset at the 1628 end of the current handler. 1629 1630 -- Function: gpg_error_t assuan_command_parse_fd (assuan_context_t CTX, 1631 char *LINE, assuan_fd_t *RFD) 1632 1633 This is the core of the default 'INPUT' and 'OUTPUT' handler. It 1634 may be used in custom commands as well to negotiate a file 1635 descriptor. If LINE contains 'FD=N', it returns N in RFD assuming 1636 a local file descriptor. If LINE contains just 'FD' it returns a 1637 file descriptor at RFD; this file descriptor needs to have been 1638 sent by the client right before using 'assuan_sendfd'. 1639 1640 On W32 systems the returned file descriptor is a system handle and 1641 not a libc low level I/O file descriptor. Thus applications need 1642 to use '_open_osfhandle' before they can pass this descriptor to 1643 standard functions like 'fdopen' or 'dup'. 1644 1645 -- Function: const char * assuan_get_command_name 1646 (assuan_context_t CTX) 1647 1648 Return the name of the command currently processed by a handler. 1649 The returned string is valid until the next call to an Assuan 1650 function on the same context. Returns 'NULL' if no handler is 1651 executed or the command is not known. 1652 1653 -- Function: assuan_fd_t assuan_get_input_fd (assuan_context_t CTX) 1654 1655 Return the file descriptor sent by the client using the last 1656 'INPUT' command. Returns 'ASSUAN_INVALID_FD' if no file descriptor 1657 is available. 1658 1659 -- Function: assuan_fd_t assuan_get_output_fd (assuan_context_t CTX) 1660 1661 Return the file descriptor sent by the client using the last 1662 'OUTPUT' command. Returns 'ASSUAN_INVALID_FD' if no file 1663 descriptor is available. 1664 1665 -- Function: gpg_error_t assuan_close_input_fd (assuan_context_t CTX) 1666 1667 Close the file descriptor set by the last 'INPUT' command. This 1668 function has the advantage over a simple 'close' that it can do 1669 some sanity checks and make sure that a following 1670 'assuan_get_input_fd' won't return an already closed descriptor. 1671 1672 -- Function: gpg_error_t assuan_close_output_fd (assuan_context_t CTX) 1673 1674 Close the file descriptor set by the last 'OUTPUT' command. This 1675 function has the advantage over a simple 'close' that it can do 1676 some sanity checks and make sure that a following 1677 'assuan_get_input_fd' won't return an already closed descriptor. 1678 1679 -- Function: gpg_error_t assuan_set_error (assuan_context_t CTX, 1680 gpg_error_t ERR, const char *TEXT) 1681 This is a helper to provide a more descriptive error text with 1682 'ERR' lines. For this to work, the text needs to be stored in the 1683 context CTX while still being in the command handler. This 1684 function is commonly called this way 1685 return assuan_set_error (ctx, err, "commands needs 5 arguments"); 1686 The value ERR is passed through and thus the return value of the 1687 command handler in the example. The provided text further explains 1688 that error to humans. 1689 1690 -- Function: pid_t assuan_get_pid (assuan_context_t CTX) 1691 1692 This function returns the pid of the connected connected peer. If 1693 that pid is not known 'ASSUAN_INVALID_PID' is returned. Note that 1694 it is not always possible to learn the pid of the other process. 1695 For a pipe based server the client knows it instantly and a 1696 mechanism is in place to let the server learn it. For socket based 1697 servers the pid is only available on systems providing the 1698 'SO_PEERCRED' socket option (1). 1699 1700 -- Data type: assuan_peercred_t 1701 This structure is used to store the peer credentials. The 1702 available members depend on the operating system. 1703 1704 'pid_t pid' 1705 The process ID of the peer. 1706 1707 'uid_t uid' 1708 The user ID of the peer process. 1709 1710 'gid_t gid' 1711 The group ID of the peer process. 1712 1713 -- Function: gpg_error_t assuan_get_peercred (assuan_context_t CTX, 1714 assuan_peercred_t *PEERCRED) 1715 Return user credentials of the peer. This will work only on 1716 certain systems and only when connected over a socket. On success, 1717 a pointer to the peer credentials is stored in PEERCRED. The 1718 information is only valid as long as the state of the connection is 1719 unchanged (at least until the next assuan call to the same 1720 context). 1721 1722 As of now only the server is able to retrieve this information. 1723 Note, that for getting the pid of the peer 'assuan_get_pid' is 1724 usually better suited. 1725 1726 -- Function: int assuan_get_active_fds (assuan_context_t CTX, int WHAT, 1727 assuan_fd_t *FDARRAY, int FDARRAYSIZE) 1728 1729 Return all active file descriptors for the context CTX. This 1730 function can be used to select on the file descriptors and to call 1731 'assuan_process_next' if there is an active one. The first 1732 descriptor in the array is the one used for the command connection. 1733 Currently WHAT needs to be '0' to return descriptors used for 1734 reading, '1' will eventually be used to return descriptors used for 1735 writing. FDARRAY is an array of integers provided by the caller; 1736 FDARRAYSIZE gives the size of that array. 1737 1738 On success the number of active descriptors are returned. These 1739 active descriptors are then stored in FDARRAY. On error '-1' is 1740 returned; the most likely reason for this is a too small FDARRAY. 1741 1742 Note that on W32 systems the returned file descriptor is a system 1743 handle and not a libc low level I/O file descriptor. 1744 1745 -- Function: int assuan_pending_line (assuan_context_t CTX) 1746 A call to this function return true if a full line has been 1747 buffered and thus an entire assuan line may be read without 1748 triggering any actual I/O. 1749 1750 ---------- Footnotes ---------- 1751 1752 (1) to our knowledge only the Linux kernel has this feature 1753 1754 1755File: assuan.info, Node: Socket wrappers, Next: Library Copying, Prev: Utilities, Up: Top 1756 175710 Socket wrapper functions 1758*************************** 1759 1760It is sometimes useful to support Unix domain sockets on Windows. To do 1761this in a portable way, Assuan provides a set of wrapper functions which 1762may be used on any system but will enhance Windows to support these 1763socket types. The actual implementation is based on local TCP sockets 1764and fully transparent for the client. Server code needs to utilize two 1765extra functions to check the permissions. 1766 1767 -- Function: gpg_error_t assuan_sock_init (void) 1768 Initialize the socket wrappers. Must be called once at startup if 1769 any of the socket wrapper functions are used. 1770 1771 -- Function: gpg_error_t assuan_sock_deinit (void) 1772 Deinitialize the socket wrappers. 1773 1774 -- Function: int assuan_sock_close (assuan_fd_t FD) 1775 Wrapper for close which does a closesocket on Windows if needed. 1776 1777 -- Function: assuan_fd_t assuan_sock_new (int DOMAIN, int TYPE, 1778 int PROTO); 1779 Wrapper around socket. 1780 1781 -- Function: int assuan_sock_connect (assuan_fd_t SOCKFD, 1782 struct sockaddr *ADDR, int ADDRLEN) 1783 1784 Wrapper around connect. For Unix domain sockets under Windows this 1785 function also does a write immediately after the the connect to 1786 send the nonce as read from the socket's file. Under Unix this 1787 function check whether the socket file is a redirection file and 1788 connects to the redirected socket instead; see 1789 'assuan_sock_set_sockaddr_un' for details on the redirection file 1790 format. 1791 1792 -- Function: int assuan_sock_connect_byname (const char * HOST, 1793 unsigned short PORT, int RESERVED, const char *CREDENTIALS, 1794 unsigned int FLAGS) 1795 1796 Directly connect to PORT on HOST given as a name. The current 1797 implementation requires that FLAGS has either 'ASSUAN_SOCK_SOCKS' 1798 or 'ASSUAN_SOCK_TOR' set. On success a new TCP STREAM socket is 1799 returned; on error 'ASSUAN_INVALID_FD' and ERRNO set. If 1800 CREDENTIALS is not 'NULL', it is a string used for password based 1801 SOCKS authentication. Username and password are separated by a 1802 colon. RESERVED should be 0. To test whether the proxy is 1803 available HOST and PORT may be given as NULL/0: If the proxy is 1804 available the function returns a valid socket which is in the state 1805 after credentials sub-negotiation. The caller now knows that the 1806 SOCKS proxy is available and has been authenticated; normally the 1807 caller closes the socket then. 1808 1809 -- Function: int assuan_sock_bind ( assuan_fd_t SOCKFD, 1810 struct sockaddr *ADDR, int ADDRLEN) 1811 1812 Wrapper around bind. Under Windows this creates a file and writes 1813 the port number and a random nonce to this file. 1814 1815 -- Function: int assuan_sock_set_sockaddr_un ( const char *FNAME, 1816 struct sockaddr *ADDR, int *R_REDIRECTED) 1817 1818 This is a helper function to initialize the Unix socket domain 1819 address structure ADDR and store the file name FNAME there. If 1820 R_REDIRECTED is not NULL the function checks whether FNAME already 1821 exists, is a regular file, and not a socket. In that case FNAME is 1822 read to see whether this is a redirection to a socket file. If 1823 that is the case 1 is stored at R_REDIRECTED. If the file does not 1824 look like a redirection file 0 will be stored there and FNAME will 1825 be used in the regular way. 1826 1827 The format of a redirection file is 1828 1829 %Assuan% 1830 socket=NAME 1831 1832 With NAME being is the actual socket to use. No white spaces are 1833 allowed, both lines must be terminated by a single linefeed, and 1834 extra lines are not allowed. Environment variables are interpreted 1835 in NAME if given in '${VAR}' notation. No escape characters are 1836 defined; if the string '${' shall be used in file name, an 1837 environment variable with that content may be used. The length of 1838 the redirection file is limited to 511 bytes which is more than 1839 sufficient for any known implementation of Unix domain sockets. 1840 1841 -- Function: int assuan_sock_get_nonce ( struct sockaddr *ADDR, 1842 int ADDRLEN, assuan_sock_nonce_t *NONCE) 1843 1844 This is used by the server after a bind to return the random nonce. 1845 To keep the code readable this may also be used on POSIX system. 1846 1847 -- Function: int assuan_sock_check_nonce ( assuan_fd_t FD, 1848 assuan_sock_nonce_t *NONCE) 1849 1850 If the option 'ASSUAN_SOCKET_SERVER_ACCEPTED' has been used, 1851 Libassuan has no way to check the nonce of the server. Thus an 1852 explicit check of the saved nonce using this function is required. 1853 If this function fails the server should immediately drop the 1854 connection. This function may not be used if Libassuan does the 1855 accept call itself (i.e. 'ASSUAN_SOCKET_SERVER_ACCEPTED' has not 1856 been used) because in this case Libassuan calls this function 1857 internally. See also 'assuan_set_sock_nonce'. 1858 1859 Actually this mechanism is only required on Windows but for 1860 cleanness of code it may be used on POSIX systems as well, where 1861 this function is a nop. 1862 1863 To control certain properties of the wrapper two additional functions 1864are provided: 1865 1866 -- Function: int assuan_sock_set_flag ( assuan_fd_t FD, 1867 const char *NAME, int VALUE) 1868 1869 Set the flags NAME for socket FD to VALUE. See below for a list of 1870 valid names. Returns 0 on success; on failure sets ERRNO and 1871 returns -1. 1872 1873 -- Function: int assuan_sock_get_flag ( assuan_fd_t FD, 1874 const char *NAME, int *R_VALUE) 1875 1876 Store the current value of the flag NAME for socket FD at R_VALUE. 1877 See below for a list of valid names. Returns 0 on success; on 1878 failure sets ERRNO and returns -1. 1879 1880 The supported flags are: 1881 1882'cygwin' 1883 This flag has an effect only on Windows. If the value is 1, the 1884 socket is set into Cygwin mode so that Cygwin clients can connect 1885 to such a socket. This flag needs to be set before a bind and 1886 should not be changed during the lifetime of the socket. There is 1887 no need to set this flag for connecting to a Cygwin style socket 1888 because no state is required at the client. On non-Windows 1889 platforms setting this flag is ignored, reading the flag always 1890 returns a value of 0. 1891 1892'tor-mode' 1893'socks' 1894 If VALUE is 1 globally enable SOCKS5 mode for new connections using 1895 IPv6 or IPv4. FD must be set to 'ASSUAN_INVALID_FD' A future 1896 extension may allow to disable SOCKS5 mode for a specified socket 1897 but globally disabling SOCKS5 mode is not possible. Using the flag 1898 "tor-mode" expects the SOCKS5 proxy to listen on port 9050, the 1899 flag "socks" expects the proxy to listen on port 1080. 1900 1901 Connections to the loopback address are not routed though the SOCKS 1902 proxy. UDP requests are not supported at all. The proxy will be 1903 connected at address 127.0.0.1; an IPv6 connection to the proxy is 1904 not yet supported. 1905 1906 1907File: assuan.info, Node: Library Copying, Next: Copying, Prev: Socket wrappers, Up: Top 1908 1909GNU Lesser General Public License 1910********************************* 1911 1912 Version 2.1, February 1999 1913 1914 Copyright (C) 1991, 1999 Free Software Foundation, Inc. 1915 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA 1916 1917 Everyone is permitted to copy and distribute verbatim copies 1918 of this license document, but changing it is not allowed. 1919 1920 [This is the first released version of the Lesser GPL. It also counts 1921 as the successor of the GNU Library Public License, version 2, hence the 1922 version number 2.1.] 1923 1924Preamble 1925======== 1926 1927The licenses for most software are designed to take away your freedom to 1928share and change it. By contrast, the GNU General Public Licenses are 1929intended to guarantee your freedom to share and change free software--to 1930make sure the software is free for all its users. 1931 1932 This license, the Lesser General Public License, applies to some 1933specially designated software--typically libraries--of the Free Software 1934Foundation and other authors who decide to use it. You can use it too, 1935but we suggest you first think carefully about whether this license or 1936the ordinary General Public License is the better strategy to use in any 1937particular case, based on the explanations below. 1938 1939 When we speak of free software, we are referring to freedom of use, 1940not price. Our General Public Licenses are designed to make sure that 1941you have the freedom to distribute copies of free software (and charge 1942for this service if you wish); that you receive source code or can get 1943it if you want it; that you can change the software and use pieces of it 1944in new free programs; and that you are informed that you can do these 1945things. 1946 1947 To protect your rights, we need to make restrictions that forbid 1948distributors to deny you these rights or to ask you to surrender these 1949rights. These restrictions translate to certain responsibilities for 1950you if you distribute copies of the library or if you modify it. 1951 1952 For example, if you distribute copies of the library, whether gratis 1953or for a fee, you must give the recipients all the rights that we gave 1954you. You must make sure that they, too, receive or can get the source 1955code. If you link other code with the library, you must provide 1956complete object files to the recipients, so that they can relink them 1957with the library after making changes to the library and recompiling it. 1958And you must show them these terms so they know their rights. 1959 1960 We protect your rights with a two-step method: (1) we copyright the 1961library, and (2) we offer you this license, which gives you legal 1962permission to copy, distribute and/or modify the library. 1963 1964 To protect each distributor, we want to make it very clear that there 1965is no warranty for the free library. Also, if the library is modified 1966by someone else and passed on, the recipients should know that what they 1967have is not the original version, so that the original author's 1968reputation will not be affected by problems that might be introduced by 1969others. 1970 1971 Finally, software patents pose a constant threat to the existence of 1972any free program. We wish to make sure that a company cannot 1973effectively restrict the users of a free program by obtaining a 1974restrictive license from a patent holder. Therefore, we insist that any 1975patent license obtained for a version of the library must be consistent 1976with the full freedom of use specified in this license. 1977 1978 Most GNU software, including some libraries, is covered by the 1979ordinary GNU General Public License. This license, the GNU Lesser 1980General Public License, applies to certain designated libraries, and is 1981quite different from the ordinary General Public License. We use this 1982license for certain libraries in order to permit linking those libraries 1983into non-free programs. 1984 1985 When a program is linked with a library, whether statically or using 1986a shared library, the combination of the two is legally speaking a 1987combined work, a derivative of the original library. The ordinary 1988General Public License therefore permits such linking only if the entire 1989combination fits its criteria of freedom. The Lesser General Public 1990License permits more lax criteria for linking other code with the 1991library. 1992 1993 We call this license the "Lesser" General Public License because it 1994does _Less_ to protect the user's freedom than the ordinary General 1995Public License. It also provides other free software developers Less of 1996an advantage over competing non-free programs. These disadvantages are 1997the reason we use the ordinary General Public License for many 1998libraries. However, the Lesser license provides advantages in certain 1999special circumstances. 2000 2001 For example, on rare occasions, there may be a special need to 2002encourage the widest possible use of a certain library, so that it 2003becomes a de-facto standard. To achieve this, non-free programs must be 2004allowed to use the library. A more frequent case is that a free library 2005does the same job as widely used non-free libraries. In this case, 2006there is little to gain by limiting the free library to free software 2007only, so we use the Lesser General Public License. 2008 2009 In other cases, permission to use a particular library in non-free 2010programs enables a greater number of people to use a large body of free 2011software. For example, permission to use the GNU C Library in non-free 2012programs enables many more people to use the whole GNU operating system, 2013as well as its variant, the GNU/Linux operating system. 2014 2015 Although the Lesser General Public License is Less protective of the 2016users' freedom, it does ensure that the user of a program that is linked 2017with the Library has the freedom and the wherewithal to run that program 2018using a modified version of the Library. 2019 2020 The precise terms and conditions for copying, distribution and 2021modification follow. Pay close attention to the difference between a 2022"work based on the library" and a "work that uses the library". The 2023former contains code derived from the library, whereas the latter must 2024be combined with the library in order to run. 2025 2026 GNU LESSER GENERAL PUBLIC LICENSE 2027 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 2028 2029 0. This License Agreement applies to any software library or other 2030 program which contains a notice placed by the copyright holder or 2031 other authorized party saying it may be distributed under the terms 2032 of this Lesser General Public License (also called "this License"). 2033 Each licensee is addressed as "you". 2034 2035 A "library" means a collection of software functions and/or data 2036 prepared so as to be conveniently linked with application programs 2037 (which use some of those functions and data) to form executables. 2038 2039 The "Library", below, refers to any such software library or work 2040 which has been distributed under these terms. A "work based on the 2041 Library" means either the Library or any derivative work under 2042 copyright law: that is to say, a work containing the Library or a 2043 portion of it, either verbatim or with modifications and/or 2044 translated straightforwardly into another language. (Hereinafter, 2045 translation is included without limitation in the term 2046 "modification".) 2047 2048 "Source code" for a work means the preferred form of the work for 2049 making modifications to it. For a library, complete source code 2050 means all the source code for all modules it contains, plus any 2051 associated interface definition files, plus the scripts used to 2052 control compilation and installation of the library. 2053 2054 Activities other than copying, distribution and modification are 2055 not covered by this License; they are outside its scope. The act 2056 of running a program using the Library is not restricted, and 2057 output from such a program is covered only if its contents 2058 constitute a work based on the Library (independent of the use of 2059 the Library in a tool for writing it). Whether that is true 2060 depends on what the Library does and what the program that uses the 2061 Library does. 2062 2063 1. You may copy and distribute verbatim copies of the Library's 2064 complete source code as you receive it, in any medium, provided 2065 that you conspicuously and appropriately publish on each copy an 2066 appropriate copyright notice and disclaimer of warranty; keep 2067 intact all the notices that refer to this License and to the 2068 absence of any warranty; and distribute a copy of this License 2069 along with the Library. 2070 2071 You may charge a fee for the physical act of transferring a copy, 2072 and you may at your option offer warranty protection in exchange 2073 for a fee. 2074 2075 2. You may modify your copy or copies of the Library or any portion of 2076 it, thus forming a work based on the Library, and copy and 2077 distribute such modifications or work under the terms of Section 1 2078 above, provided that you also meet all of these conditions: 2079 2080 a. The modified work must itself be a software library. 2081 2082 b. You must cause the files modified to carry prominent notices 2083 stating that you changed the files and the date of any change. 2084 2085 c. You must cause the whole of the work to be licensed at no 2086 charge to all third parties under the terms of this License. 2087 2088 d. If a facility in the modified Library refers to a function or 2089 a table of data to be supplied by an application program that 2090 uses the facility, other than as an argument passed when the 2091 facility is invoked, then you must make a good faith effort to 2092 ensure that, in the event an application does not supply such 2093 function or table, the facility still operates, and performs 2094 whatever part of its purpose remains meaningful. 2095 2096 (For example, a function in a library to compute square roots 2097 has a purpose that is entirely well-defined independent of the 2098 application. Therefore, Subsection 2d requires that any 2099 application-supplied function or table used by this function 2100 must be optional: if the application does not supply it, the 2101 square root function must still compute square roots.) 2102 2103 These requirements apply to the modified work as a whole. If 2104 identifiable sections of that work are not derived from the 2105 Library, and can be reasonably considered independent and separate 2106 works in themselves, then this License, and its terms, do not apply 2107 to those sections when you distribute them as separate works. But 2108 when you distribute the same sections as part of a whole which is a 2109 work based on the Library, the distribution of the whole must be on 2110 the terms of this License, whose permissions for other licensees 2111 extend to the entire whole, and thus to each and every part 2112 regardless of who wrote it. 2113 2114 Thus, it is not the intent of this section to claim rights or 2115 contest your rights to work written entirely by you; rather, the 2116 intent is to exercise the right to control the distribution of 2117 derivative or collective works based on the Library. 2118 2119 In addition, mere aggregation of another work not based on the 2120 Library with the Library (or with a work based on the Library) on a 2121 volume of a storage or distribution medium does not bring the other 2122 work under the scope of this License. 2123 2124 3. You may opt to apply the terms of the ordinary GNU General Public 2125 License instead of this License to a given copy of the Library. To 2126 do this, you must alter all the notices that refer to this License, 2127 so that they refer to the ordinary GNU General Public License, 2128 version 2, instead of to this License. (If a newer version than 2129 version 2 of the ordinary GNU General Public License has appeared, 2130 then you can specify that version instead if you wish.) Do not 2131 make any other change in these notices. 2132 2133 Once this change is made in a given copy, it is irreversible for 2134 that copy, so the ordinary GNU General Public License applies to 2135 all subsequent copies and derivative works made from that copy. 2136 2137 This option is useful when you wish to copy part of the code of the 2138 Library into a program that is not a library. 2139 2140 4. You may copy and distribute the Library (or a portion or derivative 2141 of it, under Section 2) in object code or executable form under the 2142 terms of Sections 1 and 2 above provided that you accompany it with 2143 the complete corresponding machine-readable source code, which must 2144 be distributed under the terms of Sections 1 and 2 above on a 2145 medium customarily used for software interchange. 2146 2147 If distribution of object code is made by offering access to copy 2148 from a designated place, then offering equivalent access to copy 2149 the source code from the same place satisfies the requirement to 2150 distribute the source code, even though third parties are not 2151 compelled to copy the source along with the object code. 2152 2153 5. A program that contains no derivative of any portion of the 2154 Library, but is designed to work with the Library by being compiled 2155 or linked with it, is called a "work that uses the Library". Such 2156 a work, in isolation, is not a derivative work of the Library, and 2157 therefore falls outside the scope of this License. 2158 2159 However, linking a "work that uses the Library" with the Library 2160 creates an executable that is a derivative of the Library (because 2161 it contains portions of the Library), rather than a "work that uses 2162 the library". The executable is therefore covered by this License. 2163 Section 6 states terms for distribution of such executables. 2164 2165 When a "work that uses the Library" uses material from a header 2166 file that is part of the Library, the object code for the work may 2167 be a derivative work of the Library even though the source code is 2168 not. Whether this is true is especially significant if the work 2169 can be linked without the Library, or if the work is itself a 2170 library. The threshold for this to be true is not precisely 2171 defined by law. 2172 2173 If such an object file uses only numerical parameters, data 2174 structure layouts and accessors, and small macros and small inline 2175 functions (ten lines or less in length), then the use of the object 2176 file is unrestricted, regardless of whether it is legally a 2177 derivative work. (Executables containing this object code plus 2178 portions of the Library will still fall under Section 6.) 2179 2180 Otherwise, if the work is a derivative of the Library, you may 2181 distribute the object code for the work under the terms of Section 2182 6. Any executables containing that work also fall under Section 6, 2183 whether or not they are linked directly with the Library itself. 2184 2185 6. As an exception to the Sections above, you may also combine or link 2186 a "work that uses the Library" with the Library to produce a work 2187 containing portions of the Library, and distribute that work under 2188 terms of your choice, provided that the terms permit modification 2189 of the work for the customer's own use and reverse engineering for 2190 debugging such modifications. 2191 2192 You must give prominent notice with each copy of the work that the 2193 Library is used in it and that the Library and its use are covered 2194 by this License. You must supply a copy of this License. If the 2195 work during execution displays copyright notices, you must include 2196 the copyright notice for the Library among them, as well as a 2197 reference directing the user to the copy of this License. Also, 2198 you must do one of these things: 2199 2200 a. Accompany the work with the complete corresponding 2201 machine-readable source code for the Library including 2202 whatever changes were used in the work (which must be 2203 distributed under Sections 1 and 2 above); and, if the work is 2204 an executable linked with the Library, with the complete 2205 machine-readable "work that uses the Library", as object code 2206 and/or source code, so that the user can modify the Library 2207 and then relink to produce a modified executable containing 2208 the modified Library. (It is understood that the user who 2209 changes the contents of definitions files in the Library will 2210 not necessarily be able to recompile the application to use 2211 the modified definitions.) 2212 2213 b. Use a suitable shared library mechanism for linking with the 2214 Library. A suitable mechanism is one that (1) uses at run 2215 time a copy of the library already present on the user's 2216 computer system, rather than copying library functions into 2217 the executable, and (2) will operate properly with a modified 2218 version of the library, if the user installs one, as long as 2219 the modified version is interface-compatible with the version 2220 that the work was made with. 2221 2222 c. Accompany the work with a written offer, valid for at least 2223 three years, to give the same user the materials specified in 2224 Subsection 6a, above, for a charge no more than the cost of 2225 performing this distribution. 2226 2227 d. If distribution of the work is made by offering access to copy 2228 from a designated place, offer equivalent access to copy the 2229 above specified materials from the same place. 2230 2231 e. Verify that the user has already received a copy of these 2232 materials or that you have already sent this user a copy. 2233 2234 For an executable, the required form of the "work that uses the 2235 Library" must include any data and utility programs needed for 2236 reproducing the executable from it. However, as a special 2237 exception, the materials to be distributed need not include 2238 anything that is normally distributed (in either source or binary 2239 form) with the major components (compiler, kernel, and so on) of 2240 the operating system on which the executable runs, unless that 2241 component itself accompanies the executable. 2242 2243 It may happen that this requirement contradicts the license 2244 restrictions of other proprietary libraries that do not normally 2245 accompany the operating system. Such a contradiction means you 2246 cannot use both them and the Library together in an executable that 2247 you distribute. 2248 2249 7. You may place library facilities that are a work based on the 2250 Library side-by-side in a single library together with other 2251 library facilities not covered by this License, and distribute such 2252 a combined library, provided that the separate distribution of the 2253 work based on the Library and of the other library facilities is 2254 otherwise permitted, and provided that you do these two things: 2255 2256 a. Accompany the combined library with a copy of the same work 2257 based on the Library, uncombined with any other library 2258 facilities. This must be distributed under the terms of the 2259 Sections above. 2260 2261 b. Give prominent notice with the combined library of the fact 2262 that part of it is a work based on the Library, and explaining 2263 where to find the accompanying uncombined form of the same 2264 work. 2265 2266 8. You may not copy, modify, sublicense, link with, or distribute the 2267 Library except as expressly provided under this License. Any 2268 attempt otherwise to copy, modify, sublicense, link with, or 2269 distribute the Library is void, and will automatically terminate 2270 your rights under this License. However, parties who have received 2271 copies, or rights, from you under this License will not have their 2272 licenses terminated so long as such parties remain in full 2273 compliance. 2274 2275 9. You are not required to accept this License, since you have not 2276 signed it. However, nothing else grants you permission to modify 2277 or distribute the Library or its derivative works. These actions 2278 are prohibited by law if you do not accept this License. 2279 Therefore, by modifying or distributing the Library (or any work 2280 based on the Library), you indicate your acceptance of this License 2281 to do so, and all its terms and conditions for copying, 2282 distributing or modifying the Library or works based on it. 2283 2284 10. Each time you redistribute the Library (or any work based on the 2285 Library), the recipient automatically receives a license from the 2286 original licensor to copy, distribute, link with or modify the 2287 Library subject to these terms and conditions. You may not impose 2288 any further restrictions on the recipients' exercise of the rights 2289 granted herein. You are not responsible for enforcing compliance 2290 by third parties with this License. 2291 2292 11. If, as a consequence of a court judgment or allegation of patent 2293 infringement or for any other reason (not limited to patent 2294 issues), conditions are imposed on you (whether by court order, 2295 agreement or otherwise) that contradict the conditions of this 2296 License, they do not excuse you from the conditions of this 2297 License. If you cannot distribute so as to satisfy simultaneously 2298 your obligations under this License and any other pertinent 2299 obligations, then as a consequence you may not distribute the 2300 Library at all. For example, if a patent license would not permit 2301 royalty-free redistribution of the Library by all those who receive 2302 copies directly or indirectly through you, then the only way you 2303 could satisfy both it and this License would be to refrain entirely 2304 from distribution of the Library. 2305 2306 If any portion of this section is held invalid or unenforceable 2307 under any particular circumstance, the balance of the section is 2308 intended to apply, and the section as a whole is intended to apply 2309 in other circumstances. 2310 2311 It is not the purpose of this section to induce you to infringe any 2312 patents or other property right claims or to contest validity of 2313 any such claims; this section has the sole purpose of protecting 2314 the integrity of the free software distribution system which is 2315 implemented by public license practices. Many people have made 2316 generous contributions to the wide range of software distributed 2317 through that system in reliance on consistent application of that 2318 system; it is up to the author/donor to decide if he or she is 2319 willing to distribute software through any other system and a 2320 licensee cannot impose that choice. 2321 2322 This section is intended to make thoroughly clear what is believed 2323 to be a consequence of the rest of this License. 2324 2325 12. If the distribution and/or use of the Library is restricted in 2326 certain countries either by patents or by copyrighted interfaces, 2327 the original copyright holder who places the Library under this 2328 License may add an explicit geographical distribution limitation 2329 excluding those countries, so that distribution is permitted only 2330 in or among countries not thus excluded. In such case, this 2331 License incorporates the limitation as if written in the body of 2332 this License. 2333 2334 13. The Free Software Foundation may publish revised and/or new 2335 versions of the Lesser General Public License from time to time. 2336 Such new versions will be similar in spirit to the present version, 2337 but may differ in detail to address new problems or concerns. 2338 2339 Each version is given a distinguishing version number. If the 2340 Library specifies a version number of this License which applies to 2341 it and "any later version", you have the option of following the 2342 terms and conditions either of that version or of any later version 2343 published by the Free Software Foundation. If the Library does not 2344 specify a license version number, you may choose any version ever 2345 published by the Free Software Foundation. 2346 2347 14. If you wish to incorporate parts of the Library into other free 2348 programs whose distribution conditions are incompatible with these, 2349 write to the author to ask for permission. For software which is 2350 copyrighted by the Free Software Foundation, write to the Free 2351 Software Foundation; we sometimes make exceptions for this. Our 2352 decision will be guided by the two goals of preserving the free 2353 status of all derivatives of our free software and of promoting the 2354 sharing and reuse of software generally. 2355 2356 NO WARRANTY 2357 2358 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO 2359 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE 2360 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS 2361 AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY 2362 OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT 2363 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 2364 FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND 2365 PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE 2366 DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR 2367 OR CORRECTION. 2368 2369 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 2370 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY 2371 MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE 2372 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, 2373 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR 2374 INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF 2375 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU 2376 OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY 2377 OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN 2378 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 2379 2380 END OF TERMS AND CONDITIONS 2381 2382How to Apply These Terms to Your New Libraries 2383============================================== 2384 2385If you develop a new library, and you want it to be of the greatest 2386possible use to the public, we recommend making it free software that 2387everyone can redistribute and change. You can do so by permitting 2388redistribution under these terms (or, alternatively, under the terms of 2389the ordinary General Public License). 2390 2391 To apply these terms, attach the following notices to the library. 2392It is safest to attach them to the start of each source file to most 2393effectively convey the exclusion of warranty; and each file should have 2394at least the "copyright" line and a pointer to where the full notice is 2395found. 2396 2397 ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES. 2398 Copyright (C) YEAR NAME OF AUTHOR 2399 2400 This library is free software; you can redistribute it and/or modify it 2401 under the terms of the GNU Lesser General Public License as published by 2402 the Free Software Foundation; either version 2.1 of the License, or (at 2403 your option) any later version. 2404 2405 This library is distributed in the hope that it will be useful, but 2406 WITHOUT ANY WARRANTY; without even the implied warranty of 2407 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 2408 Lesser General Public License for more details. 2409 2410 You should have received a copy of the GNU Lesser General Public 2411 License along with this library; if not, write to the Free Software 2412 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, 2413 USA. 2414 2415 Also add information on how to contact you by electronic and paper 2416mail. 2417 2418 You should also get your employer (if you work as a programmer) or 2419your school, if any, to sign a "copyright disclaimer" for the library, 2420if necessary. Here is a sample; alter the names: 2421 2422 Yoyodyne, Inc., hereby disclaims all copyright interest in the library 2423 `Frob' (a library for tweaking knobs) written by James Random Hacker. 2424 2425 SIGNATURE OF TY COON, 1 April 1990 2426 Ty Coon, President of Vice 2427 2428 That's all there is to it! 2429 2430 2431File: assuan.info, Node: Copying, Next: Index, Prev: Library Copying, Up: Top 2432 2433GNU General Public License 2434************************** 2435 2436 Version 3, 29 June 2007 2437 2438 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/> 2439 2440 Everyone is permitted to copy and distribute verbatim copies of this 2441 license document, but changing it is not allowed. 2442 2443Preamble 2444======== 2445 2446The GNU General Public License is a free, copyleft license for software 2447and other kinds of works. 2448 2449 The licenses for most software and other practical works are designed 2450to take away your freedom to share and change the works. By contrast, 2451the GNU General Public License is intended to guarantee your freedom to 2452share and change all versions of a program-to make sure it remains free 2453software for all its users. We, the Free Software Foundation, use the 2454GNU General Public License for most of our software; it applies also to 2455any other work released this way by its authors. You can apply it to 2456your programs, too. 2457 2458 When we speak of free software, we are referring to freedom, not 2459price. Our General Public Licenses are designed to make sure that you 2460have the freedom to distribute copies of free software (and charge for 2461them if you wish), that you receive source code or can get it if you 2462want it, that you can change the software or use pieces of it in new 2463free programs, and that you know you can do these things. 2464 2465 To protect your rights, we need to prevent others from denying you 2466these rights or asking you to surrender the rights. Therefore, you have 2467certain responsibilities if you distribute copies of the software, or if 2468you modify it: responsibilities to respect the freedom of others. 2469 2470 For example, if you distribute copies of such a program, whether 2471gratis or for a fee, you must pass on to the recipients the same 2472freedoms that you received. You must make sure that they, too, receive 2473or can get the source code. And you must show them these terms so they 2474know their rights. 2475 2476 Developers that use the GNU GPL protect your rights with two steps: 2477(1) assert copyright on the software, and (2) offer you this License 2478giving you legal permission to copy, distribute and/or modify it. 2479 2480 For the developers' and authors' protection, the GPL clearly explains 2481that there is no warranty for this free software. For both users' and 2482authors' sake, the GPL requires that modified versions be marked as 2483changed, so that their problems will not be attributed erroneously to 2484authors of previous versions. 2485 2486 Some devices are designed to deny users access to install or run 2487modified versions of the software inside them, although the manufacturer 2488can do so. This is fundamentally incompatible with the aim of 2489protecting users' freedom to change the software. The systematic 2490pattern of such abuse occurs in the area of products for individuals to 2491use, which is precisely where it is most unacceptable. Therefore, we 2492have designed this version of the GPL to prohibit the practice for those 2493products. If such problems arise substantially in other domains, we 2494stand ready to extend this provision to those domains in future versions 2495of the GPL, as needed to protect the freedom of users. 2496 2497 Finally, every program is threatened constantly by software patents. 2498States should not allow patents to restrict development and use of 2499software on general-purpose computers, but in those that do, we wish to 2500avoid the special danger that patents applied to a free program could 2501make it effectively proprietary. To prevent this, the GPL assures that 2502patents cannot be used to render the program non-free. 2503 2504 The precise terms and conditions for copying, distribution and 2505modification follow. 2506 2507 TERMS AND CONDITIONS 2508 2509 0. Definitions. 2510 2511 "This License" refers to version 3 of the GNU General Public 2512 License. 2513 2514 "Copyright" also means copyright-like laws that apply to other 2515 kinds of works, such as semiconductor masks. 2516 2517 "The Program" refers to any copyrightable work licensed under this 2518 License. Each licensee is addressed as "you". "Licensees" and 2519 "recipients" may be individuals or organizations. 2520 2521 To "modify" a work means to copy from or adapt all or part of the 2522 work in a fashion requiring copyright permission, other than the 2523 making of an exact copy. The resulting work is called a "modified 2524 version" of the earlier work or a work "based on" the earlier work. 2525 2526 A "covered work" means either the unmodified Program or a work 2527 based on the Program. 2528 2529 To "propagate" a work means to do anything with it that, without 2530 permission, would make you directly or secondarily liable for 2531 infringement under applicable copyright law, except executing it on 2532 a computer or modifying a private copy. Propagation includes 2533 copying, distribution (with or without modification), making 2534 available to the public, and in some countries other activities as 2535 well. 2536 2537 To "convey" a work means any kind of propagation that enables other 2538 parties to make or receive copies. Mere interaction with a user 2539 through a computer network, with no transfer of a copy, is not 2540 conveying. 2541 2542 An interactive user interface displays "Appropriate Legal Notices" 2543 to the extent that it includes a convenient and prominently visible 2544 feature that (1) displays an appropriate copyright notice, and (2) 2545 tells the user that there is no warranty for the work (except to 2546 the extent that warranties are provided), that licensees may convey 2547 the work under this License, and how to view a copy of this 2548 License. If the interface presents a list of user commands or 2549 options, such as a menu, a prominent item in the list meets this 2550 criterion. 2551 2552 1. Source Code. 2553 2554 The "source code" for a work means the preferred form of the work 2555 for making modifications to it. "Object code" means any non-source 2556 form of a work. 2557 2558 A "Standard Interface" means an interface that either is an 2559 official standard defined by a recognized standards body, or, in 2560 the case of interfaces specified for a particular programming 2561 language, one that is widely used among developers working in that 2562 language. 2563 2564 The "System Libraries" of an executable work include anything, 2565 other than the work as a whole, that (a) is included in the normal 2566 form of packaging a Major Component, but which is not part of that 2567 Major Component, and (b) serves only to enable use of the work with 2568 that Major Component, or to implement a Standard Interface for 2569 which an implementation is available to the public in source code 2570 form. A "Major Component", in this context, means a major 2571 essential component (kernel, window system, and so on) of the 2572 specific operating system (if any) on which the executable work 2573 runs, or a compiler used to produce the work, or an object code 2574 interpreter used to run it. 2575 2576 The "Corresponding Source" for a work in object code form means all 2577 the source code needed to generate, install, and (for an executable 2578 work) run the object code and to modify the work, including scripts 2579 to control those activities. However, it does not include the 2580 work's System Libraries, or general-purpose tools or generally 2581 available free programs which are used unmodified in performing 2582 those activities but which are not part of the work. For example, 2583 Corresponding Source includes interface definition files associated 2584 with source files for the work, and the source code for shared 2585 libraries and dynamically linked subprograms that the work is 2586 specifically designed to require, such as by intimate data 2587 communication or control flow between those subprograms and other 2588 parts of the work. 2589 2590 The Corresponding Source need not include anything that users can 2591 regenerate automatically from other parts of the Corresponding 2592 Source. 2593 2594 The Corresponding Source for a work in source code form is that 2595 same work. 2596 2597 2. Basic Permissions. 2598 2599 All rights granted under this License are granted for the term of 2600 copyright on the Program, and are irrevocable provided the stated 2601 conditions are met. This License explicitly affirms your unlimited 2602 permission to run the unmodified Program. The output from running 2603 a covered work is covered by this License only if the output, given 2604 its content, constitutes a covered work. This License acknowledges 2605 your rights of fair use or other equivalent, as provided by 2606 copyright law. 2607 2608 You may make, run and propagate covered works that you do not 2609 convey, without conditions so long as your license otherwise 2610 remains in force. You may convey covered works to others for the 2611 sole purpose of having them make modifications exclusively for you, 2612 or provide you with facilities for running those works, provided 2613 that you comply with the terms of this License in conveying all 2614 material for which you do not control copyright. Those thus making 2615 or running the covered works for you must do so exclusively on your 2616 behalf, under your direction and control, on terms that prohibit 2617 them from making any copies of your copyrighted material outside 2618 their relationship with you. 2619 2620 Conveying under any other circumstances is permitted solely under 2621 the conditions stated below. Sublicensing is not allowed; section 2622 10 makes it unnecessary. 2623 2624 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 2625 2626 No covered work shall be deemed part of an effective technological 2627 measure under any applicable law fulfilling obligations under 2628 article 11 of the WIPO copyright treaty adopted on 20 December 2629 1996, or similar laws prohibiting or restricting circumvention of 2630 such measures. 2631 2632 When you convey a covered work, you waive any legal power to forbid 2633 circumvention of technological measures to the extent such 2634 circumvention is effected by exercising rights under this License 2635 with respect to the covered work, and you disclaim any intention to 2636 limit operation or modification of the work as a means of 2637 enforcing, against the work's users, your or third parties' legal 2638 rights to forbid circumvention of technological measures. 2639 2640 4. Conveying Verbatim Copies. 2641 2642 You may convey verbatim copies of the Program's source code as you 2643 receive it, in any medium, provided that you conspicuously and 2644 appropriately publish on each copy an appropriate copyright notice; 2645 keep intact all notices stating that this License and any 2646 non-permissive terms added in accord with section 7 apply to the 2647 code; keep intact all notices of the absence of any warranty; and 2648 give all recipients a copy of this License along with the Program. 2649 2650 You may charge any price or no price for each copy that you convey, 2651 and you may offer support or warranty protection for a fee. 2652 2653 5. Conveying Modified Source Versions. 2654 2655 You may convey a work based on the Program, or the modifications to 2656 produce it from the Program, in the form of source code under the 2657 terms of section 4, provided that you also meet all of these 2658 conditions: 2659 2660 a. The work must carry prominent notices stating that you 2661 modified it, and giving a relevant date. 2662 2663 b. The work must carry prominent notices stating that it is 2664 released under this License and any conditions added under 2665 section 7. This requirement modifies the requirement in 2666 section 4 to "keep intact all notices". 2667 2668 c. You must license the entire work, as a whole, under this 2669 License to anyone who comes into possession of a copy. This 2670 License will therefore apply, along with any applicable 2671 section 7 additional terms, to the whole of the work, and all 2672 its parts, regardless of how they are packaged. This License 2673 gives no permission to license the work in any other way, but 2674 it does not invalidate such permission if you have separately 2675 received it. 2676 2677 d. If the work has interactive user interfaces, each must display 2678 Appropriate Legal Notices; however, if the Program has 2679 interactive interfaces that do not display Appropriate Legal 2680 Notices, your work need not make them do so. 2681 2682 A compilation of a covered work with other separate and independent 2683 works, which are not by their nature extensions of the covered 2684 work, and which are not combined with it such as to form a larger 2685 program, in or on a volume of a storage or distribution medium, is 2686 called an "aggregate" if the compilation and its resulting 2687 copyright are not used to limit the access or legal rights of the 2688 compilation's users beyond what the individual works permit. 2689 Inclusion of a covered work in an aggregate does not cause this 2690 License to apply to the other parts of the aggregate. 2691 2692 6. Conveying Non-Source Forms. 2693 2694 You may convey a covered work in object code form under the terms 2695 of sections 4 and 5, provided that you also convey the 2696 machine-readable Corresponding Source under the terms of this 2697 License, in one of these ways: 2698 2699 a. Convey the object code in, or embodied in, a physical product 2700 (including a physical distribution medium), accompanied by the 2701 Corresponding Source fixed on a durable physical medium 2702 customarily used for software interchange. 2703 2704 b. Convey the object code in, or embodied in, a physical product 2705 (including a physical distribution medium), accompanied by a 2706 written offer, valid for at least three years and valid for as 2707 long as you offer spare parts or customer support for that 2708 product model, to give anyone who possesses the object code 2709 either (1) a copy of the Corresponding Source for all the 2710 software in the product that is covered by this License, on a 2711 durable physical medium customarily used for software 2712 interchange, for a price no more than your reasonable cost of 2713 physically performing this conveying of source, or (2) access 2714 to copy the Corresponding Source from a network server at no 2715 charge. 2716 2717 c. Convey individual copies of the object code with a copy of the 2718 written offer to provide the Corresponding Source. This 2719 alternative is allowed only occasionally and noncommercially, 2720 and only if you received the object code with such an offer, 2721 in accord with subsection 6b. 2722 2723 d. Convey the object code by offering access from a designated 2724 place (gratis or for a charge), and offer equivalent access to 2725 the Corresponding Source in the same way through the same 2726 place at no further charge. You need not require recipients 2727 to copy the Corresponding Source along with the object code. 2728 If the place to copy the object code is a network server, the 2729 Corresponding Source may be on a different server (operated by 2730 you or a third party) that supports equivalent copying 2731 facilities, provided you maintain clear directions next to the 2732 object code saying where to find the Corresponding Source. 2733 Regardless of what server hosts the Corresponding Source, you 2734 remain obligated to ensure that it is available for as long as 2735 needed to satisfy these requirements. 2736 2737 e. Convey the object code using peer-to-peer transmission, 2738 provided you inform other peers where the object code and 2739 Corresponding Source of the work are being offered to the 2740 general public at no charge under subsection 6d. 2741 2742 A separable portion of the object code, whose source code is 2743 excluded from the Corresponding Source as a System Library, need 2744 not be included in conveying the object code work. 2745 2746 A "User Product" is either (1) a "consumer product", which means 2747 any tangible personal property which is normally used for personal, 2748 family, or household purposes, or (2) anything designed or sold for 2749 incorporation into a dwelling. In determining whether a product is 2750 a consumer product, doubtful cases shall be resolved in favor of 2751 coverage. For a particular product received by a particular user, 2752 "normally used" refers to a typical or common use of that class of 2753 product, regardless of the status of the particular user or of the 2754 way in which the particular user actually uses, or expects or is 2755 expected to use, the product. A product is a consumer product 2756 regardless of whether the product has substantial commercial, 2757 industrial or non-consumer uses, unless such uses represent the 2758 only significant mode of use of the product. 2759 2760 "Installation Information" for a User Product means any methods, 2761 procedures, authorization keys, or other information required to 2762 install and execute modified versions of a covered work in that 2763 User Product from a modified version of its Corresponding Source. 2764 The information must suffice to ensure that the continued 2765 functioning of the modified object code is in no case prevented or 2766 interfered with solely because modification has been made. 2767 2768 If you convey an object code work under this section in, or with, 2769 or specifically for use in, a User Product, and the conveying 2770 occurs as part of a transaction in which the right of possession 2771 and use of the User Product is transferred to the recipient in 2772 perpetuity or for a fixed term (regardless of how the transaction 2773 is characterized), the Corresponding Source conveyed under this 2774 section must be accompanied by the Installation Information. But 2775 this requirement does not apply if neither you nor any third party 2776 retains the ability to install modified object code on the User 2777 Product (for example, the work has been installed in ROM). 2778 2779 The requirement to provide Installation Information does not 2780 include a requirement to continue to provide support service, 2781 warranty, or updates for a work that has been modified or installed 2782 by the recipient, or for the User Product in which it has been 2783 modified or installed. Access to a network may be denied when the 2784 modification itself materially and adversely affects the operation 2785 of the network or violates the rules and protocols for 2786 communication across the network. 2787 2788 Corresponding Source conveyed, and Installation Information 2789 provided, in accord with this section must be in a format that is 2790 publicly documented (and with an implementation available to the 2791 public in source code form), and must require no special password 2792 or key for unpacking, reading or copying. 2793 2794 7. Additional Terms. 2795 2796 "Additional permissions" are terms that supplement the terms of 2797 this License by making exceptions from one or more of its 2798 conditions. Additional permissions that are applicable to the 2799 entire Program shall be treated as though they were included in 2800 this License, to the extent that they are valid under applicable 2801 law. If additional permissions apply only to part of the Program, 2802 that part may be used separately under those permissions, but the 2803 entire Program remains governed by this License without regard to 2804 the additional permissions. 2805 2806 When you convey a copy of a covered work, you may at your option 2807 remove any additional permissions from that copy, or from any part 2808 of it. (Additional permissions may be written to require their own 2809 removal in certain cases when you modify the work.) You may place 2810 additional permissions on material, added by you to a covered work, 2811 for which you have or can give appropriate copyright permission. 2812 2813 Notwithstanding any other provision of this License, for material 2814 you add to a covered work, you may (if authorized by the copyright 2815 holders of that material) supplement the terms of this License with 2816 terms: 2817 2818 a. Disclaiming warranty or limiting liability differently from 2819 the terms of sections 15 and 16 of this License; or 2820 2821 b. Requiring preservation of specified reasonable legal notices 2822 or author attributions in that material or in the Appropriate 2823 Legal Notices displayed by works containing it; or 2824 2825 c. Prohibiting misrepresentation of the origin of that material, 2826 or requiring that modified versions of such material be marked 2827 in reasonable ways as different from the original version; or 2828 2829 d. Limiting the use for publicity purposes of names of licensors 2830 or authors of the material; or 2831 2832 e. Declining to grant rights under trademark law for use of some 2833 trade names, trademarks, or service marks; or 2834 2835 f. Requiring indemnification of licensors and authors of that 2836 material by anyone who conveys the material (or modified 2837 versions of it) with contractual assumptions of liability to 2838 the recipient, for any liability that these contractual 2839 assumptions directly impose on those licensors and authors. 2840 2841 All other non-permissive additional terms are considered "further 2842 restrictions" within the meaning of section 10. If the Program as 2843 you received it, or any part of it, contains a notice stating that 2844 it is governed by this License along with a term that is a further 2845 restriction, you may remove that term. If a license document 2846 contains a further restriction but permits relicensing or conveying 2847 under this License, you may add to a covered work material governed 2848 by the terms of that license document, provided that the further 2849 restriction does not survive such relicensing or conveying. 2850 2851 If you add terms to a covered work in accord with this section, you 2852 must place, in the relevant source files, a statement of the 2853 additional terms that apply to those files, or a notice indicating 2854 where to find the applicable terms. 2855 2856 Additional terms, permissive or non-permissive, may be stated in 2857 the form of a separately written license, or stated as exceptions; 2858 the above requirements apply either way. 2859 2860 8. Termination. 2861 2862 You may not propagate or modify a covered work except as expressly 2863 provided under this License. Any attempt otherwise to propagate or 2864 modify it is void, and will automatically terminate your rights 2865 under this License (including any patent licenses granted under the 2866 third paragraph of section 11). 2867 2868 However, if you cease all violation of this License, then your 2869 license from a particular copyright holder is reinstated (a) 2870 provisionally, unless and until the copyright holder explicitly and 2871 finally terminates your license, and (b) permanently, if the 2872 copyright holder fails to notify you of the violation by some 2873 reasonable means prior to 60 days after the cessation. 2874 2875 Moreover, your license from a particular copyright holder is 2876 reinstated permanently if the copyright holder notifies you of the 2877 violation by some reasonable means, this is the first time you have 2878 received notice of violation of this License (for any work) from 2879 that copyright holder, and you cure the violation prior to 30 days 2880 after your receipt of the notice. 2881 2882 Termination of your rights under this section does not terminate 2883 the licenses of parties who have received copies or rights from you 2884 under this License. If your rights have been terminated and not 2885 permanently reinstated, you do not qualify to receive new licenses 2886 for the same material under section 10. 2887 2888 9. Acceptance Not Required for Having Copies. 2889 2890 You are not required to accept this License in order to receive or 2891 run a copy of the Program. Ancillary propagation of a covered work 2892 occurring solely as a consequence of using peer-to-peer 2893 transmission to receive a copy likewise does not require 2894 acceptance. However, nothing other than this License grants you 2895 permission to propagate or modify any covered work. These actions 2896 infringe copyright if you do not accept this License. Therefore, 2897 by modifying or propagating a covered work, you indicate your 2898 acceptance of this License to do so. 2899 2900 10. Automatic Licensing of Downstream Recipients. 2901 2902 Each time you convey a covered work, the recipient automatically 2903 receives a license from the original licensors, to run, modify and 2904 propagate that work, subject to this License. You are not 2905 responsible for enforcing compliance by third parties with this 2906 License. 2907 2908 An "entity transaction" is a transaction transferring control of an 2909 organization, or substantially all assets of one, or subdividing an 2910 organization, or merging organizations. If propagation of a 2911 covered work results from an entity transaction, each party to that 2912 transaction who receives a copy of the work also receives whatever 2913 licenses to the work the party's predecessor in interest had or 2914 could give under the previous paragraph, plus a right to possession 2915 of the Corresponding Source of the work from the predecessor in 2916 interest, if the predecessor has it or can get it with reasonable 2917 efforts. 2918 2919 You may not impose any further restrictions on the exercise of the 2920 rights granted or affirmed under this License. For example, you 2921 may not impose a license fee, royalty, or other charge for exercise 2922 of rights granted under this License, and you may not initiate 2923 litigation (including a cross-claim or counterclaim in a lawsuit) 2924 alleging that any patent claim is infringed by making, using, 2925 selling, offering for sale, or importing the Program or any portion 2926 of it. 2927 2928 11. Patents. 2929 2930 A "contributor" is a copyright holder who authorizes use under this 2931 License of the Program or a work on which the Program is based. 2932 The work thus licensed is called the contributor's "contributor 2933 version". 2934 2935 A contributor's "essential patent claims" are all patent claims 2936 owned or controlled by the contributor, whether already acquired or 2937 hereafter acquired, that would be infringed by some manner, 2938 permitted by this License, of making, using, or selling its 2939 contributor version, but do not include claims that would be 2940 infringed only as a consequence of further modification of the 2941 contributor version. For purposes of this definition, "control" 2942 includes the right to grant patent sublicenses in a manner 2943 consistent with the requirements of this License. 2944 2945 Each contributor grants you a non-exclusive, worldwide, 2946 royalty-free patent license under the contributor's essential 2947 patent claims, to make, use, sell, offer for sale, import and 2948 otherwise run, modify and propagate the contents of its contributor 2949 version. 2950 2951 In the following three paragraphs, a "patent license" is any 2952 express agreement or commitment, however denominated, not to 2953 enforce a patent (such as an express permission to practice a 2954 patent or covenant not to sue for patent infringement). To "grant" 2955 such a patent license to a party means to make such an agreement or 2956 commitment not to enforce a patent against the party. 2957 2958 If you convey a covered work, knowingly relying on a patent 2959 license, and the Corresponding Source of the work is not available 2960 for anyone to copy, free of charge and under the terms of this 2961 License, through a publicly available network server or other 2962 readily accessible means, then you must either (1) cause the 2963 Corresponding Source to be so available, or (2) arrange to deprive 2964 yourself of the benefit of the patent license for this particular 2965 work, or (3) arrange, in a manner consistent with the requirements 2966 of this License, to extend the patent license to downstream 2967 recipients. "Knowingly relying" means you have actual knowledge 2968 that, but for the patent license, your conveying the covered work 2969 in a country, or your recipient's use of the covered work in a 2970 country, would infringe one or more identifiable patents in that 2971 country that you have reason to believe are valid. 2972 2973 If, pursuant to or in connection with a single transaction or 2974 arrangement, you convey, or propagate by procuring conveyance of, a 2975 covered work, and grant a patent license to some of the parties 2976 receiving the covered work authorizing them to use, propagate, 2977 modify or convey a specific copy of the covered work, then the 2978 patent license you grant is automatically extended to all 2979 recipients of the covered work and works based on it. 2980 2981 A patent license is "discriminatory" if it does not include within 2982 the scope of its coverage, prohibits the exercise of, or is 2983 conditioned on the non-exercise of one or more of the rights that 2984 are specifically granted under this License. You may not convey a 2985 covered work if you are a party to an arrangement with a third 2986 party that is in the business of distributing software, under which 2987 you make payment to the third party based on the extent of your 2988 activity of conveying the work, and under which the third party 2989 grants, to any of the parties who would receive the covered work 2990 from you, a discriminatory patent license (a) in connection with 2991 copies of the covered work conveyed by you (or copies made from 2992 those copies), or (b) primarily for and in connection with specific 2993 products or compilations that contain the covered work, unless you 2994 entered into that arrangement, or that patent license was granted, 2995 prior to 28 March 2007. 2996 2997 Nothing in this License shall be construed as excluding or limiting 2998 any implied license or other defenses to infringement that may 2999 otherwise be available to you under applicable patent law. 3000 3001 12. No Surrender of Others' Freedom. 3002 3003 If conditions are imposed on you (whether by court order, agreement 3004 or otherwise) that contradict the conditions of this License, they 3005 do not excuse you from the conditions of this License. If you 3006 cannot convey a covered work so as to satisfy simultaneously your 3007 obligations under this License and any other pertinent obligations, 3008 then as a consequence you may not convey it at all. For example, 3009 if you agree to terms that obligate you to collect a royalty for 3010 further conveying from those to whom you convey the Program, the 3011 only way you could satisfy both those terms and this License would 3012 be to refrain entirely from conveying the Program. 3013 3014 13. Use with the GNU Affero General Public License. 3015 3016 Notwithstanding any other provision of this License, you have 3017 permission to link or combine any covered work with a work licensed 3018 under version 3 of the GNU Affero General Public License into a 3019 single combined work, and to convey the resulting work. The terms 3020 of this License will continue to apply to the part which is the 3021 covered work, but the special requirements of the GNU Affero 3022 General Public License, section 13, concerning interaction through 3023 a network will apply to the combination as such. 3024 3025 14. Revised Versions of this License. 3026 3027 The Free Software Foundation may publish revised and/or new 3028 versions of the GNU General Public License from time to time. Such 3029 new versions will be similar in spirit to the present version, but 3030 may differ in detail to address new problems or concerns. 3031 3032 Each version is given a distinguishing version number. If the 3033 Program specifies that a certain numbered version of the GNU 3034 General Public License "or any later version" applies to it, you 3035 have the option of following the terms and conditions either of 3036 that numbered version or of any later version published by the Free 3037 Software Foundation. If the Program does not specify a version 3038 number of the GNU General Public License, you may choose any 3039 version ever published by the Free Software Foundation. 3040 3041 If the Program specifies that a proxy can decide which future 3042 versions of the GNU General Public License can be used, that 3043 proxy's public statement of acceptance of a version permanently 3044 authorizes you to choose that version for the Program. 3045 3046 Later license versions may give you additional or different 3047 permissions. However, no additional obligations are imposed on any 3048 author or copyright holder as a result of your choosing to follow a 3049 later version. 3050 3051 15. Disclaimer of Warranty. 3052 3053 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 3054 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE 3055 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" 3056 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, 3057 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 3058 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE 3059 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. 3060 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 3061 NECESSARY SERVICING, REPAIR OR CORRECTION. 3062 3063 16. Limitation of Liability. 3064 3065 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 3066 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES 3067 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR 3068 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR 3069 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE 3070 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA 3071 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 3072 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER 3073 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF 3074 THE POSSIBILITY OF SUCH DAMAGES. 3075 3076 17. Interpretation of Sections 15 and 16. 3077 3078 If the disclaimer of warranty and limitation of liability provided 3079 above cannot be given local legal effect according to their terms, 3080 reviewing courts shall apply local law that most closely 3081 approximates an absolute waiver of all civil liability in 3082 connection with the Program, unless a warranty or assumption of 3083 liability accompanies a copy of the Program in return for a fee. 3084 3085 END OF TERMS AND CONDITIONS 3086 3087How to Apply These Terms to Your New Programs 3088============================================= 3089 3090If you develop a new program, and you want it to be of the greatest 3091possible use to the public, the best way to achieve this is to make it 3092free software which everyone can redistribute and change under these 3093terms. 3094 3095 To do so, attach the following notices to the program. It is safest 3096to attach them to the start of each source file to most effectively 3097state the exclusion of warranty; and each file should have at least the 3098"copyright" line and a pointer to where the full notice is found. 3099 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. 3100 Copyright (C) YEAR NAME OF AUTHOR 3101 3102 This program is free software: you can redistribute it and/or modify 3103 it under the terms of the GNU General Public License as published by 3104 the Free Software Foundation, either version 3 of the License, or (at 3105 your option) any later version. 3106 3107 This program is distributed in the hope that it will be useful, but 3108 WITHOUT ANY WARRANTY; without even the implied warranty of 3109 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 3110 General Public License for more details. 3111 3112 You should have received a copy of the GNU General Public License 3113 along with this program. If not, see <http://www.gnu.org/licenses/>. 3114 3115 Also add information on how to contact you by electronic and paper 3116mail. 3117 3118 If the program does terminal interaction, make it output a short 3119notice like this when it starts in an interactive mode: 3120 3121 PROGRAM Copyright (C) YEAR NAME OF AUTHOR 3122 This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. 3123 This is free software, and you are welcome to redistribute it under certain conditions; type 'show c' for details. 3124 3125 The hypothetical commands 'show w' and 'show c' should show the 3126appropriate parts of the General Public License. Of course, your 3127program's commands might be different; for a GUI interface, you would 3128use an "about box". 3129 3130 You should also get your employer (if you work as a programmer) or 3131school, if any, to sign a "copyright disclaimer" for the program, if 3132necessary. For more information on this, and how to apply and follow 3133the GNU GPL, see <http://www.gnu.org/licenses/>. 3134 3135 The GNU General Public License does not permit incorporating your 3136program into proprietary programs. If your program is a subroutine 3137library, you may consider it more useful to permit linking proprietary 3138applications with the library. If this is what you want to do, use the 3139GNU Lesser General Public License instead of this License. But first, 3140please read <http://www.gnu.org/philosophy/why-not-lgpl.html>. 3141 3142 3143File: assuan.info, Node: Index, Prev: Copying, Up: Top 3144 3145Index 3146***** 3147 3148�[index�] 3149* Menu: 3150 3151* AM_PATH_LIBASSUAN: Automake. (line 11) 3152* assuan_accept: Server code. (line 267) 3153* assuan_begin_confidential: Contexts. (line 110) 3154* assuan_close_input_fd: Utilities. (line 93) 3155* assuan_close_output_fd: Utilities. (line 100) 3156* assuan_command_parse_fd: Utilities. (line 57) 3157* assuan_context_t: Data Types. (line 9) 3158* assuan_ctx_set_system_hooks: Contexts. (line 222) 3159* assuan_end_confidential: Contexts. (line 117) 3160* assuan_fdopen: Data Types. (line 21) 3161* assuan_fd_t: Data Types. (line 16) 3162* assuan_flag_t: Contexts. (line 81) 3163* assuan_get_active_fds: Utilities. (line 154) 3164* assuan_get_assuan_log_prefix: Default Log Handler. (line 12) 3165* assuan_get_assuan_log_stream: Default Log Handler. (line 26) 3166* assuan_get_command_name: Utilities. (line 73) 3167* assuan_get_data_fp: Utilities. (line 36) 3168* assuan_get_flag: Contexts. (line 105) 3169* assuan_get_gpg_err_source: Initializing the library. 3170 (line 72) 3171* assuan_get_input_fd: Utilities. (line 81) 3172* assuan_get_log_cb: Initializing the library. 3173 (line 112) 3174* assuan_get_malloc_hooks: Initializing the library. 3175 (line 54) 3176* assuan_get_output_fd: Utilities. (line 87) 3177* assuan_get_peercred: Utilities. (line 141) 3178* assuan_get_pid: Utilities. (line 118) 3179* assuan_get_pointer: Contexts. (line 61) 3180* assuan_init_pipe_server: Server code. (line 74) 3181* assuan_init_socket_server: Server code. (line 90) 3182* assuan_inquire: Utilities. (line 17) 3183* assuan_inquire_ext: External I/O Loop Server. 3184 (line 80) 3185* assuan_malloc_hooks_t: Initializing the library. 3186 (line 41) 3187* assuan_new: Contexts. (line 13) 3188* assuan_new_ext: Contexts. (line 33) 3189* assuan_peercred_t: Utilities. (line 128) 3190* assuan_pending_line: Utilities. (line 174) 3191* assuan_pipe_connect: Client code. (line 12) 3192* assuan_process: Server code. (line 277) 3193* assuan_process_done: External I/O Loop Server. 3194 (line 75) 3195* assuan_process_next: External I/O Loop Server. 3196 (line 69) 3197* assuan_read_line: Reading and Writing. (line 12) 3198* assuan_receivefd: Client code. (line 127) 3199* assuan_register_bye_notify: Server code. (line 170) 3200* assuan_register_cancel_notify: Server code. (line 183) 3201* assuan_register_command: Server code. (line 142) 3202* assuan_register_input_notify: Server code. (line 202) 3203* assuan_register_option_handler: Server code. (line 189) 3204* assuan_register_output_notify: Server code. (line 215) 3205* assuan_register_post_cmd_notify: Server code. (line 161) 3206* assuan_register_reset_notify: Server code. (line 177) 3207* assuan_release: Contexts. (line 45) 3208* assuan_sendfd: Client code. (line 114) 3209* assuan_send_data: Reading and Writing. (line 35) 3210* assuan_set_assuan_log_prefix: Default Log Handler. (line 8) 3211* assuan_set_assuan_log_stream: Default Log Handler. (line 17) 3212* assuan_set_error: Utilities. (line 107) 3213* assuan_set_flag: Contexts. (line 74) 3214* assuan_set_gpg_err_source: Initializing the library. 3215 (line 63) 3216* assuan_set_hello_line: Server code. (line 228) 3217* assuan_set_io_monitor: Reading and Writing. (line 72) 3218* assuan_set_log_cb: Initializing the library. 3219 (line 106) 3220* assuan_set_log_stream: Default Log Handler. (line 33) 3221* assuan_set_malloc_hooks: Initializing the library. 3222 (line 44) 3223* assuan_set_okay_line: Utilities. (line 49) 3224* assuan_set_pointer: Contexts. (line 53) 3225* assuan_set_sock_nonce: Server code. (line 112) 3226* assuan_set_system_hooks: Contexts. (line 207) 3227* assuan_socket_connect: Client code. (line 55) 3228* assuan_sock_bind: Socket wrappers. (line 56) 3229* assuan_sock_check_nonce: Socket wrappers. (line 95) 3230* assuan_sock_close: Socket wrappers. (line 20) 3231* assuan_sock_connect: Socket wrappers. (line 28) 3232* assuan_sock_connect_byname: Socket wrappers. (line 39) 3233* assuan_sock_deinit: Socket wrappers. (line 17) 3234* assuan_sock_get_flag: Socket wrappers. (line 122) 3235* assuan_sock_get_nonce: Socket wrappers. (line 88) 3236* assuan_sock_init: Socket wrappers. (line 13) 3237* assuan_sock_new: Socket wrappers. (line 23) 3238* assuan_sock_set_flag: Socket wrappers. (line 114) 3239* assuan_sock_set_sockaddr_un: Socket wrappers. (line 62) 3240* assuan_sock_set_system_hooks: Contexts. (line 213) 3241* assuan_transact: Client code. (line 72) 3242* assuan_write_line: Reading and Writing. (line 23) 3243* assuan_write_status: Utilities. (line 10) 3244* gpg_error_t (*assuan_handler_t) (assuan_context_t CTX, char *LINE): Server code. 3245 (line 136) 3246* int (*assuan_log_cb_t) (assuan_context_t CTX, void *HOOK_VALUE, unsigned int CAT, const char *MSG): Initializing the library. 3247 (line 79) 3248* introduction: Top. (line 6) 3249* LGPL, GNU Lesser General Public License: Library Copying. (line 6) 3250* struct assuan_malloc_hooks: Initializing the library. 3251 (line 24) 3252* struct assuan_system_hooks: Contexts. (line 124) 3253* unsigned int (*assuan_io_monitor_t) (assuan_context_t CTX, void *HOOK_VALUE, int INOUT, const char *LINE, size_t LINELEN): Reading and Writing. 3254 (line 54) 3255 3256 3257 3258Tag Table: 3259Node: Top907 3260Node: Introduction1973 3261Node: Assuan4228 3262Node: Implementation5272 3263Node: Server responses6451 3264Node: Client requests8741 3265Node: Error codes11779 3266Node: Preparation12118 3267Node: Header12693 3268Node: Building sources13479 3269Node: Automake15378 3270Node: Multi Threading16526 3271Node: Generalities17485 3272Node: Data Types17889 3273Node: Initializing the library18997 3274Ref: function assuan_set_gpg_err_source21693 3275Node: Default Log Handler24012 3276Node: Contexts25778 3277Ref: function assuan_new26358 3278Node: Reading and Writing36930 3279Node: Client code40405 3280Ref: function assuan_sendfd45402 3281Ref: function assuan_receivefd45993 3282Node: Server code46368 3283Node: External I/O Loop58493 3284Node: External I/O Loop Client60318 3285Node: External I/O Loop Server63403 3286Node: Utilities67987 3287Ref: Utilities-Footnote-176088 3288Node: Socket wrappers76152 3289Node: Library Copying83133 3290Node: Copying111245 3291Node: Index148759 3292 3293End Tag Table 3294