diff options
author | Anas Nashif <anas.nashif@intel.com> | 2013-02-19 08:22:18 -0800 |
---|---|---|
committer | Anas Nashif <anas.nashif@intel.com> | 2013-02-19 08:22:18 -0800 |
commit | 26fb537f9cf011eaeaf975adcad5e8e9154d04fd (patch) | |
tree | ddc2171273fca8b730b9c496e1b5ed3b01878577 /doc | |
download | gpgme-26fb537f9cf011eaeaf975adcad5e8e9154d04fd.tar.gz gpgme-26fb537f9cf011eaeaf975adcad5e8e9154d04fd.tar.bz2 gpgme-26fb537f9cf011eaeaf975adcad5e8e9154d04fd.zip |
Imported Upstream version 1.3.2upstream/1.3.2
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ChangeLog-2011 | 888 | ||||
-rw-r--r-- | doc/HACKING | 28 | ||||
-rw-r--r-- | doc/Makefile.am | 36 | ||||
-rw-r--r-- | doc/Makefile.in | 722 | ||||
-rw-r--r-- | doc/gpgme.info | 156 | ||||
-rw-r--r-- | doc/gpgme.info-1 | 6615 | ||||
-rw-r--r-- | doc/gpgme.info-2 | 1309 | ||||
-rw-r--r-- | doc/gpgme.texi | 5787 | ||||
-rw-r--r-- | doc/gpl.texi | 724 | ||||
-rw-r--r-- | doc/lesser.texi | 565 | ||||
-rwxr-xr-x | doc/mdate-sh | 205 | ||||
-rw-r--r-- | doc/module-overview.sk | 640 | ||||
-rw-r--r-- | doc/stamp-vti | 4 | ||||
-rw-r--r-- | doc/texinfo.tex | 8962 | ||||
-rw-r--r-- | doc/uiserver.texi | 612 | ||||
-rw-r--r-- | doc/version.texi | 4 |
16 files changed, 27257 insertions, 0 deletions
diff --git a/doc/ChangeLog-2011 b/doc/ChangeLog-2011 new file mode 100644 index 0000000..d6ecca7 --- /dev/null +++ b/doc/ChangeLog-2011 @@ -0,0 +1,888 @@ +2011-12-02 Werner Koch <wk@g10code.com> + + NB: ChangeLog files are no longer manually maintained. Starting + on December 1st, 2011 we put change information only in the GIT + commit log, and generate a top-level ChangeLog file from logs at + "make dist". See doc/HACKING for details. + +2011-05-12 Marcus Brinkmann <marcus@g10code.com> + + * gpgme.texi (I/O Callback Example): Fix example code. + + * gpgme.texi (Generating Keys): Fix OpenPGP parameters and reference + GPG and GPGSM manual. + +2010-01-05 Werner Koch <wk@g10code.com> + + * gpgme.texi (Changing Passphrases): New. + +2009-07-21 Werner Koch <wk@g10code.com> + + * uiserver.texi (UI Server Encrypt): Add --expect-sign option to + PREP_ENCRYPT. + +2009-06-16 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Result Management): New section. + +2009-06-16 Werner Koch <wk@g10code.com> + + * gpgme.texi (Exporting Keys): Document gpgme_op_export_keys. + (Importing Keys): Document gpgme_op_import_keys. + (Data Buffer Meta-Data): Document URL encodings. + +2009-05-28 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Library Version Check): Document selftest error. + (Creating Contexts): Likewise. + +2009-05-18 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Encrypting a Plaintext): Document + GPGME_ENCRYPT_NO_ENCRYPT_TO. + +2009-05-05 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Engine Information): Replace path by file_name. + +2008-11-28 Werner Koch <wk@g10code.com> + + * gpgme.texi (Listing Keys): Change description of the return + value to match the code. Spotted by Colin Leroy. + +2008-10-15 Werner Koch <wk@g10code.com> + + * uiserver.texi (Miscellaneous UI Server Commands): Add option + --protocol to the SENDER command. + +2008-07-17 Werner Koch <wk@g10code.com> + + * module-overview.sk: New. + +2008-07-04 Werner Koch <wk@g10code.com> + + * gpgme.texi (Algorithms): Add a hint on symmetric only encryption. + +2008-06-27 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Cancellation): Document gpgme_cancel_async. + +2008-06-25 Werner Koch <wk@g10code.com> + + * gpgme.texi (Listing Keys): Updated example to the current API. + Noted by Nico Schottelius. + +2008-06-05 Werner Koch <wk@g10code.com> + + * uiserver.texi (Miscellaneous UI Server Commands): Describe + START_CONFDIALOG. + +2008-06-04 Werner Koch <wk@g10code.com> + + * gpgme.texi: Use @copying command. Change license to + GPLv3. Include protocol specis from GpgOL and GPGEx. Minor + cleanups. + +2008-03-11 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (File Based Data Buffers): Document the need for + blocking operations. + (Callback Based Data Buffers): Likewise. + +2008-03-05 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Library Version Check): Rename snippet function to + init_gpgme. + (I/O Callback Example): Call it here. + +2008-01-28 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi: Document that data encoding affects some output data + objects now. + +2007-09-27 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Protocols and Engines): Document GPGME_PROTOCOL_UNKNOWN. + +2007-09-11 Werner Koch <wk@g10code.com> + + * gpgme.texi (I/O Callback Example): Typo fix. + +2007-08-07 Werner Koch <wk@g10code.com> + + * gpgme.texi (Verify): Describe chain_model. + +2007-07-12 Werner Koch <wk@g10code.com> + + * gpgme.texi (Library Version Check): Add remark that the socket + layer will get initialized. + +2007-06-05 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Advanced Key Editing): New section. + +2007-05-21 Werner Koch <wk@g10code.com> + + * Makefile.am (online): New target. + +2007-05-18 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Error Strings): Fix documentation of + gpgme_strerror_r. + +2006-11-01 Moritz Schulte <moritz@g10code.com> + + * gpgme.texi (Data Buffer I/O Operations): Fixed entry for + gpgme_data_seek: OFFSET is not a pointer; some s/whence/offset/. + +2006-09-25 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Destroying Data Buffers): Clarify that + gpgme_data_release_and_get_mem destroys DH unconditionally. + +2005-03-24 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Library Version Check): Make example code compatible + to W32 systems. + +2006-06-21 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Passphrase Callback): Fix inverted condition in + description. + +2005-12-20 Werner Koch <wk@g10code.com> + + * gpgme.texi (Verify): Document pka_trust. + +2005-12-06 Werner Koch <wk@g10code.com> + + * gpgme.texi (Key Management): Updated to match the fixes for + subkey fingerprints and theg secret flag. + +2005-10-06 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Destroying Data Buffers): Document gpgme_free. + +2005-10-02 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Key Management): Add the new member notations of + gpgme_sig_key_t. + (Key Listing Mode): Document GPGME_KEYLIST_MODE_SIG_NOTATIONS. + +2005-10-01 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi: Enclose all return parameters of deftypefuns in + curly brackets. + + * gpgme.texi (Signature Notation Data): New section. + (Verify): Added more about the notation data structure. + +2005-09-30 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Data Buffer I/O Operations, Data Buffer Meta-Data): + New subsections. + + * gpgme.texi: Replace plaintext_filename with file_name. + + * gpgme.texi (Key Management): Document is_qualified. + +2005-07-27 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Decrypt): Add plaintext_filename to + gpgme_decrypt_result_t. + (Verify): Likewise for gpgme_verify_result_t. + +2005-06-03 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Verify): Add information about new fields in + gpgme_signature_t. + + * gpgme.texi (Decrypt): Add gpgme_recipient_t. + +2005-05-28 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Key Listing Mode): Fix return type of + gpgme_set_keylist_mode. + Reported by "Sergio" <ml_sergico@virgilio.it>. + +2005-04-28 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Included Certificates): Document + GPGME_INCLUDE_CERTS_DEFAULT. + +2005-01-12 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Engine Configuration): New section. + (Crypto Engine): New subsection. + +2004-12-07 Marcus Brinkmann <marcus@g10code.de> + + * lesser.texi (Library Copying): Change from @appendixsec to + @appendix. + * gpgme.texi (Features): Change reference to GPL to one to LGPL. + + * Makefile.am: Change license to LGPL. + (gpgme_TEXINFOS): Replace gpl.texi with lesser.texi. + + * gpgme.texi: Change license to LGPL (also for documentation of + GPGME's license). + * lesser.texi: New file. + * gpl.texi: File removed. + + * gpgme.texi (Creating Contexts): Fix cut&paste error. Reported + by Noel Torres <envite@rolamasao.org>. + +2004-09-30 Marcus Brinkmann <marcus@g10code.de> + + * Makefile.am (gpgme_TEXINFOS): Remove fdl.texi. + * gpgme.texi: Do not include fdl.texi. Change license to GPL. + * fdl.texi: File removed. + +2004-09-29 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Key Management): Change type of keylist_mode in + gpgme_key_t to gpgme_keylist_mode_t. + +2004-09-28 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Passphrase Callback): Fix last change. + +2004-09-27 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Passphrase Callback): Document + GPG_ERR_NOT_IMPLEMENTED. + + * gpgme.texi: Update copyright year for tex version. + +2004-07-29 Moritz Schulte <moritz@g10code.com> + + * gpgme.texi (Verify): Fix gpgme_get_key example (ancient + force_update argument was still there). + +2004-06-08 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Listing Keys): Elaborate on the length restrictions + on search patterns. + + * gpgme.texi (Decrypt and Verify): Document the NO_DATA error + code. + (Verify): Document the relationship between gpgme_op_verify_result + and the decrypt and verify operations. + +2004-05-21 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.text (Verify): Document GPG_ERR_CERT_REVOKED status. + + * gpgme.texi (Decrypt): Add note about new field wrong_key_usage + of gpgme_decrypt_result_t. + + * gpgme.texi (Key Management): Add note about new field + keylist_mode of gpgme_key_t. + +2004-04-29 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Verify): Correct type of member wrong_key_usage. + +2004-03-29 Moritz Schulte <moritz@duesseldorf.ccc.de> + + * gpgme.texi (Verify): Fix type of gpgme_op_verify_result. + * gpgme.texi (Key Listing Mode): Typo fix. + +2004-03-23 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Library Version Check): Fix the instruction when to + set the locale. + +2004-03-03 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (I/O Callback Example Qt): New section by Marc Mutz. + +2004-02-24 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (cancellation): New section. + +2004-02-17 Werner Koch <wk@gnupg.org> + + * gpgme.texi (Key Listing Mode): Doc KEYLIST_MODE_VALIDATE. + +2004-02-06 Moritz Schulte <mo@g10code.com> + + * gpgme.texi: A couple of small fixes regarding the Largfile + Support section. + +2004-02-01 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Largefile Support): New section. + +2004-01-13 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Key Management): Fix exportable field. + +2003-12-25 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Key Management): Rename member class in + gpgme_key_sig_t to sig_class. + (Creating a Signature): Likewise for gpgme_signature_t. + +2003-12-23 Moritz Schulte <mo@g10code.com> + + * gpgme.texi (Listing Keys): Minor clarification for + gpgme_get_key. + +2003-10-06 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Signal Handling): New section. + +2003-09-14 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Multi Threading): Correct documentation on memory + synchronization requirement. + + * gpgme.texi (Locale): New section. + (Multi Threading): Set locale in example. + +2003-09-13 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Error Strings): Add gpgme_strerror_r. + +2003-09-13 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Multi Threading): Update documentation. + +2003-09-03 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Header): We don't use the assuan namespace anymore. + Document new thread options. + +2003-08-14 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Creating a Signature): Change type of member class + to unsigned int. + +2003-08-04 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Verify): Get error code from SIG->status in the code + for gpgme_get_sig_status. + +2003-07-31 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Key Management): Add can_authenticate flag. + + * gpgme.texi (Listing Keys): Document GPG_ERR_AMBIGUOUS_NAME for + gpgme_get_key. + +2003-07-29 Marcus Brinkmann <marcus@g10code.de> + + * Makefile.am (EXTRA_DIST): Remove variable. + + * gpgme.texi (Encrypting a Plaintext): Bad passphrase is only + possible with symmetric encryption, change the wording to reflect + that. + + * gpgme.texi (Creating a Signature): Document + GPG_ERR_UNUSABLE_SECKEY. + + * gpgme.texi (Encrypting a Plaintext): Mention encrypt and sign + operations in result function. + (Creating a Signature): Likewise. + +2003-07-23 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Key Listing Mode): Remove word duplication. + (Listing Keys): Remove mentioning of force argument. + (Verify): Don't mention r_stat. Fix some typos. + (Decrypt and Verify): Correct info how to get the result. Don't + mention r_stat. + (Manipulating Data Buffers): Fix documentation of return value. + (Listing Keys): Update examples. + (Decrypt): Result might also be available when operation failed. + (Verify): Result might also be available when operation failed. + All spotted by Stéphane Corthésy. + +2003-07-22 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Error Sources): Fix cut and paste error. + +2003-07-09 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Key Management): Clarify difference between can_sign + and can_certify. + (Information About Keys): Likewise for GPGME_ATTR_CAN_SIGN and + GPGME_ATTR_CAN_CERTIFY. + +2003-07-08 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Progress Meter Callback): Change return type of + gpgme_progress_cb_t to void. + +2003-06-22 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi: Add 2003 to copyright notice. + + * gpgme.texi (Header): Fix name space documentation on + libgpg-error. + +2003-06-22 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Multi Threading): Remove reference to + gpgme_recipients_t. + +2003-06-06 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Crypto Operations): Rename gpgme_invalid_user_id_t + to gpgme_invalid_key_t. + +2003-06-06 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi: Change error codes to GPG_ERR_* variants. + (Error Handling): Rewritten. + +2003-05-29 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Exporting Keys): Change and document prototypes. + Add new gpgme_op_export_ext and gpgme_op_export_ext_start + variants. + (Selecting Recipients): Section removed. + (Encrypting a Plaintext): Change prototypes and document the + changes. + +2003-05-28 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Exporting Keys): Change argument type from + gpgme_recipient_t to gpgme_user_id_t. + (Encrypting a Plaintext): Likewise. + (Selecting Recipients): Rewritten. + +2003-05-27 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Protocol Selection): Do not use @acronym in @node + because that breaks texi2dvi. + + * gpgme.texi (Passphrase Callback): Document new prototype. + +2003-05-18 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Header): Remove Gpgme as namespace prefix. Add + _GPGME to namespace prefix. + * gpgme.texi (Multi Threading): Add note about link order. + +2003-05-04 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Listing Keys): Document what happens if key is not + found. + + * gpgme.texi (Importing Keys): Fix cut and paste error. + +2003-04-30 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Encrypting a Plaintext): Remove reference to + gpgme_get_op_info. + (Detailed Results): Subsection removed. + + * gpgme.texi (Key Listing Mode): Add GPGME_KEYLIST_MODE_SIGS. + (Manipulating Keys): Add obsoleteness note. + (Key Signatures): Likewise. + (Information About Keys): Likewise. + (Key Management): Add new data types GpgmeSubkey, GpgmeKeySig, + GpgmeUserID, and all the information about GpgmeKey. + +2003-04-29 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Listing Keys): Remove force_update argument from + gpgme_get_key. + + * gpgme.texi (Trust Item Management): Add data members of + GpgmeTrustItem type. + (Information About Trust Items): Add note about obsoleteness. + (Manipulating Trust Items): Add gpgme_trust_item_ref and + gpgme_trust_item_unref. + +2003-04-28 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Verify): Rewritten to take into account new and + deprecated functions and data types. + + * gpgme.texi (Decrypt): Descript gpgme_op_decrypt_result and + GpgmeDecryptResult. + +2003-04-27 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Encrypting a Plaintext): Add info about + GpgmeEncryptResult and gpgme_op_encrypt_result. + + * gpgme.texi (Creating a Signature): Add info about + GpgmeNewSignature, GpgmeSignResult and gpgme_op_sign_result. + (Crypto Operations): Add GpgmeInvalidUserID. + (Algorithms): New chapter. + + * gpgme.texi (Deleting Keys): Document + GPGME_Ambiguous_Specification. + (Error Values): Remove GPGME_Invalid_Type and GPGME_Invalid_Mode. + Add GPGME_Unknown_Reason, GPGME_Not_Found, + GPGME_Ambiguous_Specification, GPGME_Wrong_Key_Usage, + GPGME_Key_Revoked, GPGME_Key_Expired, GPGME_No_CRL_Known, + GPGME_CRL_Too_Old, GPGME_Policy_Mismatch, GPGME_No_Secret_Key, + GPGME_Key_Not_Trusted, GPGME_Issuer_Missing, GPGME_Chain_Too_Long, + GPGME_Unsupported_Algorithm, GPGME_Sig_Expired, + GPGME_Bad_Signature, GPGME_No_Public_Key. + +2003-04-25 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Importing Keys): Change GPGME_IMPORT_PRIVATE to + GPGME_IMPORT_SECRET. + + * gpgme.texi (Importing Keys): Remove note about gpgme_get_op_info. + (Detailed Results): Remove note about import. + + * gpgme.texi (Importing Keys): Add documentation for + GpgmeImportStatus, GpgmeImportResult and gpgme_op_import_result. + + * gpgme.texi (Generating Keys): Fix documentation of public and + secret arguments. + +2003-04-24 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Generating Keys): Document changed gpgme_op_genkey + and new gpgme_op_genkey_result function. Document + GpgmeGenKeyResult data type. + + * gpgme.texi (Error Values): Rename GPGME_No_Passphrase to + GPGME_Bad_Passphrase. + * gpgme.texi (Decrypt): Likewise. + (Decrypt and Verify): Likewise. + (Creating a Signature): Likewise. + (Encrypting a Plaintext): Likewise. + + * gpgme.texi (Error Values): Rename GPGME_No_Recipients to + GPGME_No_UserID and GPGME_Invalid_Recipient to + GPGME_Invalid_UserID. + (Encrypting a Plaintext): Likewise. + + * gpgme.texi (Error Values): Remove GPGME_Busy and GPGME_No_Request. + (Listing Keys): Likewise. + (Listing Trust Items): Likewise. + +2003-02-06 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Cancelling an Operation): Removed. + (Passphrase Callback): Document new type for GpgmePassphraseCb. + +2003-01-30 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Engine Information): Rename member part to + file_name. + + * gpgme.texi (Protocols and Engines): Document + gpgme_get_protocol_name. + + * gpgme.texi (Engine Information): Rewritten. + +2003-01-29 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (I/O Callback Interface): Document new even + GPGME_EVENT_START. + (Waiting For Completion): Document new possible return values. + (I/O Callback Interface): Document return type of GpgmeIOCb. + +2003-01-29 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Hooking Up Into Idle Time): Section removed. + +2002-12-24 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Verify): Drop R_STAT argument in gpgme_op_verify. + * gpgme.texi (Decrypt and Verify): Likewise for + gpgme_op_decrypt_verify. + +2002-12-23 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Information About Keys): Document that + GPGME_ATTR_IS_SECRET is not representable as a string anymore. + +2002-12-22 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Key Signatures): New section. + (Listing Keys): Add gpgme_get_key. + +2002-12-06 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Memory Based Data Buffers): New subsection. + (File Based Data Buffers): Likewise. + (Callback Based Data Buffers): Likewise. + (Manipulating Data Buffers): Update interfaces. Add + gpgme_data_seek. + * gpgme.texi (Engine Version Check): Remove gpgme_check_engine. + +2002-11-21 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Verify): Document the new interface. + +2002-11-19 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Generating Keys): Document new argument to + gpgme_op_genkey. + +2002-11-05 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Verify): Fix prototype of gpgme_get_sig_key. + Reported by Miguel Coca <e970095@zipi.fi.upm.es>. + +2002-08-30 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Selecting Signers): Fix reference count. + +2002-08-21 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Header): Document name space. + +2002-08-20 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Importing Keys): Document gpgme_op_import_ext. + + * gpgme.texi (Importing Keys): Undocument EOF. + +2002-08-14 Werner Koch <wk@gnupg.org> + + * gpgme.texi (Information About Keys): Changed GPGME_ATTR_TYPE. + +2002-07-25 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Deleting Keys): Say that secret keys might not be + deleted. + +2002-07-25 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Information About Keys): Document (badly) the new + key attributes. + + * gpgme.texi (Manipulating Data Buffers): Mention that backend + tries to detect encoding automatically. + +2002-07-03 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Run Control): Update this section. + (Waiting For Completion): Likewise for this subsection. + (Cancelling an Operation): Likewise for this subsection. + (Using External Event Loops): New subsection with several + subsubsections. + +2002-06-28 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Multi Threading): Remove item about the need to + synchronize anything against gpgme_wait (except gpgme_wait + itself). + +2002-06-27 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Information About Keys): Fix documentation for IDX. + (Information About Trust Items): Likewise. + +2002-06-26 Werner Koch <wk@gnupg.org> + + * gpgme.texi (Importing Keys): Document the return value -1 of + gpgme_op_import. + +2002-06-20 Werner Koch <wk@gnupg.org> + + * gpgme.texi (Verify): Explain the new whatidx variable. + +2002-06-10 Werner Koch <wk@gnupg.org> + + * gpgme.texi (Verify): Document attribute GPGME_ATTR_ERRTOK. + +2002-06-04 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Multi Threading): Document new autodetection. + +2002-06-04 Marcus Brinkmann <marcus@g10code.de> + + * Makefile.am (DISTCLEANFILES): New variable. + +2002-05-26 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi: Some typographical correctons throughout. + +2002-05-09 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Using Automake): New section. + +2002-05-09 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Multi Threading): Escape { and }. + +2002-05-09 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Overview): Replace note about thread-safeness. + (Multi Threading): New section. + +2002-05-03 Werner Koch <wk@gnupg.org> + + * gpgme.texi (Manipulating Data Buffers): Changed some data types + to void*. + (Protocol Selection): Added gpgme_get_protocol. + (Verify): Updated to include the new attribute fucntions and + status codes. + +2002-04-27 Werner Koch <wk@gnupg.org> + + * gpgme.texi (Manipulating Data Buffers): New type GpgmeDataEncoding. + +2002-04-23 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Passphrase Callback): Document that either return + argument can be NULL. + (Progress Meter Callback): Likewise. + +2002-04-22 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Passphrase Callback): Fix small typo. Document the + new function gpgme_get_passphrase_cb. + (Progress Meter Callback): Document the new function + gpgme_get_progress_cb. + +2002-04-16 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Creating a Signature): Fix function name. Reported + by Wichert Ackerman <wichert@debian.org>. + +2002-03-29 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (direntry): End index entry with a full stop. + Patch submitted by Jose Carlos Garcia Sogo <jsogo@debian.org>. + +2002-03-17 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Detailed Results): Fix syntax error in last change. + +2002-03-08 Werner Koch <wk@gnupg.org> + + * gpgme.texi (Detailed Results): Import does also return info. + +2002-03-06 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Encrypting a Plaintext): Document symmetric + encryption. + +2002-03-06 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Error Strings): Add example. + * gpgme.texi (Listing Keys): Likewise. + +2002-03-03 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Information About Keys): Document GPGME_ATTR_EXPIRE. + +2002-03-03 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Verify): Document verification of normal and + cleartext signatures. + +2002-02-27 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Listing Keys): Document gpgme_op_keylist_ext_start. + +2002-02-27 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Encrypting a Plaintext): Document + GPGME_Invalid_Recipients. + (Error Values): Likewise. + +2002-02-26 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Encrypting a Plaintext): Document + gpgme_op_encrypt_sign and gpgme_op_encrypt_sign_start. + +2002-02-25 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Creating a Signature): Add a note about + certificates to include. + (Included Certificates): New section. + +2002-02-09 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Detailed Results): Remove literal tags. + (Generating Keys): Update documentation. + + * gpgme.texi (Generating Keys): Fix syntax error. + +2002-02-06 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Waiting For Completion): Adjust doc to changes in + the code. + +2002-02-06 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Key Listing Mode): Update documentation. + +2002-01-31 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Generating Keys): Document error at creation + failure. + +2002-01-30 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Deleting Keys): Document new error values. + +2002-01-30 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Importing Keys): Add reference to gpgme_get_op_info. + +2002-01-30 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi: Some spell checking. + +2002-01-30 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi: Add all the gpgme_op_*_start functions. + Fill the concept index with many, many entries. + +2002-01-29 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Run Control): New section. + (Verify): Docuent gpgme_get_notation. + (More Information): New section describing gpgme_get_op_info. + +2002-01-22 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Passphrase callback): Change GpgmePassphraseCb's + R_HD type from void* to void**. + +2002-01-22 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Creating data buffers): Change + gpgme_data_new_from_filepart's LENGTH type from off_t to size_t. + +2002-01-22 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi (Generating keys): New subsection. + (Exporting keys): Likewise. + (Importing keys): Likewise. + (Deleting keys): Likewise. + +2002-01-16 Marcus Brinkmann <marcus@g10code.de> + + * gpgme.texi: g10Code -> g10 Code + + * gpgme.texi (Top): Complete detailmenu. + + * gpgme.texi: Convert embarassing cruft to the real thing. + +2002-01-16 Marcus Brinkmann <marcus@g10code.de> + + * ChangeLog: New file. + * gpgme.texi: Likewise. + * gpl.texi: Likewise. + * fdl.texi: Likewise. + * Makefile.am (info_TEXINFOS): New variable. + (gpgme_TEXINFOS): Likewise. + + Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, + 2011 g10 Code GmbH + + This file is free software; as a special exception the author gives + unlimited permission to copy and/or distribute it, with or without + modifications, as long as this notice is preserved. + + This file is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY, to the extent permitted by law; without even the + implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. diff --git a/doc/HACKING b/doc/HACKING new file mode 100644 index 0000000..6149d25 --- /dev/null +++ b/doc/HACKING @@ -0,0 +1,28 @@ +# HACKING -*- org -*- +#+TITLE: Hacking notes for GPGME +#+STARTUP: showall + +* No more ChangeLog files + + Do not modify any of the ChangeLog files in GPGME. Starting + on December 1st, 2011 we put change information only in the GIT + commit log, and generate a top-level ChangeLog file from logs at + "make dist" time. As such, there are strict requirements on the + form of the commit log messages. The old ChangeLog files have all + be renamed to ChangeLog-2011 + + +* Commit log requirements + + Your commit log should always start with a one-line summary, the + second line should be blank, and the remaining lines are usually + ChangeLog-style entries for all affected files. However, it's fine + -- even recommended -- to write a few lines of prose describing the + change, when the summary and ChangeLog entries don't give enough of + the big picture. Omit the leading TABs that you're used to seeing + in a "real" ChangeLog file, but keep the maximum line length at 72 + or smaller, so that the generated ChangeLog lines, each with its + leading TAB, will not exceed 80 columns. + + Note that ./autogen.sh installs a git hook to do some basic syntax + checking on the commit log message. diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..93afc06 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,36 @@ +# doc - Automake template +# Copyright (C) 2001, 2004 g10 Code GmbH +# +# This file is part of GPGME. +# +# GPGME is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as +# published by the Free Software Foundation; either version 2.1 of the +# License, or (at your option) any later version. +# +# GPGME is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General +# Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + +## Process this file with automake to produce Makefile.in + +DISTCLEANFILES = gpgme.tmp + +EXTRA_DIST = module-overview.sk HACKING ChangeLog-2011 + +info_TEXINFOS = gpgme.texi +gpgme_TEXINFOS = uiserver.texi lesser.texi gpl.texi + +online: gpgme.html gpgme.pdf + set -e; \ + echo "Uploading current manuals to www.gnupg.org ..."; \ + user=werner ; \ + (cd gpgme.html && rsync -vr --exclude='.svn' . \ + $${user}@cvs.gnupg.org:webspace/manuals/gpgme/ ); \ + rsync -v gpgme.pdf $${user}@cvs.gnupg.org:webspace/manuals/ + diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..31455d6 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,722 @@ +# Makefile.in generated by automake 1.11.1 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, +# Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# doc - Automake template +# Copyright (C) 2001, 2004 g10 Code GmbH +# +# This file is part of GPGME. +# +# GPGME is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as +# published by the Free Software Foundation; either version 2.1 of the +# License, or (at your option) any later version. +# +# GPGME is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General +# Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc +DIST_COMMON = $(gpgme_TEXINFOS) $(srcdir)/Makefile.am \ + $(srcdir)/Makefile.in $(srcdir)/stamp-vti \ + $(srcdir)/version.texi mdate-sh texinfo.tex +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/glib-2.0.m4 \ + $(top_srcdir)/m4/glibc21.m4 $(top_srcdir)/m4/gnupg-ttyname.m4 \ + $(top_srcdir)/m4/gpg-error.m4 $(top_srcdir)/m4/libassuan.m4 \ + $(top_srcdir)/m4/libtool.m4 $(top_srcdir)/m4/ltoptions.m4 \ + $(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \ + $(top_srcdir)/m4/lt~obsolete.m4 $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +SOURCES = +DIST_SOURCES = +INFO_DEPS = $(srcdir)/gpgme.info +am__TEXINFO_TEX_DIR = $(srcdir) +DVIS = gpgme.dvi +PDFS = gpgme.pdf +PSS = gpgme.ps +HTMLS = gpgme.html +TEXINFOS = gpgme.texi +TEXI2DVI = texi2dvi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +am__installdirs = "$(DESTDIR)$(infodir)" +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AR = @AR@ +AS = @AS@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BUILD_FILEVERSION = @BUILD_FILEVERSION@ +BUILD_NUMBER = @BUILD_NUMBER@ +BUILD_TIMESTAMP = @BUILD_TIMESTAMP@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +G13 = @G13@ +GITLOG_TO_CHANGELOG = @GITLOG_TO_CHANGELOG@ +GLIBC21 = @GLIBC21@ +GLIB_CFLAGS = @GLIB_CFLAGS@ +GLIB_GENMARSHAL = @GLIB_GENMARSHAL@ +GLIB_LIBS = @GLIB_LIBS@ +GLIB_MKENUMS = @GLIB_MKENUMS@ +GOBJECT_QUERY = @GOBJECT_QUERY@ +GPG = @GPG@ +GPGCONF = @GPGCONF@ +GPGME_CONFIG_API_VERSION = @GPGME_CONFIG_API_VERSION@ +GPGME_CONFIG_CFLAGS = @GPGME_CONFIG_CFLAGS@ +GPGME_CONFIG_HOST = @GPGME_CONFIG_HOST@ +GPGME_CONFIG_LIBS = @GPGME_CONFIG_LIBS@ +GPGSM = @GPGSM@ +GPG_ERROR_CFLAGS = @GPG_ERROR_CFLAGS@ +GPG_ERROR_CONFIG = @GPG_ERROR_CONFIG@ +GPG_ERROR_LIBS = @GPG_ERROR_LIBS@ +GPG_PATH = @GPG_PATH@ +GREP = @GREP@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LIBASSUAN_CFLAGS = @LIBASSUAN_CFLAGS@ +LIBASSUAN_CONFIG = @LIBASSUAN_CONFIG@ +LIBASSUAN_LIBS = @LIBASSUAN_LIBS@ +LIBGPGME_LT_AGE = @LIBGPGME_LT_AGE@ +LIBGPGME_LT_CURRENT = @LIBGPGME_LT_CURRENT@ +LIBGPGME_LT_REVISION = @LIBGPGME_LT_REVISION@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MKDIR_P = @MKDIR_P@ +NEED__FILE_OFFSET_BITS = @NEED__FILE_OFFSET_BITS@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PKG_CONFIG = @PKG_CONFIG@ +QT4_CORE_CFLAGS = @QT4_CORE_CFLAGS@ +QT4_CORE_LIBS = @QT4_CORE_LIBS@ +RANLIB = @RANLIB@ +RC = @RC@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +emacs_local_vars_begin = @emacs_local_vars_begin@ +emacs_local_vars_end = @emacs_local_vars_end@ +emacs_local_vars_read_only = @emacs_local_vars_read_only@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +DISTCLEANFILES = gpgme.tmp +EXTRA_DIST = module-overview.sk HACKING ChangeLog-2011 +info_TEXINFOS = gpgme.texi +gpgme_TEXINFOS = uiserver.texi lesser.texi gpl.texi +all: all-am + +.SUFFIXES: +.SUFFIXES: .dvi .html .info .pdf .ps .texi +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs + +.texi.info: + restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && $(am__cd) $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + $(am__cd) $(srcdir); \ + else \ + rc=$$?; \ + $(am__cd) $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texi.dvi: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $< + +.texi.pdf: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $< + +.texi.html: + rm -rf $(@:.html=.htp) + if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@; \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ + else \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ + exit 1; \ + fi +$(srcdir)/gpgme.info: gpgme.texi $(srcdir)/version.texi $(gpgme_TEXINFOS) +gpgme.dvi: gpgme.texi $(srcdir)/version.texi $(gpgme_TEXINFOS) +gpgme.pdf: gpgme.texi $(srcdir)/version.texi $(gpgme_TEXINFOS) +gpgme.html: gpgme.texi $(srcdir)/version.texi $(gpgme_TEXINFOS) +$(srcdir)/version.texi: @MAINTAINER_MODE_TRUE@ $(srcdir)/stamp-vti +$(srcdir)/stamp-vti: gpgme.texi $(top_srcdir)/configure + @(dir=.; test -f ./gpgme.texi || dir=$(srcdir); \ + set `$(SHELL) $(srcdir)/mdate-sh $$dir/gpgme.texi`; \ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > vti.tmp + @cmp -s vti.tmp $(srcdir)/version.texi \ + || (echo "Updating $(srcdir)/version.texi"; \ + cp vti.tmp $(srcdir)/version.texi) + -@rm -f vti.tmp + @cp $(srcdir)/version.texi $@ + +mostlyclean-vti: + -rm -f vti.tmp + +maintainer-clean-vti: +@MAINTAINER_MODE_TRUE@ -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi +.dvi.ps: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ + rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ + done + +uninstall-info-am: + @$(PRE_UNINSTALL) + @if test -d '$(DESTDIR)$(infodir)' && \ + (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +uninstall-pdf-am: + @$(NORMAL_UNINSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ + rm -f "$(DESTDIR)$(psdir)/$$f"; \ + done + +dist-info: $(INFO_DEPS) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ + for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ + if test -f $$file; then \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f "$(distdir)/$$relfile" || \ + cp -p $$file "$(distdir)/$$relfile"; \ + else :; fi; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf gpgme.aux gpgme.cp gpgme.cps gpgme.fn gpgme.fns gpgme.ky gpgme.kys \ + gpgme.log gpgme.pg gpgme.tmp gpgme.toc gpgme.tp gpgme.vr \ + gpgme.vrs + +clean-aminfo: + -test -z "gpgme.dvi gpgme.pdf gpgme.ps gpgme.html" \ + || rm -rf gpgme.dvi gpgme.pdf gpgme.ps gpgme.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info +check-am: all-am +check: check-am +all-am: Makefile $(INFO_DEPS) +installdirs: + for dir in "$(DESTDIR)$(infodir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + -test -z "$(DISTCLEANFILES)" || rm -f $(DISTCLEANFILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: $(DVIS) + +html: html-am + +html-am: $(HTMLS) + +info: info-am + +info-am: $(INFO_DEPS) + +install-data-am: install-info-am + +install-dvi: install-dvi-am + +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)" + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \ + done +install-exec-am: + +install-html: install-html-am + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)" + @list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + $(am__strip_dir) \ + if test -d "$$d$$p"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \ + else \ + list2="$$list2 $$d$$p"; \ + fi; \ + done; \ + test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ + done; } +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)" + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + echo "$$ifile"; \ + else : ; fi; \ + done; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done + @$(POST_INSTALL) + @if (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)" + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done +install-ps: install-ps-am + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)" + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic maintainer-clean-vti + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \ + mostlyclean-libtool mostlyclean-vti + +pdf: pdf-am + +pdf-am: $(PDFS) + +ps: ps-am + +ps-am: $(PSS) + +uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-aminfo clean-generic \ + clean-libtool dist-info distclean distclean-generic \ + distclean-libtool distdir dvi dvi-am html html-am info info-am \ + install install-am install-data install-data-am install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-aminfo \ + maintainer-clean-generic maintainer-clean-vti mostlyclean \ + mostlyclean-aminfo mostlyclean-generic mostlyclean-libtool \ + mostlyclean-vti pdf pdf-am ps ps-am uninstall uninstall-am \ + uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + + +online: gpgme.html gpgme.pdf + set -e; \ + echo "Uploading current manuals to www.gnupg.org ..."; \ + user=werner ; \ + (cd gpgme.html && rsync -vr --exclude='.svn' . \ + $${user}@cvs.gnupg.org:webspace/manuals/gpgme/ ); \ + rsync -v gpgme.pdf $${user}@cvs.gnupg.org:webspace/manuals/ + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/doc/gpgme.info b/doc/gpgme.info new file mode 100644 index 0000000..a035624 --- /dev/null +++ b/doc/gpgme.info @@ -0,0 +1,156 @@ +This is /home/wk/w/gpgme/doc/gpgme.info, produced by makeinfo version +4.13 from /home/wk/w/gpgme/doc/gpgme.texi. + +INFO-DIR-SECTION GNU Libraries +START-INFO-DIR-ENTRY +* GPGME: (gpgme). Adding support for cryptography to your program. +END-INFO-DIR-ENTRY + + Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 g10 +Code GmbH. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 3 of the + License, or (at your option) any later version. The text of the + license can be found in the section entitled "Copying". + + This document is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + + This file documents the GPGME library. + + This is Edition 1.3.2, last updated 2 May 2012, of `The `GnuPG Made +Easy' Reference Manual', for Version 1.3.2. + + Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 g10 +Code GmbH. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 3 of the + License, or (at your option) any later version. The text of the + license can be found in the section entitled "Copying". + + This document is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + + +Indirect: +gpgme.info-1: 1731 +gpgme.info-2: 276396 + +Tag Table: +(Indirect) +Node: Top1731 +Node: Introduction8512 +Node: Getting Started9299 +Node: Features10424 +Node: Overview11574 +Node: Preparation12683 +Node: Header13680 +Node: Building the Source14379 +Node: Largefile Support (LFS)16488 +Node: Using Automake20492 +Node: Using Libtool22128 +Node: Library Version Check22478 +Node: Signal Handling25366 +Node: Multi Threading26582 +Ref: Multi Threading-Footnote-128764 +Node: Protocols and Engines29178 +Node: Engine Version Check31527 +Node: Engine Information32104 +Node: Engine Configuration35804 +Node: OpenPGP37066 +Node: Cryptographic Message Syntax37402 +Node: Algorithms37696 +Ref: Algorithms-Footnote-138175 +Node: Public Key Algorithms38303 +Node: Hash Algorithms40234 +Node: Error Handling41332 +Node: Error Values43194 +Node: Error Sources48272 +Node: Error Codes50599 +Node: Error Strings55238 +Node: Exchanging Data57017 +Node: Creating Data Buffers58331 +Node: Memory Based Data Buffers58847 +Node: File Based Data Buffers62201 +Node: Callback Based Data Buffers64372 +Node: Destroying Data Buffers69928 +Node: Manipulating Data Buffers71287 +Node: Data Buffer I/O Operations71706 +Node: Data Buffer Meta-Data74409 +Node: Contexts77759 +Node: Creating Contexts78882 +Node: Destroying Contexts79693 +Node: Result Management80028 +Node: Context Attributes81434 +Node: Protocol Selection82212 +Node: Crypto Engine83224 +Node: ASCII Armor85045 +Node: Text Mode85657 +Node: Included Certificates86588 +Node: Key Listing Mode87963 +Node: Passphrase Callback91320 +Node: Progress Meter Callback94370 +Node: Locale96294 +Node: Key Management97833 +Node: Listing Keys107761 +Node: Information About Keys115023 +Node: Key Signatures123021 +Node: Manipulating Keys127033 +Node: Generating Keys127875 +Node: Exporting Keys132482 +Node: Importing Keys138381 +Ref: Importing Keys-Footnote-1145544 +Node: Deleting Keys145672 +Node: Changing Passphrases147069 +Node: Advanced Key Editing148330 +Node: Trust Item Management151434 +Node: Listing Trust Items152504 +Node: Information About Trust Items154802 +Node: Manipulating Trust Items156684 +Node: Crypto Operations157645 +Node: Decrypt158889 +Node: Verify162747 +Node: Decrypt and Verify180603 +Node: Sign182607 +Node: Selecting Signers183171 +Node: Creating a Signature184152 +Node: Signature Notation Data188741 +Node: Encrypt190925 +Node: Encrypting a Plaintext191281 +Node: Run Control197126 +Node: Waiting For Completion197873 +Node: Using External Event Loops199919 +Node: I/O Callback Interface201886 +Node: Registering I/O Callbacks206980 +Node: I/O Callback Example208971 +Node: I/O Callback Example GTK+215190 +Node: I/O Callback Example GDK216979 +Node: I/O Callback Example Qt218621 +Node: Cancellation220909 +Node: UI Server Protocol223162 +Ref: UI Server Protocol-Footnote-1224599 +Node: UI Server Encrypt224718 +Node: UI Server Sign229899 +Node: UI Server Decrypt232128 +Node: UI Server Verify233566 +Node: UI Server Set Input Files237068 +Node: UI Server Sign/Encrypt Files237868 +Node: UI Server Verify/Decrypt Files239637 +Node: UI Server Import/Export Keys241483 +Node: UI Server Checksum Files242516 +Node: Miscellaneous UI Server Commands244682 +Ref: command SENDER246594 +Node: Library Copying248270 +Node: Copying276396 +Node: Function and Data Index314027 +Node: Concept Index339006 + +End Tag Table diff --git a/doc/gpgme.info-1 b/doc/gpgme.info-1 new file mode 100644 index 0000000..35b948a --- /dev/null +++ b/doc/gpgme.info-1 @@ -0,0 +1,6615 @@ +This is /home/wk/w/gpgme/doc/gpgme.info, produced by makeinfo version +4.13 from /home/wk/w/gpgme/doc/gpgme.texi. + +INFO-DIR-SECTION GNU Libraries +START-INFO-DIR-ENTRY +* GPGME: (gpgme). Adding support for cryptography to your program. +END-INFO-DIR-ENTRY + + Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 g10 +Code GmbH. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 3 of the + License, or (at your option) any later version. The text of the + license can be found in the section entitled "Copying". + + This document is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + + This file documents the GPGME library. + + This is Edition 1.3.2, last updated 2 May 2012, of `The `GnuPG Made +Easy' Reference Manual', for Version 1.3.2. + + Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 g10 +Code GmbH. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 3 of the + License, or (at your option) any later version. The text of the + license can be found in the section entitled "Copying". + + This document is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + + +File: gpgme.info, Node: Top, Next: Introduction, Up: (dir) + +Main Menu +********* + +This is Edition 1.3.2, last updated 2 May 2012, of `The `GnuPG Made +Easy' Reference Manual', for Version 1.3.2 of the GPGME library. + +* Menu: + +* Introduction:: How to use this manual. +* Preparation:: What you should do before using the library. +* Protocols and Engines:: Supported crypto protocols. +* Algorithms:: Supported algorithms. +* Error Handling:: Error numbers and their meanings. +* Exchanging Data:: Passing data to and from GPGME. +* Contexts:: Handling GPGME contexts. + +Appendices + +* UI Server Protocol:: The GnuPG UI Server Protocol. + +* Library Copying:: The GNU Lesser General Public License says + how you can copy and share `GnuPG Made Easy'. +* Copying:: The GNU General Public License says how you + can copy and share this manual. + +Indices + +* Concept Index:: Index of concepts and programs. +* Function and Data Index:: Index of functions, variables and data types. + + + --- The Detailed Node Listing --- + +Introduction + +* Getting Started:: Purpose of the manual, and how to use it. +* Features:: Reasons to install and use GPGME. +* Overview:: Basic architecture of the GPGME library. + +Preparation + +* Header:: What header file you need to include. +* Building the Source:: Compiler options to be used. +* Largefile Support (LFS):: How to use GPGME with LFS. +* Using Automake:: Compiler options to be used the easy way. +* Using Libtool:: Avoiding compiler options entirely. +* Library Version Check:: Getting and verifying the library version. +* Signal Handling:: How GPGME affects signal handling. +* Multi Threading:: How GPGME can be used in an MT environment. + +Protocols and Engines + +* Engine Version Check:: Verifying the engine version. +* Engine Information:: Obtaining more information about the engines. +* Engine Configuration:: Changing the engine configuration. +* OpenPGP:: Support for the OpenPGP protocol. +* Cryptographic Message Syntax:: Support for the CMS. + +Algorithms + +* Public Key Algorithms:: A list of all public key algorithms. +* Hash Algorithms:: A list of all hash algorithms. + +Error Handling + +* Error Values:: The error value and what it means. +* Error Codes:: A list of important error codes. +* Error Sources:: A list of important error sources. +* Error Strings:: How to get a descriptive string from a value. + +Exchanging Data + +* Creating Data Buffers:: Creating new data buffers. +* Destroying Data Buffers:: Releasing data buffers. +* Manipulating Data Buffers:: Operations on data buffers. + +Creating Data Buffers + +* Memory Based Data Buffers:: Creating memory based data buffers. +* File Based Data Buffers:: Creating file based data buffers. +* Callback Based Data Buffers:: Creating callback based data buffers. + +Manipulating Data Buffers + +* Data Buffer I/O Operations:: I/O operations on data buffers. +* Data Buffer Meta-Data:: Meta-data manipulation of data buffers. + +Contexts + +* Creating Contexts:: Creating new GPGME contexts. +* Destroying Contexts:: Releasing GPGME contexts. +* Result Management:: Managing the result of crypto operations. +* Context Attributes:: Setting properties of a context. +* Key Management:: Managing keys with GPGME. +* Trust Item Management:: Managing trust items with GPGME. +* Crypto Operations:: Using a context for cryptography. +* Run Control:: Controlling how operations are run. + +Context Attributes + +* Protocol Selection:: Selecting the protocol used by a context. +* Crypto Engine:: Configuring the crypto engine. +* ASCII Armor:: Requesting ASCII armored output. +* Text Mode:: Choosing canonical text mode. +* Included Certificates:: Including a number of certificates. +* Key Listing Mode:: Selecting key listing mode. +* Passphrase Callback:: Getting the passphrase from the user. +* Progress Meter Callback:: Being informed about the progress. +* Locale:: Setting the locale of a context. + +Key Management + +* Listing Keys:: Browsing the list of available keys. +* Information About Keys:: Requesting detailed information about keys. +* Key Signatures:: Listing the signatures on a key. +* Manipulating Keys:: Operations on keys. +* Generating Keys:: Creating new key pairs. +* Exporting Keys:: Retrieving key data from the key ring. +* Importing Keys:: Adding keys to the key ring. +* Deleting Keys:: Removing keys from the key ring. +* Advanced Key Editing:: Advanced key edit operation. + +Trust Item Management + +* Listing Trust Items:: Browsing the list of available trust items. +* Information About Trust Items:: Requesting information about trust items. +* Manipulating Trust Items:: Operations on trust items. + +Crypto Operations + +* Decrypt:: Decrypting a ciphertext. +* Verify:: Verifying a signature. +* Decrypt and Verify:: Decrypting a signed ciphertext. +* Sign:: Creating a signature. +* Encrypt:: Encrypting a plaintext. + +Sign + +* Selecting Signers:: How to choose the keys to sign with. +* Creating a Signature:: How to create a signature. +* Signature Notation Data:: How to add notation data to a signature. + +Encrypt + +* Encrypting a Plaintext:: How to encrypt a plaintext. + +Run Control + +* Waiting For Completion:: Waiting until an operation is completed. +* Using External Event Loops:: Advanced control over what happens when. +* Cancellation:: How to end pending operations prematurely. + +Using External Event Loops + +* I/O Callback Interface:: How I/O callbacks are registered. +* Registering I/O Callbacks:: How to use I/O callbacks for a context. +* I/O Callback Example:: An example how to use I/O callbacks. +* I/O Callback Example GTK+:: How to integrate GPGME in GTK+. +* I/O Callback Example GDK:: How to integrate GPGME in GDK. +* I/O Callback Example Qt:: How to integrate GPGME in Qt. + + +File: gpgme.info, Node: Introduction, Next: Preparation, Prev: Top, Up: Top + +1 Introduction +************** + +`GnuPG Made Easy' (GPGME) is a C language library that allows to add +support for cryptography to a program. It is designed to make access +to public key crypto engines like GnuPG or GpgSM easier for +applications. GPGME provides a high-level crypto API for encryption, +decryption, signing, signature verification and key management. + + GPGME uses GnuPG and GpgSM as its backends to support OpenPGP and +the Cryptographic Message Syntax (CMS). + +* Menu: + +* Getting Started:: Purpose of the manual, and how to use it. +* Features:: Reasons to install and use GPGME. +* Overview:: Basic architecture of the GPGME library. + + +File: gpgme.info, Node: Getting Started, Next: Features, Up: Introduction + +1.1 Getting Started +=================== + +This manual documents the GPGME library programming interface. All +functions and data types provided by the library are explained. + + The reader is assumed to possess basic knowledge about cryptography +in general, and public key cryptography in particular. The underlying +cryptographic engines that are used by the library are not explained, +but where necessary, special features or requirements by an engine are +mentioned as far as they are relevant to GPGME or its users. + + This manual can be used in several ways. If read from the beginning +to the end, it gives a good introduction into the library and how it +can be used in an application. Forward references are included where +necessary. Later on, the manual can be used as a reference manual to +get just the information needed about any particular interface of the +library. Experienced programmers might want to start looking at the +examples at the end of the manual, and then only read up those parts of +the interface which are unclear. + + +File: gpgme.info, Node: Features, Next: Overview, Prev: Getting Started, Up: Introduction + +1.2 Features +============ + +GPGME has a couple of advantages over other libraries doing a similar +job, and over implementing support for GnuPG or other crypto engines +into your application directly. + +it's free software + Anybody can use, modify, and redistribute it under the terms of + the GNU Lesser General Public License (*note Library Copying::). + +it's flexible + GPGME provides transparent support for several cryptographic + protocols by different engines. Currently, GPGME supports the + OpenPGP protocol using GnuPG as the backend, and the Cryptographic + Message Syntax using GpgSM as the backend. + +it's easy + GPGME hides the differences between the protocols and engines from + the programmer behind an easy-to-use interface. This way the + programmer can focus on the other parts of the program, and still + integrate strong cryptography in his application. Once support for + GPGME has been added to a program, it is easy to add support for + other crypto protocols once GPGME backends provide them. + + +File: gpgme.info, Node: Overview, Prev: Features, Up: Introduction + +1.3 Overview +============ + +GPGME provides a data abstraction that is used to pass data to the +crypto engine, and receive returned data from it. Data can be read +from memory or from files, but it can also be provided by a callback +function. + + The actual cryptographic operations are always set within a context. +A context provides configuration parameters that define the behaviour +of all operations performed within it. Only one operation per context +is allowed at any time, but when one operation is finished, you can run +the next operation in the same context. There can be more than one +context, and all can run different operations at the same time. + + Furthermore, GPGME has rich key management facilities including +listing keys, querying their attributes, generating, importing, +exporting and deleting keys, and acquiring information about the trust +path. + + With some precautions, GPGME can be used in a multi-threaded +environment, although it is not completely thread safe and thus needs +the support of the application. + + +File: gpgme.info, Node: Preparation, Next: Protocols and Engines, Prev: Introduction, Up: Top + +2 Preparation +************* + +To use GPGME, you have to perform some changes to your sources and the +build system. The necessary changes are small and explained in the +following sections. At the end of this chapter, it is described how +the library is initialized, and how the requirements of the library are +verified. + +* Menu: + +* Header:: What header file you need to include. +* Building the Source:: Compiler options to be used. +* Largefile Support (LFS):: How to use GPGME with LFS. +* Using Automake:: Compiler options to be used the easy way. +* Using Libtool:: Avoiding compiler options entirely. +* Library Version Check:: Getting and verifying the library version. +* Signal Handling:: How GPGME affects signal handling. +* Multi Threading:: How GPGME can be used in an MT environment. + + +File: gpgme.info, Node: Header, Next: Building the Source, Up: Preparation + +2.1 Header +========== + +All interfaces (data types and functions) of the library are defined in +the header file `gpgme.h'. You must include this in all programs using +the library, either directly or through some other header file, like +this: + + #include <gpgme.h> + + The name space of GPGME is `gpgme_*' for function names and data +types and `GPGME_*' for other symbols. Symbols internal to GPGME take +the form `_gpgme_*' and `_GPGME_*'. + + Because GPGME makes use of the GPG Error library, using GPGME will +also use the `GPG_ERR_*' name space directly, and the `gpg_err*' and +`gpg_str*' name space indirectly. + + +File: gpgme.info, Node: Building the Source, Next: Largefile Support (LFS), Prev: Header, Up: Preparation + +2.2 Building the Source +======================= + +If you want to compile a source file including the `gpgme.h' header +file, you must make sure that the compiler can find it in the directory +hierarchy. This is accomplished by adding the path to the directory in +which the header file is located to the compilers include file search +path (via the `-I' option). + + However, the path to the include file is determined at the time the +source is configured. To solve this problem, gpgme ships with a small +helper program `gpgme-config' that knows about the path to the include +file and other configuration options. The options that need to be +added to the compiler invocation at compile time are output by the +`--cflags' option to `gpgme-config'. The following example shows how +it can be used at the command line: + + gcc -c foo.c `gpgme-config --cflags` + + Adding the output of `gpgme-config --cflags' to the compiler command +line will ensure that the compiler can find the GPGME header file. + + A similar problem occurs when linking the program with the library. +Again, the compiler has to find the library files. For this to work, +the path to the library files has to be added to the library search +path (via the `-L' option). For this, the option `--libs' to +`gpgme-config' can be used. For convenience, this option also outputs +all other options that are required to link the program with GPGME (in +particular, the `-lgpgme' option). The example shows how to link +`foo.o' with the GPGME library to a program `foo'. + + gcc -o foo foo.o `gpgme-config --libs` + + Of course you can also combine both examples to a single command by +specifying both options to `gpgme-config': + + gcc -o foo foo.c `gpgme-config --cflags --libs` + + If you want to link to one of the thread-safe versions of GPGME, you +must specify the `--thread' option before any other option to select +the thread package you want to link with. Supported thread packages +are `--thread=pth' and `--thread=pthread'. + + +File: gpgme.info, Node: Largefile Support (LFS), Next: Using Automake, Prev: Building the Source, Up: Preparation + +2.3 Largefile Support (LFS) +=========================== + +GPGME is compiled with largefile support by default, if it is available +on the system. This means that GPGME supports files larger than two +gigabyte in size, if the underlying operating system can. On some +systems, largefile support is already the default. On such systems, +nothing special is required. However, some systems provide only +support for files up to two gigabyte in size by default. Support for +larger file sizes has to be specifically enabled. + + To make a difficult situation even more complex, such systems provide +two different types of largefile support. You can either get all +relevant functions replaced with alternatives that are largefile +capable, or you can get new functions and data types for largefile +support added. Those new functions have the same name as their +smallfile counterparts, but with a suffix of 64. + + An example: The data type `off_t' is 32 bit wide on GNU/Linux PC +systems. To address offsets in large files, you can either enable +largefile support add-on. Then a new data type `off64_t' is provided, +which is 64 bit wide. Or you can replace the existing `off_t' data +type with its 64 bit wide counterpart. All occurences of `off_t' are +then automagically replaced. + + As if matters were not complex enough, there are also two different +types of file descriptors in such systems. This is important because +if file descriptors are exchanged between programs that use a different +maximum file size, certain errors must be produced on some file +descriptors to prevent subtle overflow bugs from occuring. + + As you can see, supporting two different maximum file sizes at the +same time is not at all an easy task. However, the maximum file size +does matter for GPGME, because some data types it uses in its +interfaces are affected by that. For example, the `off_t' data type is +used in the `gpgme_data_seek' function, to match its POSIX counterpart. +This affects the call-frame of the function, and thus the ABI of the +library. Furthermore, file descriptors can be exchanged between GPGME +and the application. + + For you as the user of the library, this means that your program must +be compiled in the same file size mode as the library. Luckily, there +is absolutely no valid reason for new programs to not enable largefile +support by default and just use that. The compatibility modes (small +file sizes or dual mode) can be considered an historic artefact, only +useful to allow for a transitional period. + + GPGME is compiled using largefile support by default. This means +that your application must do the same, at least as far as it is +relevant for using the `gpgme.h' header file. All types in this header +files refer to their largefile counterparts, if they are different from +any default types on the system. + + You can enable largefile support, if it is different from the default +on the system the application is compiled on, by using the Autoconf +macro `AC_SYS_LARGEFILE'. If you do this, then you don't need to worry +about anything else: It will just work. In this case you might also +want to use `AC_FUNC_FSEEKO' to take advantage of some new interfaces, +and `AC_TYPE_OFF_T' (just in case). + + If you do not use Autoconf, you can define the preprocessor symbol +`_FILE_OFFSET_BITS' to 64 _before_ including any header files, for +example by specifying the option `-D_FILE_OFFSET_BITS=64' on the +compiler command line. You will also want to define the preprocessor +symbol `LARGEFILE_SOURCE' to 1 in this case, to take advantage of some +new interfaces. + + If you do not want to do either of the above, you probably know +enough about the issue to invent your own solution. Just keep in mind +that the GPGME header file expects that largefile support is enabled, +if it is available. In particular, we do not support dual mode +(`_LARGEFILE64_SOURCE'). + + +File: gpgme.info, Node: Using Automake, Next: Using Libtool, Prev: Largefile Support (LFS), Up: Preparation + +2.4 Using Automake +================== + +It is much easier if you use GNU Automake instead of writing your own +Makefiles. If you do that you do not have to worry about finding and +invoking the `gpgme-config' script at all. GPGME provides an extension +to Automake that does all the work for you. + + -- Macro: AM_PATH_GPGME ([MINIMUM-VERSION], [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + -- Macro: AM_PATH_GPGME_PTH ([MINIMUM-VERSION], [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + -- Macro: AM_PATH_GPGME_PTHREAD ([MINIMUM-VERSION], [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Check whether GPGME (at least version MINIMUM-VERSION, if given) + exists on the host system. If it is found, execute + ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given. + + Additionally, the function defines `GPGME_CFLAGS' to the flags + needed for compilation of the program to find the `gpgme.h' header + file, and `GPGME_LIBS' to the linker flags needed to link the + program to the GPGME library. + + `AM_PATH_GPGME_PTH' checks for the version of GPGME that can be + used with GNU Pth, and defines `GPGME_PTH_CFLAGS' and + `GPGME_PTH_LIBS'. + + `AM_PATH_GPGME_PTHREAD' checks for the version of GPGME that can + be used with the native pthread implementation, and defines + `GPGME_PTHREAD_CFLAGS' and `GPGME_PTHREAD_LIBS'. + + You can use the defined Autoconf variables like this in your +`Makefile.am': + + AM_CPPFLAGS = $(GPGME_CFLAGS) + LDADD = $(GPGME_LIBS) + + +File: gpgme.info, Node: Using Libtool, Next: Library Version Check, Prev: Using Automake, Up: Preparation + +2.5 Using Libtool +================= + +The easiest way is to just use GNU Libtool. If you use libtool, and +link to `libgpgme.la', `libgpgme-pth.la' or `libgpgme-pthread.la' +respectively, everything will be done automatically by Libtool. + + +File: gpgme.info, Node: Library Version Check, Next: Signal Handling, Prev: Using Libtool, Up: Preparation + +2.6 Library Version Check +========================= + + -- Function: const char * gpgme_check_version + (const char *REQUIRED_VERSION) + The function `gpgme_check_version' has four purposes. It can be + used to retrieve the version number of the library. In addition it + can verify that the version number is higher than a certain + required version number. In either case, the function initializes + some sub-systems, and for this reason alone it must be invoked + early in your program, before you make use of the other functions + in GPGME. The last purpose is to run selftests. + + As a side effect for W32 based systems, the socket layer will get + initialized. + + If REQUIRED_VERSION is `NULL', the function returns a pointer to a + statically allocated string containing the version number of the + library. + + If REQUIRED_VERSION is not `NULL', it should point to a string + containing a version number, and the function checks that the + version of the library is at least as high as the version number + provided. In this case, the function returns a pointer to a + statically allocated string containing the version number of the + library. If REQUIRED_VERSION is not a valid version number, or if + the version requirement is not met, the function returns `NULL'. + + If you use a version of a library that is backwards compatible with + older releases, but contains additional interfaces which your + program uses, this function provides a run-time check if the + necessary features are provided by the installed version of the + library. + + If a selftest fails, the function may still succeed. Selftest + errors are returned later when invoking `gpgme_new', so that a + detailed error code can be returned (historically, + `gpgme_check_version' does not return a detailed error code). + + After initializing GPGME, you should set the locale information to +the locale required for your output terminal. This locale information +is needed for example for the curses and Gtk pinentry. Here is an +example of a complete initialization: + + #include <locale.h> + #include <gpgme.h> + + void + init_gpgme (void) + { + /* Initialize the locale environment. */ + setlocale (LC_ALL, ""); + gpgme_check_version (NULL); + gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL)); + #ifdef LC_MESSAGES + gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL)); + #endif + } + + Note that you are highly recommended to initialize the locale +settings like this. GPGME can not do this for you because it would not +be thread safe. The conditional on LC_MESSAGES is only necessary for +portability to W32 systems. + + +File: gpgme.info, Node: Signal Handling, Next: Multi Threading, Prev: Library Version Check, Up: Preparation + +2.7 Signal Handling +=================== + +The GPGME library communicates with child processes (the crypto +engines). If a child process dies unexpectedly, for example due to a +bug, or system problem, a `SIGPIPE' signal will be delivered to the +application. The default action is to abort the program. To protect +against this, `gpgme_check_version' sets the `SIGPIPE' signal action to +`SIG_IGN', which means that the signal will be ignored. + + GPGME will only do that if the signal action for `SIGPIPE' is +`SIG_DEF' at the time `gpgme_check_version' is called. If it is +something different, `GPGME' will take no action. + + This means that if your application does not install any signal +handler for `SIGPIPE', you don't need to take any precautions. If you +do install a signal handler for `SIGPIPE', you must be prepared to +handle any `SIGPIPE' events that occur due to GPGME writing to a +defunct pipe. Furthermore, if your application is multi-threaded, and +you install a signal action for `SIGPIPE', you must make sure you do +this either before `gpgme_check_version' is called or afterwards. + + +File: gpgme.info, Node: Multi Threading, Prev: Signal Handling, Up: Preparation + +2.8 Multi Threading +=================== + +The GPGME library is not entirely thread-safe, but it can still be used +in a multi-threaded environment if some care is taken. If the +following requirements are met, there should be no race conditions to +worry about: + + * GPGME supports the thread libraries pthread and GNU Pth. The + support for this has to be enabled at compile time. GPGME will + automatically detect the location in which the thread libraries + are installed and activate the support for them at build time. + + Support for other thread libraries is very easy to add. Please + contact us if you have the need. + + * If you want to use GPGME with threads, you must link to the right + version of the library. The name of the right library is + `libgpgme-' followed by the name of the thread package you use. + For example, if you use GNU Pth, the right name is `libgpgme-pth'. + Use the Automake macros or `gpgme-config' program for simplicity. + + * The function `gpgme_check_version' must be called before any other + function in the library, because it initializes the thread support + subsystem in GPGME. To achieve this in multi-threaded programs, + you must synchronize the memory with respect to other threads that + also want to use GPGME. For this, it is sufficient to call + `gpgme_check_version' before creating the other threads using + GPGME(1). + + * Any `gpgme_data_t' and `gpgme_ctx_t' object must only be accessed + by one thread at a time. If multiple threads want to deal with + the same object, the caller has to make sure that operations on + that object are fully synchronized. + + * Only one thread at any time is allowed to call `gpgme_wait'. If + multiple threads call this function, the caller must make sure that + all invocations are fully synchronized. It is safe to start + asynchronous operations while a thread is running in gpgme_wait. + + * The function `gpgme_strerror' is not thread safe. You have to use + `gpgme_strerror_r' instead. + + ---------- Footnotes ---------- + + (1) At least this is true for POSIX threads, as `pthread_create' is +a function that synchronizes memory with respects to other threads. +There are many functions which have this property, a complete list can +be found in POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in +the definition of the term "Memory Synchronization". For other thread +packages other, more relaxed or more strict rules may apply. + + +File: gpgme.info, Node: Protocols and Engines, Next: Algorithms, Prev: Preparation, Up: Top + +3 Protocols and Engines +*********************** + +GPGME supports several cryptographic protocols, however, it does not +implement them. Rather it uses backends (also called engines) which +implement the protocol. GPGME uses inter-process communication to pass +data back and forth between the application and the backend, but the +details of the communication protocol and invocation of the backend is +completely hidden by the interface. All complexity is handled by +GPGME. Where an exchange of information between the application and +the backend is necessary, GPGME provides the necessary callback function +hooks and further interfaces. + + -- Data type: enum gpgme_protocol_t + The `gpgme_protocol_t' type specifies the set of possible protocol + values that are supported by GPGME. The following protocols are + supported: + + `GPGME_PROTOCOL_OpenPGP' + This specifies the OpenPGP protocol. + + `GPGME_PROTOCOL_CMS' + This specifies the Cryptographic Message Syntax. + + `GPGME_PROTOCOL_ASSUAN' + Under development. Please ask on <gnupg-devel@gnupg.org> for + help. + + `GPGME_PROTOCOL_G13' + Under development. Please ask on <gnupg-devel@gnupg.org> for + help. + + `GPGME_PROTOCOL_UISERVER' + Under development. Please ask on <gnupg-devel@gnupg.org> for + help. + + `GPGME_PROTOCOL_UNKNOWN' + Reserved for future extension. You may use this to indicate + that the used protocol is not known to the application. + Currently, GPGME does not accept this value in any operation, + though, except for `gpgme_get_protocol_name'. + + -- Function: const char * gpgme_get_protocol_name + (gpgme_protocol_t PROTOCOL) + The function `gpgme_get_protocol_name' returns a statically + allocated string describing the protocol PROTOCOL, or `NULL' if + the protocol number is not valid. + +* Menu: + +* Engine Version Check:: Verifying the engine version. +* Engine Information:: Obtaining more information about the engines. +* Engine Configuration:: Changing the engine configuration. +* OpenPGP:: Support for the OpenPGP protocol. +* Cryptographic Message Syntax:: Support for the CMS. + + +File: gpgme.info, Node: Engine Version Check, Next: Engine Information, Up: Protocols and Engines + +3.1 Engine Version Check +======================== + + -- Function: gpgme_error_t gpgme_engine_check_version + (gpgme_protocol_t PROTOCOL) + The function `gpgme_engine_check_version' verifies that the engine + implementing the protocol PROTOCOL is installed in the expected + path and meets the version requirement of GPGME. + + This function returns the error code `GPG_ERR_NO_ERROR' if the + engine is available and `GPG_ERR_INV_ENGINE' if it is not. + + +File: gpgme.info, Node: Engine Information, Next: Engine Configuration, Prev: Engine Version Check, Up: Protocols and Engines + +3.2 Engine Information +====================== + + -- Data type: gpgme_engine_info_t + The `gpgme_engine_info_t' type specifies a pointer to a structure + describing a crypto engine. The structure contains the following + elements: + + `gpgme_engine_info_t next' + This is a pointer to the next engine info structure in the + linked list, or `NULL' if this is the last element. + + `gpgme_protocol_t protocol' + This is the protocol for which the crypto engine is used. + You can convert this to a string with + `gpgme_get_protocol_name' for printing. + + `const char *file_name' + This is a string holding the file name of the executable of + the crypto engine. Currently, it is never `NULL', but using + `NULL' is reserved for future use, so always check before you + use it. + + `const char *home_dir' + This is a string holding the directory name of the crypto + engine's configuration directory. If it is `NULL', then the + default directory is used. + + `const char *version' + This is a string containing the version number of the crypto + engine. It might be `NULL' if the version number can not be + determined, for example because the executable doesn't exist + or is invalid. + + `const char *req_version' + This is a string containing the minimum required version + number of the crypto engine for GPGME to work correctly. + This is the version number that `gpgme_engine_check_version' + verifies against. Currently, it is never `NULL', but using + `NULL' is reserved for future use, so always check before you + use it. + + -- Function: gpgme_error_t gpgme_get_engine_info + (gpgme_engine_info_t *INFO) + The function `gpgme_get_engine_info' returns a linked list of + engine info structures in INFO. Each info structure describes the + defaults of one configured backend. + + The memory for the info structures is allocated the first time this + function is invoked, and must not be freed by the caller. + + This function returns the error code `GPG_ERR_NO_ERROR' if + successful, and a system error if the memory could not be + allocated. + + Here is an example how you can provide more diagnostics if you +receive an error message which indicates that the crypto engine is +invalid. + + gpgme_ctx_t ctx; + gpgme_error_t err; + + [...] + + if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE) + { + gpgme_engine_info_t info; + err = gpgme_get_engine_info (&info); + if (!err) + { + while (info && info->protocol != gpgme_get_protocol (ctx)) + info = info->next; + if (!info) + fprintf (stderr, "GPGME compiled without support for protocol %s", + gpgme_get_protocol_name (info->protocol)); + else if (info->file_name && !info->version) + fprintf (stderr, "Engine %s not installed properly", + info->file_name); + else if (info->file_name && info->version && info->req_version) + fprintf (stderr, "Engine %s version %s installed, " + "but at least version %s required", info->file_name, + info->version, info->req_version); + else + fprintf (stderr, "Unknown problem with engine for protocol %s", + gpgme_get_protocol_name (info->protocol)); + } + } + + +File: gpgme.info, Node: Engine Configuration, Next: OpenPGP, Prev: Engine Information, Up: Protocols and Engines + +3.3 Engine Configuration +======================== + +You can change the configuration of a backend engine, and thus change +the executable program and configuration directory to be used. You can +make these changes the default or set them for some contexts +individually. + + -- Function: gpgme_error_t gpgme_set_engine_info + (gpgme_protocol_t PROTO, const char *FILE_NAME, + const char *HOME_DIR) + The function `gpgme_set_engine_info' changes the default + configuration of the crypto engine implementing the protocol PROTO. + + FILE_NAME is the file name of the executable program implementing + this protocol, and HOME_DIR is the directory name of the + configuration directory for this crypto engine. If HOME_DIR is + `NULL', the engine's default will be used. + + The new defaults are not applied to already created GPGME contexts. + + This function returns the error code `GPG_ERR_NO_ERROR' if + successful, or an eror code on failure. + + The functions `gpgme_ctx_get_engine_info' and +`gpgme_ctx_set_engine_info' can be used to change the engine +configuration per context. *Note Crypto Engine::. + + +File: gpgme.info, Node: OpenPGP, Next: Cryptographic Message Syntax, Prev: Engine Configuration, Up: Protocols and Engines + +3.4 OpenPGP +=========== + +OpenPGP is implemented by GnuPG, the GNU Privacy Guard. This is the +first protocol that was supported by GPGME. + + The OpenPGP protocol is specified by `GPGME_PROTOCOL_OpenPGP'. + + +File: gpgme.info, Node: Cryptographic Message Syntax, Prev: OpenPGP, Up: Protocols and Engines + +3.5 Cryptographic Message Syntax +================================ + +CMS is implemented by GpgSM, the S/MIME implementation for GnuPG. + + The CMS protocol is specified by `GPGME_PROTOCOL_CMS'. + + +File: gpgme.info, Node: Algorithms, Next: Error Handling, Prev: Protocols and Engines, Up: Top + +4 Algorithms +************ + +The crypto backends support a variety of algorithms used in public key +cryptography.(1) The following sections list the identifiers used to +denote such an algorithm. + +* Menu: + +* Public Key Algorithms:: A list of all public key algorithms. +* Hash Algorithms:: A list of all hash algorithms. + + ---------- Footnotes ---------- + + (1) Some engines also provide symmetric only encryption; see the +description of the encryption function on how to use this. + + +File: gpgme.info, Node: Public Key Algorithms, Next: Hash Algorithms, Up: Algorithms + +4.1 Public Key Algorithms +========================= + +Public key algorithms are used for encryption, decryption, signing and +verification of signatures. + + -- Data type: enum gpgme_pubkey_algo_t + The `gpgme_pubkey_algo_t' type specifies the set of all public key + algorithms that are supported by GPGME. Possible values are: + + `GPGME_PK_RSA' + This value indicates the RSA (Rivest, Shamir, Adleman) + algorithm. + + `GPGME_PK_RSA_E' + Deprecated. This value indicates the RSA (Rivest, Shamir, + Adleman) algorithm for encryption and decryption only. + + `GPGME_PK_RSA_S' + Deprecated. This value indicates the RSA (Rivest, Shamir, + Adleman) algorithm for signing and verification only. + + `GPGME_PK_DSA' + This value indicates DSA, the Digital Signature Algorithm. + + `GPGME_PK_ELG' + This value indicates ElGamal. + + `GPGME_PK_ELG_E' + This value also indicates ElGamal and is used specifically in + GnuPG. + + `GPGME_PK_ELG_E' + This value also indicates ElGamal and is used specifically in + GnuPG. + + `GPGME_PK_ECDSA' + This value indicates ECDSA, the Elliptic Curve Digital + Signature Algorithm as defined by FIPS 186-2. + + `GPGME_PK_ECDH' + This value indicates ECDH, the Eliptic Curve Diffie-Hellmann + encryption algorithm as defined by the ECC in OpenPGP draft. + + + -- Function: const char * gpgme_pubkey_algo_name + (gpgme_pubkey_algo_t ALGO) + The function `gpgme_pubkey_algo_name' returns a pointer to a + statically allocated string containing a description of the public + key algorithm ALGO. This string can be used to output the name of + the public key algorithm to the user. + + If ALGO is not a valid public key algorithm, `NULL' is returned. + + +File: gpgme.info, Node: Hash Algorithms, Prev: Public Key Algorithms, Up: Algorithms + +4.2 Hash Algorithms +=================== + +Hash (message digest) algorithms are used to compress a long message to +make it suitable for public key cryptography. + + -- Data type: enum gpgme_hash_algo_t + The `gpgme_hash_algo_t' type specifies the set of all hash + algorithms that are supported by GPGME. Possible values are: + + `GPGME_MD_MD5' + + `GPGME_MD_SHA1' + + `GPGME_MD_RMD160' + + `GPGME_MD_MD2' + + `GPGME_MD_TIGER' + + `GPGME_MD_HAVAL' + + `GPGME_MD_SHA256' + + `GPGME_MD_SHA384' + + `GPGME_MD_SHA512' + + `GPGME_MD_MD4' + + `GPGME_MD_CRC32' + + `GPGME_MD_CRC32_RFC1510' + + `GPGME_MD_CRC24_RFC2440' + + -- Function: const char * gpgme_hash_algo_name (gpgme_hash_algo_t ALGO) + The function `gpgme_hash_algo_name' returns a pointer to a + statically allocated string containing a description of the hash + algorithm ALGO. This string can be used to output the name of the + hash algorithm to the user. + + If ALGO is not a valid hash algorithm, `NULL' is returned. + + +File: gpgme.info, Node: Error Handling, Next: Exchanging Data, Prev: Algorithms, Up: Top + +5 Error Handling +**************** + +Many functions in GPGME can return an error if they fail. For this +reason, the application should always catch the error condition and +take appropriate measures, for example by releasing the resources and +passing the error up to the caller, or by displaying a descriptive +message to the user and cancelling the operation. + + Some error values do not indicate a system error or an error in the +operation, but the result of an operation that failed properly. For +example, if you try to decrypt a tempered message, the decryption will +fail. Another error value actually means that the end of a data buffer +or list has been reached. The following descriptions explain for many +error codes what they mean usually. Some error values have specific +meanings if returned by a certain functions. Such cases are described +in the documentation of those functions. + + GPGME uses the `libgpg-error' library. This allows to share the +error codes with other components of the GnuPG system, and thus pass +error values transparently from the crypto engine, or some helper +application of the crypto engine, to the user. This way no information +is lost. As a consequence, GPGME does not use its own identifiers for +error codes, but uses those provided by `libgpg-error'. They usually +start with `GPG_ERR_'. + + However, GPGME does provide aliases for the functions defined in +libgpg-error, which might be preferred for name space consistency. + +* Menu: + +* Error Values:: The error value and what it means. +* Error Sources:: A list of important error sources. +* Error Codes:: A list of important error codes. +* Error Strings:: How to get a descriptive string from a value. + + +File: gpgme.info, Node: Error Values, Next: Error Sources, Up: Error Handling + +5.1 Error Values +================ + + -- Data type: gpgme_err_code_t + The `gpgme_err_code_t' type is an alias for the `libgpg-error' + type `gpg_err_code_t'. The error code indicates the type of an + error, or the reason why an operation failed. + + A list of important error codes can be found in the next section. + + -- Data type: gpgme_err_source_t + The `gpgme_err_source_t' type is an alias for the `libgpg-error' + type `gpg_err_source_t'. The error source has not a precisely + defined meaning. Sometimes it is the place where the error + happened, sometimes it is the place where an error was encoded + into an error value. Usually the error source will give an + indication to where to look for the problem. This is not always + true, but it is attempted to achieve this goal. + + A list of important error sources can be found in the next section. + + -- Data type: gpgme_error_t + The `gpgme_error_t' type is an alias for the `libgpg-error' type + `gpg_error_t'. An error value like this has always two + components, an error code and an error source. Both together form + the error value. + + Thus, the error value can not be directly compared against an error + code, but the accessor functions described below must be used. + However, it is guaranteed that only 0 is used to indicate success + (`GPG_ERR_NO_ERROR'), and that in this case all other parts of the + error value are set to 0, too. + + Note that in GPGME, the error source is used purely for + diagnostical purposes. Only the error code should be checked to + test for a certain outcome of a function. The manual only + documents the error code part of an error value. The error source + is left unspecified and might be anything. + + -- Function: static inline gpgme_err_code_t gpgme_err_code + (gpgme_error_t ERR) + The static inline function `gpgme_err_code' returns the + `gpgme_err_code_t' component of the error value ERR. This + function must be used to extract the error code from an error + value in order to compare it with the `GPG_ERR_*' error code + macros. + + -- Function: static inline gpgme_err_source_t gpgme_err_source + (gpgme_error_t ERR) + The static inline function `gpgme_err_source' returns the + `gpgme_err_source_t' component of the error value ERR. This + function must be used to extract the error source from an error + value in order to compare it with the `GPG_ERR_SOURCE_*' error + source macros. + + -- Function: static inline gpgme_error_t gpgme_err_make + (gpgme_err_source_t SOURCE, gpgme_err_code_t CODE) + The static inline function `gpgme_err_make' returns the error + value consisting of the error source SOURCE and the error code + CODE. + + This function can be used in callback functions to construct an + error value to return it to the library. + + -- Function: static inline gpgme_error_t gpgme_error + (gpgme_err_code_t CODE) + The static inline function `gpgme_error' returns the error value + consisting of the default error source and the error code CODE. + + For GPGME applications, the default error source is + `GPG_ERR_SOURCE_USER_1'. You can define + `GPGME_ERR_SOURCE_DEFAULT' before including `gpgme.h' to change + this default. + + This function can be used in callback functions to construct an + error value to return it to the library. + + The `libgpg-error' library provides error codes for all system error +numbers it knows about. If ERR is an unknown error number, the error +code `GPG_ERR_UNKNOWN_ERRNO' is used. The following functions can be +used to construct error values from system errnor numbers. + + -- Function: gpgme_error_t gpgme_err_make_from_errno + (gpgme_err_source_t SOURCE, int ERR) + The function `gpgme_err_make_from_errno' is like `gpgme_err_make', + but it takes a system error like `errno' instead of a + `gpgme_err_code_t' error code. + + -- Function: gpgme_error_t gpgme_error_from_errno (int ERR) + The function `gpgme_error_from_errno' is like `gpgme_error', but + it takes a system error like `errno' instead of a + `gpgme_err_code_t' error code. + + Sometimes you might want to map system error numbers to error codes +directly, or map an error code representing a system error back to the +system error number. The following functions can be used to do that. + + -- Function: gpgme_err_code_t gpgme_err_code_from_errno (int ERR) + The function `gpgme_err_code_from_errno' returns the error code + for the system error ERR. If ERR is not a known system error, the + function returns `GPG_ERR_UNKNOWN_ERRNO'. + + -- Function: int gpgme_err_code_to_errno (gpgme_err_code_t ERR) + The function `gpgme_err_code_to_errno' returns the system error + for the error code ERR. If ERR is not an error code representing + a system error, or if this system error is not defined on this + system, the function returns `0'. + + +File: gpgme.info, Node: Error Sources, Next: Error Codes, Prev: Error Values, Up: Error Handling + +5.2 Error Sources +================= + +The library `libgpg-error' defines an error source for every component +of the GnuPG system. The error source part of an error value is not +well defined. As such it is mainly useful to improve the diagnostic +error message for the user. + + If the error code part of an error value is `0', the whole error +value will be `0'. In this case the error source part is of course +`GPG_ERR_SOURCE_UNKNOWN'. + + The list of error sources that might occur in applications using +GPGME is: + +`GPG_ERR_SOURCE_UNKNOWN' + The error source is not known. The value of this error source is + `0'. + +`GPG_ERR_SOURCE_GPGME' + The error source is GPGME itself. This is the default for errors + that occur in the GPGME library. + +`GPG_ERR_SOURCE_GPG' + The error source is GnuPG, which is the crypto engine used for the + OpenPGP protocol. + +`GPG_ERR_SOURCE_GPGSM' + The error source is GPGSM, which is the crypto engine used for the + CMS protocol. + +`GPG_ERR_SOURCE_GCRYPT' + The error source is `libgcrypt', which is used by crypto engines + to perform cryptographic operations. + +`GPG_ERR_SOURCE_GPGAGENT' + The error source is `gpg-agent', which is used by crypto engines + to perform operations with the secret key. + +`GPG_ERR_SOURCE_PINENTRY' + The error source is `pinentry', which is used by `gpg-agent' to + query the passphrase to unlock a secret key. + +`GPG_ERR_SOURCE_SCD' + The error source is the SmartCard Daemon, which is used by + `gpg-agent' to delegate operations with the secret key to a + SmartCard. + +`GPG_ERR_SOURCE_KEYBOX' + The error source is `libkbx', a library used by the crypto engines + to manage local keyrings. + +`GPG_ERR_SOURCE_USER_1' + +`GPG_ERR_SOURCE_USER_2' + +`GPG_ERR_SOURCE_USER_3' + +`GPG_ERR_SOURCE_USER_4' + These error sources are not used by any GnuPG component and can be + used by other software. For example, applications using GPGME can + use them to mark error values coming from callback handlers. Thus + `GPG_ERR_SOURCE_USER_1' is the default for errors created with + `gpgme_error' and `gpgme_error_from_errno', unless you define + `GPGME_ERR_SOURCE_DEFAULT' before including `gpgme.h'. + + +File: gpgme.info, Node: Error Codes, Next: Error Strings, Prev: Error Sources, Up: Error Handling + +5.3 Error Codes +=============== + +The library `libgpg-error' defines many error values. Most of them are +not used by `GPGME' directly, but might be returned by GPGME because it +received them from the crypto engine. The below list only includes +such error codes that have a specific meaning in `GPGME', or which are +so common that you should know about them. + +`GPG_ERR_EOF' + This value indicates the end of a list, buffer or file. + +`GPG_ERR_NO_ERROR' + This value indicates success. The value of this error code is + `0'. Also, it is guaranteed that an error value made from the + error code `0' will be `0' itself (as a whole). This means that + the error source information is lost for this error code, however, + as this error code indicates that no error occured, this is + generally not a problem. + +`GPG_ERR_GENERAL' + This value means that something went wrong, but either there is not + enough information about the problem to return a more useful error + value, or there is no separate error value for this type of + problem. + +`GPG_ERR_ENOMEM' + This value means that an out-of-memory condition occurred. + +`GPG_ERR_E...' + System errors are mapped to GPG_ERR_FOO where FOO is the symbol for + the system error. + +`GPG_ERR_INV_VALUE' + This value means that some user provided data was out of range. + This can also refer to objects. For example, if an empty + `gpgme_data_t' object was expected, but one containing data was + provided, this error value is returned. + +`GPG_ERR_UNUSABLE_PUBKEY' + This value means that some recipients for a message were invalid. + +`GPG_ERR_UNUSABLE_SECKEY' + This value means that some signers were invalid. + +`GPG_ERR_NO_DATA' + This value means that a `gpgme_data_t' object which was expected + to have content was found empty. + +`GPG_ERR_CONFLICT' + This value means that a conflict of some sort occurred. + +`GPG_ERR_NOT_IMPLEMENTED' + This value indicates that the specific function (or operation) is + not implemented. This error should never happen. It can only + occur if you use certain values or configuration options which do + not work, but for which we think that they should work at some + later time. + +`GPG_ERR_DECRYPT_FAILED' + This value indicates that a decryption operation was unsuccessful. + +`GPG_ERR_BAD_PASSPHRASE' + This value means that the user did not provide a correct passphrase + when requested. + +`GPG_ERR_CANCELED' + This value means that the operation was canceled. + +`GPG_ERR_INV_ENGINE' + This value means that the engine that implements the desired + protocol is currently not available. This can either be because + the sources were configured to exclude support for this engine, or + because the engine is not installed properly. + +`GPG_ERR_AMBIGUOUS_NAME' + This value indicates that a user ID or other specifier did not + specify a unique key. + +`GPG_ERR_WRONG_KEY_USAGE' + This value indicates that a key is not used appropriately. + +`GPG_ERR_CERT_REVOKED' + This value indicates that a key signature was revoced. + +`GPG_ERR_CERT_EXPIRED' + This value indicates that a key signature expired. + +`GPG_ERR_NO_CRL_KNOWN' + This value indicates that no certificate revocation list is known + for the certificate. + +`GPG_ERR_NO_POLICY_MATCH' + This value indicates that a policy issue occured. + +`GPG_ERR_NO_SECKEY' + This value indicates that no secret key for the user ID is + available. + +`GPG_ERR_MISSING_CERT' + This value indicates that a key could not be imported because the + issuer certificate is missing. + +`GPG_ERR_BAD_CERT_CHAIN' + This value indicates that a key could not be imported because its + certificate chain is not good, for example it could be too long. + +`GPG_ERR_UNSUPPORTED_ALGORITHM' + This value means a verification failed because the cryptographic + algorithm is not supported by the crypto backend. + +`GPG_ERR_BAD_SIGNATURE' + This value means a verification failed because the signature is + bad. + +`GPG_ERR_NO_PUBKEY' + This value means a verification failed because the public key is + not available. + +`GPG_ERR_USER_1' + +`GPG_ERR_USER_2' + +`...' + +`GPG_ERR_USER_16' + These error codes are not used by any GnuPG component and can be + freely used by other software. Applications using GPGME might use + them to mark specific errors returned by callback handlers if no + suitable error codes (including the system errors) for these + errors exist already. + + +File: gpgme.info, Node: Error Strings, Prev: Error Codes, Up: Error Handling + +5.4 Error Strings +================= + + -- Function: const char * gpgme_strerror (gpgme_error_t ERR) + The function `gpgme_strerror' returns a pointer to a statically + allocated string containing a description of the error code + contained in the error value ERR. This string can be used to + output a diagnostic message to the user. + + This function is not thread safe. Use `gpgme_strerror_r' in + multi-threaded programs. + + -- Function: int gpgme_strerror_r (gpgme_error_t ERR, char *BUF, + size_t BUFLEN) + The function `gpgme_strerror_r' returns the error string for ERR + in the user-supplied buffer BUF of size BUFLEN. This function is, + in contrast to `gpgme_strerror', thread-safe if a thread-safe + `strerror_r' function is provided by the system. If the function + succeeds, 0 is returned and BUF contains the string describing the + error. If the buffer was not large enough, ERANGE is returned and + BUF contains as much of the beginning of the error string as fits + into the buffer. + + -- Function: const char * gpgme_strsource (gpgme_error_t ERR) + The function `gpgme_strerror' returns a pointer to a statically + allocated string containing a description of the error source + contained in the error value ERR. This string can be used to + output a diagnostic message to the user. + + The following example illustrates the use of `gpgme_strerror': + + gpgme_ctx_t ctx; + gpgme_error_t err = gpgme_new (&ctx); + if (err) + { + fprintf (stderr, "%s: creating GpgME context failed: %s: %s\n", + argv[0], gpgme_strsource (err), gpgme_strerror (err)); + exit (1); + } + + +File: gpgme.info, Node: Exchanging Data, Next: Contexts, Prev: Error Handling, Up: Top + +6 Exchanging Data +***************** + +A lot of data has to be exchanged between the user and the crypto +engine, like plaintext messages, ciphertext, signatures and information +about the keys. The technical details about exchanging the data +information are completely abstracted by GPGME. The user provides and +receives the data via `gpgme_data_t' objects, regardless of the +communication protocol between GPGME and the crypto engine in use. + + -- Data type: gpgme_data_t + The `gpgme_data_t' type is a handle for a container for generic + data, which is used by GPGME to exchange data with the user. + + `gpgme_data_t' objects do not provide notifications on events. It +is assumed that read and write operations are blocking until data is +available. If this is undesirable, the application must ensure that +all GPGME data operations always have data available, for example by +using memory buffers or files rather than pipes or sockets. This might +be relevant, for example, if the external event loop mechanism is used. + +* Menu: + +* Creating Data Buffers:: Creating new data buffers. +* Destroying Data Buffers:: Releasing data buffers. +* Manipulating Data Buffers:: Operations on data buffers. + + +File: gpgme.info, Node: Creating Data Buffers, Next: Destroying Data Buffers, Up: Exchanging Data + +6.1 Creating Data Buffers +========================= + +Data objects can be based on memory, files, or callback functions +provided by the user. Not all operations are supported by all objects. + +* Menu: + +* Memory Based Data Buffers:: Creating memory based data buffers. +* File Based Data Buffers:: Creating file based data buffers. +* Callback Based Data Buffers:: Creating callback based data buffers. + + +File: gpgme.info, Node: Memory Based Data Buffers, Next: File Based Data Buffers, Up: Creating Data Buffers + +6.1.1 Memory Based Data Buffers +------------------------------- + +Memory based data objects store all data in allocated memory. This is +convenient, but only practical for an amount of data that is a fraction +of the available physical memory. The data has to be copied from its +source and to its destination, which can often be avoided by using one +of the other data object + + -- Function: gpgme_error_t gpgme_data_new (gpgme_data_t *DH) + The function `gpgme_data_new' creates a new `gpgme_data_t' object + and returns a handle for it in DH. The data object is memory + based and initially empty. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, `GPG_ERR_INV_VALUE' if DH is not + a valid pointer, and `GPG_ERR_ENOMEM' if not enough memory is + available. + + -- Function: gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *DH, + const char *BUFFER, size_t SIZE, int COPY) + The function `gpgme_data_new_from_mem' creates a new + `gpgme_data_t' object and fills it with SIZE bytes starting from + BUFFER. + + If COPY is not zero, a private copy of the data is made. If COPY + is zero, the data is taken from the specified buffer as needed, + and the user has to ensure that the buffer remains valid for the + whole life span of the data object. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, `GPG_ERR_INV_VALUE' if DH or + BUFFER is not a valid pointer, and `GPG_ERR_ENOMEM' if not enough + memory is available. + + -- Function: gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *DH, + const char *FILENAME, int COPY) + The function `gpgme_data_new_from_file' creates a new + `gpgme_data_t' object and fills it with the content of the file + FILENAME. + + If COPY is not zero, the whole file is read in at initialization + time and the file is not used anymore after that. This is the only + mode supported currently. Later, a value of zero for COPY might + cause all reads to be delayed until the data is needed, but this is + not yet implemented. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, `GPG_ERR_INV_VALUE' if DH or + FILENAME is not a valid pointer, `GPG_ERR_NOT_IMPLEMENTED' if CODE + is zero, and `GPG_ERR_ENOMEM' if not enough memory is available. + + -- Function: gpgme_error_t gpgme_data_new_from_filepart + (gpgme_data_t *DH, const char *FILENAME, FILE *FP, + off_t OFFSET, size_t LENGTH) + The function `gpgme_data_new_from_filepart' creates a new + `gpgme_data_t' object and fills it with a part of the file + specified by FILENAME or FP. + + Exactly one of FILENAME and FP must be non-zero, the other must be + zero. The argument that is not zero specifies the file from which + LENGTH bytes are read into the data object, starting from OFFSET. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, `GPG_ERR_INV_VALUE' if DH and + exactly one of FILENAME and FP is not a valid pointer, and + `GPG_ERR_ENOMEM' if not enough memory is available. + + +File: gpgme.info, Node: File Based Data Buffers, Next: Callback Based Data Buffers, Prev: Memory Based Data Buffers, Up: Creating Data Buffers + +6.1.2 File Based Data Buffers +----------------------------- + +File based data objects operate directly on file descriptors or +streams. Only a small amount of data is stored in core at any time, so +the size of the data objects is not limited by GPGME. + + -- Function: gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *DH, + int FD) + The function `gpgme_data_new_from_fd' creates a new `gpgme_data_t' + object and uses the file descriptor FD to read from (if used as an + input data object) and write to (if used as an output data object). + + When using the data object as an input buffer, the function might + read a bit more from the file descriptor than is actually needed + by the crypto engine in the desired operation because of internal + buffering. + + Note that GPGME assumes that the file descriptor is set to blocking + mode. Errors during I/O operations, except for EINTR, are usually + fatal for crypto operations. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, and `GPG_ERR_ENOMEM' if not + enough memory is available. + + -- Function: gpgme_error_t gpgme_data_new_from_stream + (gpgme_data_t *DH, FILE *STREAM) + The function `gpgme_data_new_from_stream' creates a new + `gpgme_data_t' object and uses the I/O stream STREAM to read from + (if used as an input data object) and write to (if used as an + output data object). + + When using the data object as an input buffer, the function might + read a bit more from the stream than is actually needed by the + crypto engine in the desired operation because of internal + buffering. + + Note that GPGME assumes that the stream is in blocking mode. + Errors during I/O operations, except for EINTR, are usually fatal + for crypto operations. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, and `GPG_ERR_ENOMEM' if not + enough memory is available. + + +File: gpgme.info, Node: Callback Based Data Buffers, Prev: File Based Data Buffers, Up: Creating Data Buffers + +6.1.3 Callback Based Data Buffers +--------------------------------- + +If neither memory nor file based data objects are a good fit for your +application, you can implement the functions a data object provides +yourself and create a data object from these callback functions. + + -- Data type: ssize_t (*gpgme_data_read_cb_t) (void *HANDLE, +void *BUFFER, size_t SIZE) + The `gpgme_data_read_cb_t' type is the type of functions which + GPGME calls if it wants to read data from a user-implemented data + object. The function should read up to SIZE bytes from the + current read position into the space starting at BUFFER. The + HANDLE is provided by the user at data object creation time. + + Note that GPGME assumes that the read blocks until data is + available. Errors during I/O operations, except for EINTR, are + usually fatal for crypto operations. + + The function should return the number of bytes read, 0 on EOF, and + -1 on error. If an error occurs, ERRNO should be set to describe + the type of the error. + + -- Data type: ssize_t (*gpgme_data_write_cb_t) (void *HANDLE, +const void *BUFFER, size_t SIZE) + The `gpgme_data_write_cb_t' type is the type of functions which + GPGME calls if it wants to write data to a user-implemented data + object. The function should write up to SIZE bytes to the current + write position from the space starting at BUFFER. The HANDLE is + provided by the user at data object creation time. + + Note that GPGME assumes that the write blocks until data is + available. Errors during I/O operations, except for EINTR, are + usually fatal for crypto operations. + + The function should return the number of bytes written, and -1 on + error. If an error occurs, ERRNO should be set to describe the + type of the error. + + -- Data type: off_t (*gpgme_data_seek_cb_t) (void *HANDLE, +off_t OFFSET, int WHENCE) + The `gpgme_data_seek_cb_t' type is the type of functions which + GPGME calls if it wants to change the current read/write position + in a user-implemented data object, just like the `lseek' function. + + The function should return the new read/write position, and -1 on + error. If an error occurs, ERRNO should be set to describe the + type of the error. + + -- Data type: void (*gpgme_data_release_cb_t) (void *HANDLE) + The `gpgme_data_release_cb_t' type is the type of functions which + GPGME calls if it wants to destroy a user-implemented data object. + The HANDLE is provided by the user at data object creation time. + + -- Data type: struct gpgme_data_cbs + This structure is used to store the data callback interface + functions described above. It has the following members: + + `gpgme_data_read_cb_t read' + This is the function called by GPGME to read data from the + data object. It is only required for input data object. + + `gpgme_data_write_cb_t write' + This is the function called by GPGME to write data to the + data object. It is only required for output data object. + + `gpgme_data_seek_cb_t seek' + This is the function called by GPGME to change the current + read/write pointer in the data object (if available). It is + optional. + + `gpgme_data_release_cb_t release' + This is the function called by GPGME to release a data + object. It is optional. + + -- Function: gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *DH, + gpgme_data_cbs_t CBS, void *HANDLE) + The function `gpgme_data_new_from_cbs' creates a new + `gpgme_data_t' object and uses the user-provided callback functions + to operate on the data object. + + The handle HANDLE is passed as first argument to the callback + functions. This can be used to identify this data object. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, and `GPG_ERR_ENOMEM' if not + enough memory is available. + + The following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of GPGME. + + -- Function: gpgme_error_t gpgme_data_new_with_read_cb + (gpgme_data_t *DH, int (*READFUNC) (void *HOOK, char *BUFFER, + size_t COUNT, size_t *NREAD), void *HOOK_VALUE) + The function `gpgme_data_new_with_read_cb' creates a new + `gpgme_data_t' object and uses the callback function READFUNC to + retrieve the data on demand. As the callback function can supply + the data in any way it wants, this is the most flexible data type + GPGME provides. However, it can not be used to write data. + + The callback function receives HOOK_VALUE as its first argument + whenever it is invoked. It should return up to COUNT bytes in + BUFFER, and return the number of bytes actually read in NREAD. It + may return `0' in NREAD if no data is currently available. To + indicate `EOF' the function should return with an error code of + `-1' and set NREAD to `0'. The callback function may support to + reset its internal read pointer if it is invoked with BUFFER and + NREAD being `NULL' and COUNT being `0'. + + The function returns the error code `GPG_ERR_NO_ERROR' if the data + object was successfully created, `GPG_ERR_INV_VALUE' if DH or + READFUNC is not a valid pointer, and `GPG_ERR_ENOMEM' if not + enough memory is available. + + +File: gpgme.info, Node: Destroying Data Buffers, Next: Manipulating Data Buffers, Prev: Creating Data Buffers, Up: Exchanging Data + +6.2 Destroying Data Buffers +=========================== + + -- Function: void gpgme_data_release (gpgme_data_t DH) + The function `gpgme_data_release' destroys the data object with + the handle DH. It releases all associated resources that were not + provided by the user in the first place. + + -- Function: char * gpgme_data_release_and_get_mem (gpgme_data_t DH, + size_t *LENGTH) + The function `gpgme_data_release_and_get_mem' is like + `gpgme_data_release', except that it returns the data buffer and + its length that was provided by the object. + + The user has to release the buffer with `gpgme_free'. In case the + user provided the data buffer in non-copy mode, a copy will be + made for this purpose. + + In case an error returns, or there is no suitable data buffer that + can be returned to the user, the function will return `NULL'. In + any case, the data object DH is destroyed. + + -- Function: void gpgme_free (void *BUFFER) + The function `gpgme_free' releases the memory returned by + `gpgme_data_release_and_get_mem'. It should be used instead of + the system libraries `free' function in case different allocators + are used in a single program. + + +File: gpgme.info, Node: Manipulating Data Buffers, Prev: Destroying Data Buffers, Up: Exchanging Data + +6.3 Manipulating Data Buffers +============================= + +Data buffers contain data and meta-data. The following operations can +be used to manipulate both. + +* Menu: + +* Data Buffer I/O Operations:: I/O operations on data buffers. +* Data Buffer Meta-Data:: Meta-data manipulation of data buffers. + + +File: gpgme.info, Node: Data Buffer I/O Operations, Next: Data Buffer Meta-Data, Up: Manipulating Data Buffers + +6.3.1 Data Buffer I/O Operations +-------------------------------- + + -- Function: ssize_t gpgme_data_read (gpgme_data_t DH, void *BUFFER, + size_t LENGTH) + The function `gpgme_data_read' reads up to LENGTH bytes from the + data object with the handle DH into the space starting at BUFFER. + + If no error occurs, the actual amount read is returned. If the + end of the data object is reached, the function returns 0. + + In all other cases, the function returns -1 and sets ERRNO. + + -- Function: ssize_t gpgme_data_write (gpgme_data_t DH, + const void *BUFFER, size_t SIZE) + The function `gpgme_data_write' writes up to SIZE bytes starting + from BUFFER into the data object with the handle DH at the current + write position. + + The function returns the number of bytes actually written, or -1 + if an error occurs. If an error occurs, ERRNO is set. + + -- Function: off_t gpgme_data_seek (gpgme_data_t DH, off_t OFFSET, + int WHENCE) + The function `gpgme_data_seek' changes the current read/write + position. + + The WHENCE argument specifies how the OFFSET should be + interpreted. It must be one of the following symbolic constants: + + `SEEK_SET' + Specifies that OFFSET is a count of characters from the + beginning of the data object. + + `SEEK_CUR' + Specifies that OFFSET is a count of characters from the + current file position. This count may be positive or + negative. + + `SEEK_END' + Specifies that OFFSET is a count of characters from the end of + the data object. A negative count specifies a position + within the current extent of the data object; a positive + count specifies a position past the current end. If you set + the position past the current end, and actually write data, + you will extend the data object with zeros up to that + position. + + If successful, the function returns the resulting file position, + measured in bytes from the beginning of the data object. You can + use this feature together with `SEEK_CUR' to read the current + read/write position. + + If the function fails, -1 is returned and ERRNO is set. + + The following function is deprecated and should not be used. It will +be removed in a future version of GPGME. + + -- Function: gpgme_error_t gpgme_data_rewind (gpgme_data_t DH) + The function `gpgme_data_rewind' is equivalent to: + + return (gpgme_data_seek (dh, 0, SEEK_SET) == -1) + ? gpgme_error_from_errno (errno) : 0; + + +File: gpgme.info, Node: Data Buffer Meta-Data, Prev: Data Buffer I/O Operations, Up: Manipulating Data Buffers + +6.3.2 Data Buffer Meta-Data +--------------------------- + + -- Function: char * gpgme_data_get_file_name (gpgme_data_t DH) + The function `gpgme_data_get_file_name' returns a pointer to a + string containing the file name associated with the data object. + The file name will be stored in the output when encrypting or + signing the data and will be returned to the user when decrypting + or verifying the output data. + + If no error occurs, the string containing the file name is + returned. Otherwise, `NULL' will be returned. + + -- Function: gpgme_error_t gpgme_data_set_file_name (gpgme_data_t DH, + const char *FILE_NAME) + The function `gpgme_data_set_file_name' sets the file name + associated with the data object. The file name will be stored in + the output when encrypting or signing the data and will be + returned to the user when decrypting or verifying the output data. + + The function returns the error code `GPG_ERR_INV_VALUE' if DH is + not a valid pointer and `GPG_ERR_ENOMEM' if not enough memory is + available. + + -- Data type: enum gpgme_data_encoding_t + The `gpgme_data_encoding_t' type specifies the encoding of a + `gpgme_data_t' object. For input data objects, the encoding is + useful to give the backend a hint on the type of data. For output + data objects, the encoding can specify the output data format on + certain operations. Please note that not all backends support all + encodings on all operations. The following data types are + available: + + `GPGME_DATA_ENCODING_NONE' + This specifies that the encoding is not known. This is the + default for a new data object. The backend will try its best + to detect the encoding automatically. + + `GPGME_DATA_ENCODING_BINARY' + This specifies that the data is encoding in binary form; i.e. + there is no special encoding. + + `GPGME_DATA_ENCODING_BASE64' + This specifies that the data is encoded using the Base-64 + encoding scheme as used by MIME and other protocols. + + `GPGME_DATA_ENCODING_ARMOR' + This specifies that the data is encoded in an armored form as + used by OpenPGP and PEM. + + `GPGME_DATA_ENCODING_URL' + The data is a list of linefeed delimited URLs. This is only + useful with `gpgme_op_import'. + + `GPGME_DATA_ENCODING_URL0' + The data is a list of binary zero delimited URLs. This is + only useful with `gpgme_op_import'. + + `GPGME_DATA_ENCODING_URLESC' + The data is a list of linefeed delimited URLs with all + control and space characters percent escaped. This mode is + is not yet implemented. + + + -- Function: gpgme_data_encoding_t gpgme_data_get_encoding + (gpgme_data_t DH) + The function `gpgme_data_get_encoding' returns the encoding of the + data object with the handle DH. If DH is not a valid pointer + (e.g. `NULL') `GPGME_DATA_ENCODING_NONE' is returned. + + -- Function: gpgme_error_t gpgme_data_set_encoding + (gpgme_data_t DH, gpgme_data_encoding_t ENC) + The function `gpgme_data_set_encoding' changes the encoding of the + data object with the handle DH to ENC. + + +File: gpgme.info, Node: Contexts, Next: UI Server Protocol, Prev: Exchanging Data, Up: Top + +7 Contexts +********** + +All cryptographic operations in GPGME are performed within a context, +which contains the internal state of the operation as well as +configuration parameters. By using several contexts you can run +several cryptographic operations in parallel, with different +configuration. + + -- Data type: gpgme_ctx_t + The `gpgme_ctx_t' type is a handle for a GPGME context, which is + used to hold the configuration, status and result of cryptographic + operations. + +* Menu: + +* Creating Contexts:: Creating new GPGME contexts. +* Destroying Contexts:: Releasing GPGME contexts. +* Result Management:: Managing the result of crypto operations. +* Context Attributes:: Setting properties of a context. +* Key Management:: Managing keys with GPGME. +* Trust Item Management:: Managing trust items with GPGME. +* Crypto Operations:: Using a context for cryptography. +* Run Control:: Controlling how operations are run. + + +File: gpgme.info, Node: Creating Contexts, Next: Destroying Contexts, Up: Contexts + +7.1 Creating Contexts +===================== + + -- Function: gpgme_error_t gpgme_new (gpgme_ctx_t *CTX) + The function `gpgme_new' creates a new `gpgme_ctx_t' object and + returns a handle for it in CTX. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + context was successfully created, `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and `GPG_ERR_ENOMEM' if not enough memory is + available. Also, it returns `GPG_ERR_NOT_OPERATIONAL' if + `gpgme_check_version' was not called to initialize GPGME, and + `GPG_ERR_SELFTEST_FAILED' if a selftest failed. Currently, the + only selftest is for Windows MingW32 targets to see if + `-mms-bitfields' was used (as required). + + +File: gpgme.info, Node: Destroying Contexts, Next: Result Management, Prev: Creating Contexts, Up: Contexts + +7.2 Destroying Contexts +======================= + + -- Function: void gpgme_release (gpgme_ctx_t CTX) + The function `gpgme_release' destroys the context with the handle + CTX and releases all associated resources. + + +File: gpgme.info, Node: Result Management, Next: Context Attributes, Prev: Destroying Contexts, Up: Contexts + +7.3 Result Management +===================== + +The detailed result of an operation is returned in operation-specific +structures such as `gpgme_decrypt_result_t'. The corresponding +retrieval functions such as `gpgme_op_decrypt_result' provide static +access to the results after an operation completes. The following +interfaces make it possible to detach a result structure from its +associated context and give it a lifetime beyond that of the current +operation or context. + + -- Function: void gpgme_result_ref (void *RESULT) + The function `gpgme_result_ref' acquires an additional reference + for the result RESULT, which may be of any type + `gpgme_*_result_t'. As long as the user holds a reference, the + result structure is guaranteed to be valid and unmodified. + + -- Function: void gpgme_result_unref (void *RESULT) + The function `gpgme_result_unref' releases a reference for the + result RESULT. If this was the last reference, the result + structure will be destroyed and all resources associated to it + will be released. + + Note that a context may hold its own references to result structures, +typically until the context is destroyed or the next operation is +started. In fact, these references are accessed through the +`gpgme_op_*_result' functions. + + +File: gpgme.info, Node: Context Attributes, Next: Key Management, Prev: Result Management, Up: Contexts + +7.4 Context Attributes +====================== + +* Menu: + +* Protocol Selection:: Selecting the protocol used by a context. +* Crypto Engine:: Configuring the crypto engine. +* ASCII Armor:: Requesting ASCII armored output. +* Text Mode:: Choosing canonical text mode. +* Included Certificates:: Including a number of certificates. +* Key Listing Mode:: Selecting key listing mode. +* Passphrase Callback:: Getting the passphrase from the user. +* Progress Meter Callback:: Being informed about the progress. +* Locale:: Setting the locale of a context. + + +File: gpgme.info, Node: Protocol Selection, Next: Crypto Engine, Up: Context Attributes + +7.4.1 Protocol Selection +------------------------ + + -- Function: gpgme_error_t gpgme_set_protocol (gpgme_ctx_t CTX, + gpgme_protocol_t PROTO) + The function `gpgme_set_protocol' sets the protocol used within + the context CTX to PROTO. All crypto operations will be performed + by the crypto engine configured for that protocol. *Note + Protocols and Engines::. + + Setting the protocol with `gpgme_set_protocol' does not check if + the crypto engine for that protocol is available and installed + correctly. *Note Engine Version Check::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + protocol could be set successfully, and `GPG_ERR_INV_VALUE' if + PROTOCOL is not a valid protocol. + + -- Function: gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t CTX) + The function `gpgme_get_protocol' retrieves the protocol currently + use with the context CTX. + + +File: gpgme.info, Node: Crypto Engine, Next: ASCII Armor, Prev: Protocol Selection, Up: Context Attributes + +7.4.2 Crypto Engine +------------------- + +The following functions can be used to set and retrieve the +configuration of the crypto engines of a specific context. The default +can also be retrieved without any particular context. *Note Engine +Information::. The default can also be changed globally. *Note Engine +Configuration::. + + -- Function: gpgme_engine_info_t gpgme_ctx_get_engine_info + (gpgme_ctx_t CTX) + The function `gpgme_ctx_get_engine_info' returns a linked list of + engine info structures. Each info structure describes the + configuration of one configured backend, as used by the context + CTX. + + The result is valid until the next invocation of + `gpgme_ctx_set_engine_info' for this particular context. + + This function can not fail. + + -- Function: gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t CTX, + gpgme_protocol_t PROTO, const char *FILE_NAME, + const char *HOME_DIR) + The function `gpgme_ctx_set_engine_info' changes the configuration + of the crypto engine implementing the protocol PROTO for the + context CTX. + + FILE_NAME is the file name of the executable program implementing + this protocol, and HOME_DIR is the directory name of the + configuration directory for this crypto engine. If HOME_DIR is + `NULL', the engine's default will be used. + + Currently this function must be used before starting the first + crypto operation. It is unspecified if and when the changes will + take effect if the function is called after starting the first + operation on the context CTX. + + This function returns the error code `GPG_ERR_NO_ERROR' if + successful, or an eror code on failure. + + +File: gpgme.info, Node: ASCII Armor, Next: Text Mode, Prev: Crypto Engine, Up: Context Attributes + +7.4.3 ASCII Armor +----------------- + + -- Function: void gpgme_set_armor (gpgme_ctx_t CTX, int YES) + The function `gpgme_set_armor' specifies if the output should be + ASCII armored. By default, output is not ASCII armored. + + ASCII armored output is disabled if YES is zero, and enabled + otherwise. + + -- Function: int gpgme_get_armor (gpgme_ctx_t CTX) + The function `gpgme_get_armor' returns 1 if the output is ASCII + armored, and `0' if it is not, or if CTX is not a valid pointer. + + +File: gpgme.info, Node: Text Mode, Next: Included Certificates, Prev: ASCII Armor, Up: Context Attributes + +7.4.4 Text Mode +--------------- + + -- Function: void gpgme_set_textmode (gpgme_ctx_t CTX, int YES) + The function `gpgme_set_textmode' specifies if canonical text mode + should be used. By default, text mode is not used. + + Text mode is for example used for the RFC2015 signatures; note that + the updated RFC 3156 mandates that the mail user agent does some + preparations so that text mode is not needed anymore. + + This option is only relevant to the OpenPGP crypto engine, and + ignored by all other engines. + + Canonical text mode is disabled if YES is zero, and enabled + otherwise. + + -- Function: int gpgme_get_textmode (gpgme_ctx_t CTX) + The function `gpgme_get_textmode' returns 1 if canonical text mode + is enabled, and `0' if it is not, or if CTX is not a valid pointer. + + +File: gpgme.info, Node: Included Certificates, Next: Key Listing Mode, Prev: Text Mode, Up: Context Attributes + +7.4.5 Included Certificates +--------------------------- + + -- Function: void gpgme_set_include_certs (gpgme_ctx_t CTX, + int NR_OF_CERTS) + The function `gpgme_set_include_certs' specifies how many + certificates should be included in an S/MIME signed message. By + default, only the sender's certificate is included. The possible + values of NR_OF_CERTS are: + + `GPGME_INCLUDE_CERTS_DEFAULT' + Fall back to the default of the crypto backend. This is the + default for GPGME. + + `-2' + Include all certificates except the root certificate. + + `-1' + Include all certificates. + + `0' + Include no certificates. + + `1' + Include the sender's certificate only. + + `n' + Include the first n certificates of the certificates path, + starting from the sender's certificate. The number `n' must + be positive. + + Values of NR_OF_CERTS smaller than -2 are undefined. + + This option is only relevant to the CMS crypto engine, and ignored + by all other engines. + + -- Function: int gpgme_get_include_certs (gpgme_ctx_t CTX) + The function `gpgme_get_include_certs' returns the number of + certificates to include into an S/MIME signed message. + + +File: gpgme.info, Node: Key Listing Mode, Next: Passphrase Callback, Prev: Included Certificates, Up: Context Attributes + +7.4.6 Key Listing Mode +---------------------- + + -- Function: gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t CTX, + gpgme_keylist_mode_t MODE) + The function `gpgme_set_keylist_mode' changes the default + behaviour of the key listing functions. The value in MODE is a + bitwise-or combination of one or multiple of the following bit + values: + + `GPGME_KEYLIST_MODE_LOCAL' + The `GPGME_KEYLIST_MODE_LOCAL' symbol specifies that the local + keyring should be searched for keys in the keylisting + operation. This is the default. + + `GPGME_KEYLIST_MODE_EXTERN' + The `GPGME_KEYLIST_MODE_EXTERN' symbol specifies that an + external source should be searched for keys in the keylisting + operation. The type of external source is dependant on the + crypto engine used and whether it is combined with + `GPGME_KEYLIST_MODE_LOCAL'. For example, it can be a remote + keyserver or LDAP certificate server. + + `GPGME_KEYLIST_MODE_SIGS' + The `GPGME_KEYLIST_MODE_SIGS' symbol specifies that the key + signatures should be included in the listed keys. + + `GPGME_KEYLIST_MODE_SIG_NOTATIONS' + The `GPGME_KEYLIST_MODE_SIG_NOTATIONS' symbol specifies that + the signature notations on key signatures should be included + in the listed keys. This only works if + `GPGME_KEYLIST_MODE_SIGS' is also enabled. + + `GPGME_KEYLIST_MODE_EPHEMERAL' + The `GPGME_KEYLIST_MODE_EPHEMERAL' symbol specifies that keys + flagged as ephemeral are included in the listing. + + `GPGME_KEYLIST_MODE_VALIDATE' + The `GPGME_KEYLIST_MODE_VALIDATE' symbol specifies that the + backend should do key or certificate validation and not just + get the validity information from an internal cache. This + might be an expensive operation and is in general not useful. + Currently only implemented for the S/MIME backend and ignored + for other backends. + + + At least one of `GPGME_KEYLIST_MODE_LOCAL' and + `GPGME_KEYLIST_MODE_EXTERN' must be specified. For future binary + compatibility, you should get the current mode with + `gpgme_get_keylist_mode' and modify it by setting or clearing the + appropriate bits, and then using that calculated value in the + `gpgme_set_keylisting_mode' operation. This will leave all other + bits in the mode value intact (in particular those that are not + used in the current version of the library). + + The function returns the error code `GPG_ERR_NO_ERROR' if the mode + could be set correctly, and `GPG_ERR_INV_VALUE' if CTX is not a + valid pointer or MODE is not a valid mode. + + -- Function: gpgme_keylist_mode_t gpgme_get_keylist_mode + (gpgme_ctx_t CTX) + The function `gpgme_get_keylist_mode' returns the current key + listing mode of the context CTX. This value can then be modified + and used in a subsequent `gpgme_set_keylist_mode' operation to + only affect the desired bits (and leave all others intact). + + The function returns 0 if CTX is not a valid pointer, and the + current mode otherwise. Note that 0 is not a valid mode value. + + +File: gpgme.info, Node: Passphrase Callback, Next: Progress Meter Callback, Prev: Key Listing Mode, Up: Context Attributes + +7.4.7 Passphrase Callback +------------------------- + + -- Data type: gpgme_error_t (*gpgme_passphrase_cb_t)(void *HOOK, const +char *UID_HINT, const char *PASSPHRASE_INFO, int PREV_WAS_BAD, int FD) + The `gpgme_passphrase_cb_t' type is the type of functions usable as + passphrase callback function. + + The argument UID_HINT might contain a string that gives an + indication for which user ID the passphrase is required. If this + is not available, or not applicable (in the case of symmetric + encryption, for example), UID_HINT will be `NULL'. + + The argument PASSPHRASE_INFO, if not `NULL', will give further + information about the context in which the passphrase is required. + This information is engine and operation specific. + + If this is the repeated attempt to get the passphrase, because + previous attempts failed, then PREV_WAS_BAD is 1, otherwise it + will be 0. + + The user must write the passphrase, followed by a newline + character, to the file descriptor FD. If the user returns 0 + indicating success, the user must at least write a newline + character before returning from the callback. + + If an error occurs, return the corresponding `gpgme_error_t' + value. You can use the error code `GPG_ERR_CANCELED' to abort the + operation. Otherwise, return `0'. + + -- Function: void gpgme_set_passphrase_cb (gpgme_ctx_t CTX, + gpgme_passphrase_cb_t PASSFUNC, void *HOOK_VALUE) + The function `gpgme_set_passphrase_cb' sets the function that is + used when a passphrase needs to be provided by the user to + PASSFUNC. The function PASSFUNC needs to implemented by the user, + and whenever it is called, it is called with its first argument + being HOOK_VALUE. By default, no passphrase callback function is + set. + + Not all crypto engines require this callback to retrieve the + passphrase. It is better if the engine retrieves the passphrase + from a trusted agent (a daemon process), rather than having each + user to implement their own passphrase query. Some engines do not + even support an external passphrase callback at all, in this case + the error code `GPG_ERR_NOT_SUPPORTED' is returned. + + The user can disable the use of a passphrase callback function by + calling `gpgme_set_passphrase_cb' with PASSFUNC being `NULL'. + + -- Function: void gpgme_get_passphrase_cb (gpgme_ctx_t CTX, + gpgme_passphrase_cb_t *PASSFUNC, void **HOOK_VALUE) + The function `gpgme_get_passphrase_cb' returns the function that + is used when a passphrase needs to be provided by the user in + *PASSFUNC, and the first argument for this function in + *HOOK_VALUE. If no passphrase callback is set, or CTX is not a + valid pointer, `NULL' is returned in both variables. + + PASSFUNC or HOOK_VALUE can be `NULL'. In this case, the + corresponding value will not be returned. + + +File: gpgme.info, Node: Progress Meter Callback, Next: Locale, Prev: Passphrase Callback, Up: Context Attributes + +7.4.8 Progress Meter Callback +----------------------------- + + -- Data type: void (*gpgme_progress_cb_t)(void *HOOK, const char +*WHAT, int TYPE, int CURRENT, int TOTAL) + The `gpgme_progress_cb_t' type is the type of functions usable as + progress callback function. + + The arguments are specific to the crypto engine. More information + about the progress information returned from the GnuPG engine can + be found in the GnuPG source code in the file `doc/DETAILS' in the + section PROGRESS. + + -- Function: void gpgme_set_progress_cb (gpgme_ctx_t CTX, + gpgme_progress_cb_t PROGFUNC, void *HOOK_VALUE) + The function `gpgme_set_progress_cb' sets the function that is + used when progress information about a cryptographic operation is + available. The function PROGFUNC needs to implemented by the + user, and whenever it is called, it is called with its first + argument being HOOK_VALUE. By default, no progress callback + function is set. + + Setting a callback function allows an interactive program to + display progress information about a long operation to the user. + + The user can disable the use of a progress callback function by + calling `gpgme_set_progress_cb' with PROGFUNC being `NULL'. + + -- Function: void gpgme_get_progress_cb (gpgme_ctx_t CTX, + gpgme_progress_cb_t *PROGFUNC, void **HOOK_VALUE) + The function `gpgme_get_progress_cb' returns the function that is + used to inform the user about the progress made in *PROGFUNC, and + the first argument for this function in *HOOK_VALUE. If no + progress callback is set, or CTX is not a valid pointer, `NULL' is + returned in both variables. + + PROGFUNC or HOOK_VALUE can be `NULL'. In this case, the + corresponding value will not be returned. + + +File: gpgme.info, Node: Locale, Prev: Progress Meter Callback, Up: Context Attributes + +7.4.9 Locale +------------ + +A locale setting can be associated with a context. This locale is +passed to the crypto engine, and used for applications like the PIN +entry, which is displayed to the user when entering a passphrase is +required. + + The default locale is used to initialize the locale setting of all +contexts created afterwards. + + -- Function: gpgme_error_t gpgme_set_locale (gpgme_ctx_t CTX, + int CATEGORY, const char *VALUE) + The function `gpgme_set_locale' sets the locale of the context + CTX, or the default locale if CTX is a null pointer. + + The locale settings that should be changed are specified by + CATEGORY. Supported categories are `LC_CTYPE', `LC_MESSAGES', and + `LC_ALL', which is a wildcard you can use if you want to change + all the categories at once. + + The value to be used for the locale setting is VALUE, which will + be copied to GPGME's internal data structures. VALUE can be a + null pointer, which disables setting the locale, and will make PIN + entry and other applications use their default setting, which is + usually not what you want. + + Note that the settings are only used if the application runs on a + text terminal, and that the settings should fit the configuration + of the output terminal. Normally, it is sufficient to initialize + the default value at startup. + + The function returns an error if not enough memory is available. + + +File: gpgme.info, Node: Key Management, Next: Trust Item Management, Prev: Context Attributes, Up: Contexts + +7.5 Key Management +================== + +Some of the cryptographic operations require that recipients or signers +are specified. This is always done by specifying the respective keys +that should be used for the operation. The following section describes +how such keys can be selected and manipulated. + + -- Data type: gpgme_sub_key_t + The `gpgme_sub_key_t' type is a pointer to a subkey structure. + Sub keys are one component of a `gpgme_key_t' object. In fact, + subkeys are those parts that contains the real information about + the individual cryptographic keys that belong to the same key + object. One `gpgme_key_t' can contain several subkeys. The first + subkey in the linked list is also called the primary key. + + The subkey structure has the following members: + + `gpgme_sub_key_t next' + This is a pointer to the next subkey structure in the linked + list, or `NULL' if this is the last element. + + `unsigned int revoked : 1' + This is true if the subkey is revoked. + + `unsigned int expired : 1' + This is true if the subkey is expired. + + `unsigned int disabled : 1' + This is true if the subkey is disabled. + + `unsigned int invalid : 1' + This is true if the subkey is invalid. + + `unsigned int can_encrypt : 1' + This is true if the subkey can be used for encryption. + + `unsigned int can_sign : 1' + This is true if the subkey can be used to create data + signatures. + + `unsigned int can_certify : 1' + This is true if the subkey can be used to create key + certificates. + + `unsigned int can_authenticate : 1' + This is true if the subkey can be used for authentication. + + `unsigned int is_qualified : 1' + This is true if the subkey can be used for qualified + signatures according to local government regulations. + + `unsigned int secret : 1' + This is true if the subkey is a secret key. Note that it + will be false if the key is actually a stub key; i.e. a + secret key operation is currently not possible (offline-key). + + `gpgme_pubkey_algo_t pubkey_algo' + This is the public key algorithm supported by this subkey. + + `unsigned int length' + This is the length of the subkey (in bits). + + `char *keyid' + This is the key ID of the subkey in hexadecimal digits. + + `char *fpr' + This is the fingerprint of the subkey in hexadecimal digits, + if available. + + `long int timestamp' + This is the creation timestamp of the subkey. This is -1 if + the timestamp is invalid, and 0 if it is not available. + + `long int expires' + This is the expiration timestamp of the subkey, or 0 if the + subkey does not expire. + + -- Data type: gpgme_key_sig_t + The `gpgme_key_sig_t' type is a pointer to a key signature + structure. Key signatures are one component of a `gpgme_key_t' + object, and validate user IDs on the key. + + The signatures on a key are only available if the key was retrieved + via a listing operation with the `GPGME_KEYLIST_MODE_SIGS' mode + enabled, because it can be expensive to retrieve all signatures of + a key. + + The signature notations on a key signature are only available if + the key was retrieved via a listing operation with the + `GPGME_KEYLIST_MODE_SIG_NOTATIONS' mode enabled, because it can be + expensive to retrieve all signature notations. + + The key signature structure has the following members: + + `gpgme_key_sig_t next' + This is a pointer to the next key signature structure in the + linked list, or `NULL' if this is the last element. + + `unsigned int revoked : 1' + This is true if the key signature is a revocation signature. + + `unsigned int expired : 1' + This is true if the key signature is expired. + + `unsigned int invalid : 1' + This is true if the key signature is invalid. + + `unsigned int exportable : 1' + This is true if the key signature is exportable. + + `gpgme_pubkey_algo_t pubkey_algo' + This is the public key algorithm used to create the signature. + + `char *keyid' + This is the key ID of the key (in hexadecimal digits) used to + create the signature. + + `long int timestamp' + This is the creation timestamp of the key signature. This is + -1 if the timestamp is invalid, and 0 if it is not available. + + `long int expires' + This is the expiration timestamp of the key signature, or 0 + if the key signature does not expire. + + `gpgme_error_t status' + This is the status of the signature and has the same meaning + as the member of the same name in a `gpgme_signature_t' + object. + + `unsigned int sig_class' + This specifies the signature class of the key signature. The + meaning is specific to the crypto engine. + + `char *uid' + This is the main user ID of the key used to create the + signature. + + `char *name' + This is the name component of `uid', if available. + + `char *comment' + This is the comment component of `uid', if available. + + `char *email' + This is the email component of `uid', if available. + + `gpgme_sig_notation_t notations' + This is a linked list with the notation data and policy URLs. + + -- Data type: gpgme_user_id_t + A user ID is a component of a `gpgme_key_t' object. One key can + have many user IDs. The first one in the list is the main (or + primary) user ID. + + The user ID structure has the following members. + + `gpgme_user_id_t next' + This is a pointer to the next user ID structure in the linked + list, or `NULL' if this is the last element. + + `unsigned int revoked : 1' + This is true if the user ID is revoked. + + `unsigned int invalid : 1' + This is true if the user ID is invalid. + + `gpgme_validity_t validity' + This specifies the validity of the user ID. + + `char *uid' + This is the user ID string. + + `char *name' + This is the name component of `uid', if available. + + `char *comment' + This is the comment component of `uid', if available. + + `char *email' + This is the email component of `uid', if available. + + `gpgme_key_sig_t signatures' + This is a linked list with the signatures on this user ID. + + -- Data type: gpgme_key_t + The `gpgme_key_t' type is a pointer to a key object. It has the + following members: + + `gpgme_keylist_mode_t keylist_mode' + The keylist mode that was active when the key was retrieved. + + `unsigned int revoked : 1' + This is true if the key is revoked. + + `unsigned int expired : 1' + This is true if the key is expired. + + `unsigned int disabled : 1' + This is true if the key is disabled. + + `unsigned int invalid : 1' + This is true if the key is invalid. This might have several + reasons, for a example for the S/MIME backend, it will be set + in during key listsing if the key could not be validated due + to a missing certificates or unmatched policies. + + `unsigned int can_encrypt : 1' + This is true if the key (ie one of its subkeys) can be used + for encryption. + + `unsigned int can_sign : 1' + This is true if the key (ie one of its subkeys) can be used + to create data signatures. + + `unsigned int can_certify : 1' + This is true if the key (ie one of its subkeys) can be used + to create key certificates. + + `unsigned int can_authenticate : 1' + This is true if the key (ie one of its subkeys) can be used + for authentication. + + `unsigned int is_qualified : 1' + This is true if the key can be used for qualified signatures + according to local government regulations. + + `unsigned int secret : 1' + This is true if the key is a secret key. Note, that this + will always be true even if the corresponding subkey flag may + be false (offline/stub keys). + + `gpgme_protocol_t protocol' + This is the protocol supported by this key. + + `char *issuer_serial' + If `protocol' is `GPGME_PROTOCOL_CMS', then this is the + issuer serial. + + `char *issuer_name' + If `protocol' is `GPGME_PROTOCOL_CMS', then this is the + issuer name. + + `char *chain_id' + If `protocol' is `GPGME_PROTOCOL_CMS', then this is the chain + ID, which can be used to built the certificate chain. + + `gpgme_validity_t owner_trust' + If `protocol' is `GPGME_PROTOCOL_OpenPGP', then this is the + owner trust. + + `gpgme_sub_key_t subkeys' + This is a linked list with the subkeys of the key. The first + subkey in the list is the primary key and usually available. + + `gpgme_user_id_t uids' + This is a linked list with the user IDs of the key. The + first user ID in the list is the main (or primary) user ID. + +* Menu: + +* Listing Keys:: Browsing the list of available keys. +* Information About Keys:: Requesting detailed information about keys. +* Key Signatures:: Listing the signatures on a key. +* Manipulating Keys:: Operations on keys. +* Generating Keys:: Creating new key pairs. +* Exporting Keys:: Retrieving key data from the key ring. +* Importing Keys:: Adding keys to the key ring. +* Deleting Keys:: Removing keys from the key ring. +* Changing Passphrases:: Change the passphrase of a key. +* Advanced Key Editing:: Advanced key edit operation. + + +File: gpgme.info, Node: Listing Keys, Next: Information About Keys, Up: Key Management + +7.5.1 Listing Keys +------------------ + + -- Function: gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t CTX, + const char *PATTERN, int SECRET_ONLY) + The function `gpgme_op_keylist_start' initiates a key listing + operation inside the context CTX. It sets everything up so that + subsequent invocations of `gpgme_op_keylist_next' return the keys + in the list. + + If PATTERN is `NULL', all available keys are returned. Otherwise, + PATTERN contains an engine specific expression that is used to + limit the list to all keys matching the pattern. Note that the + total length of the pattern is restricted to an engine-specific + maximum (a couple of hundred characters are usually accepted). The + pattern should be used to restrict the search to a certain common + name or user, not to list many specific keys at once by listing + their fingerprints or key IDs. + + If SECRET_ONLY is not `0', the list is restricted to secret keys + only. + + The context will be busy until either all keys are received (and + `gpgme_op_keylist_next' returns `GPG_ERR_EOF'), or + `gpgme_op_keylist_end' is called to finish the operation. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and passes through any errors that are + reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_keylist_ext_start + (gpgme_ctx_t CTX, const char *PATTERN[], int SECRET_ONLY, + int RESERVED) + The function `gpgme_op_keylist_ext_start' initiates an extended + key listing operation inside the context CTX. It sets everything + up so that subsequent invocations of `gpgme_op_keylist_next' + return the keys in the list. + + If PATTERN or *PATTERN is `NULL', all available keys are returned. + Otherwise, PATTERN is a `NULL' terminated array of strings that + are used to limit the list to all keys matching at least one of + the patterns verbatim. Note that the total length of all patterns + is restricted to an engine-specific maximum (the exact limit also + depends on the number of patterns and amount of quoting required, + but a couple of hundred characters are usually accepted). + Patterns should be used to restrict the search to a certain common + name or user, not to list many specific keys at once by listing + their fingerprints or key IDs. + + If SECRET_ONLY is not `0', the list is restricted to secret keys + only. + + The value of RESERVED must be `0'. + + The context will be busy until either all keys are received (and + `gpgme_op_keylist_next' returns `GPG_ERR_EOF'), or + `gpgme_op_keylist_end' is called to finish the operation. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and passes through any errors that are + reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t CTX, + gpgme_key_t *R_KEY) + The function `gpgme_op_keylist_next' returns the next key in the + list created by a previous `gpgme_op_keylist_start' operation in + the context CTX. The key will have one reference for the user. + *Note Manipulating Keys::. + + This is the only way to get at `gpgme_key_t' objects in GPGME. + + If the last key in the list has already been returned, + `gpgme_op_keylist_next' returns `GPG_ERR_EOF'. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX or + R_KEY is not a valid pointer, and `GPG_ERR_ENOMEM' if there is not + enough memory for the operation. + + -- Function: gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t CTX) + The function `gpgme_op_keylist_end' ends a pending key list + operation in the context CTX. + + After the operation completed successfully, the result of the key + listing operation can be retrieved with `gpgme_op_keylist_result'. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and `GPG_ERR_ENOMEM' if at some time during + the operation there was not enough memory available. + + The following example illustrates how all keys containing a certain +string (`g10code') can be listed with their key ID and the name and +e-mail address of the main user ID: + + gpgme_ctx_t ctx; + gpgme_key_t key; + gpgme_error_t err = gpgme_new (&ctx); + + if (!err) + { + err = gpgme_op_keylist_start (ctx, "g10code", 0); + while (!err) + { + err = gpgme_op_keylist_next (ctx, &key); + if (err) + break; + printf ("%s:", key->subkeys->keyid); + if (key->uids && key->uids->name) + printf (" %s", key->uids->name); + if (key->uids && key->uids->email) + printf (" <%s>", key->uids->email); + putchar ('\n'); + gpgme_key_release (key); + } + gpgme_release (ctx); + } + if (gpg_err_code (err) != GPG_ERR_EOF) + { + fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err)); + exit (1); + } + + -- Data type: gpgme_keylist_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_keylist_*' operation. After successfully ending a key + listing operation, you can retrieve the pointer to the result with + `gpgme_op_keylist_result'. The structure contains the following + member: + + `unsigned int truncated : 1' + This is true if the crypto backend had to truncate the + result, and less than the desired keys could be listed. + + -- Function: gpgme_keylist_result_t gpgme_op_keylist_result + (gpgme_ctx_t CTX) + The function `gpgme_op_keylist_result' returns a + `gpgme_keylist_result_t' pointer to a structure holding the result + of a `gpgme_op_keylist_*' operation. The pointer is only valid if + the last operation on the context was a key listing operation, and + if this operation finished successfully. The returned pointer is + only valid until the next operation is started on the context. + + In a simple program, for which a blocking operation is acceptable, +the following function can be used to retrieve a single key. + + -- Function: gpgme_error_t gpgme_get_key (gpgme_ctx_t CTX, + const char *FPR, gpgme_key_t *R_KEY, int SECRET) + The function `gpgme_get_key' gets the key with the fingerprint (or + key ID) FPR from the crypto backend and return it in R_KEY. If + SECRET is true, get the secret key. The currently active keylist + mode is used to retrieve the key. The key will have one reference + for the user. + + If the key is not found in the keyring, `gpgme_get_key' returns + the error code `GPG_ERR_EOF' and *R_KEY will be set to `NULL'. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX or + R_KEY is not a valid pointer or FPR is not a fingerprint or key + ID, `GPG_ERR_AMBIGUOUS_NAME' if the key ID was not a unique + specifier for a key, and `GPG_ERR_ENOMEM' if at some time during + the operation there was not enough memory available. + + +File: gpgme.info, Node: Information About Keys, Next: Key Signatures, Prev: Listing Keys, Up: Key Management + +7.5.2 Information About Keys +---------------------------- + +Please see the beginning of this section for more information about +`gpgme_key_t' objects. + + -- Data type: gpgme_validity_t + The `gpgme_validity_t' type is used to specify the validity of a + user ID in a key. The following validities are defined: + + `GPGME_VALIDITY_UNKNOWN' + The user ID is of unknown validity. The string + representation of this validity is "?". + + `GPGME_VALIDITY_UNDEFINED' + The validity of the user ID is undefined. The string + representation of this validity is "q". + + `GPGME_VALIDITY_NEVER' + The user ID is never valid. The string representation of this + validity is "n". + + `GPGME_VALIDITY_MARGINAL' + The user ID is marginally valid. The string representation + of this validity is "m". + + `GPGME_VALIDITY_FULL' + The user ID is fully valid. The string representation of this + validity is "f". + + `GPGME_VALIDITY_ULTIMATE' + The user ID is ultimately valid. The string representation + of this validity is "u". + + The following interfaces are deprecated and only provided for +backward compatibility. Don't use them. They will be removed in a +future version of GPGME. + + -- Data type: gpgme_attr_t + The `gpgme_attr_t' type is used to specify a key or trust item + attribute. The following attributes are defined: + + `GPGME_ATTR_KEYID' + This is the key ID of a sub key. It is representable as a + string. + + For trust items, the trust item refers to the key with this + ID. + + `GPGME_ATTR_FPR' + This is the fingerprint of a sub key. It is representable as + a string. + + `GPGME_ATTR_ALGO' + This is the crypto algorithm for which the sub key can be + used. It is representable as a string and as a number. The + numbers correspond to the `enum gcry_pk_algos' values in the + gcrypt library. + + `GPGME_ATTR_LEN' + This is the key length of a sub key. It is representable as a + number. + + `GPGME_ATTR_CREATED' + This is the timestamp at creation time of a sub key. It is + representable as a number. + + `GPGME_ATTR_EXPIRE' + This is the expiration time of a sub key. It is + representable as a number. + + `GPGME_ATTR_OTRUST' + XXX FIXME (also for trust items) + + `GPGME_ATTR_USERID' + This is a user ID. There can be more than one user IDs in a + GPGME_KEY_T object. The first one (with index 0) is the + primary user ID. The user ID is representable as a number. + + For trust items, this is the user ID associated with this + trust item. + + `GPGME_ATTR_NAME' + This is the name belonging to a user ID. It is representable + as a string. + + `GPGME_ATTR_EMAIL' + This is the email address belonging to a user ID. It is + representable as a string. + + `GPGME_ATTR_COMMENT' + This is the comment belonging to a user ID. It is + representable as a string. + + `GPGME_ATTR_VALIDITY' + This is the validity belonging to a user ID. It is + representable as a string and as a number. See below for a + list of available validities. + + For trust items, this is the validity that is associated with + this trust item. + + `GPGME_ATTR_UID_REVOKED' + This specifies if a user ID is revoked. It is representable + as a number, and is `1' if the user ID is revoked, and `0' + otherwise. + + `GPGME_ATTR_UID_INVALID' + This specifies if a user ID is invalid. It is representable + as a number, and is `1' if the user ID is invalid, and `0' + otherwise. + + `GPGME_ATTR_LEVEL' + This is the trust level of a trust item. + + `GPGME_ATTR_TYPE' + This returns information about the type of key. For the + string function this will eother be "PGP" or "X.509". The + integer function returns 0 for PGP and 1 for X.509. It is + also used for the type of a trust item. + + `GPGME_ATTR_IS_SECRET' + This specifies if the key is a secret key. It is + representable as a number, and is `1' if the key is revoked, + and `0' otherwise. + + `GPGME_ATTR_KEY_REVOKED' + This specifies if a sub key is revoked. It is representable + as a number, and is `1' if the key is revoked, and `0' + otherwise. + + `GPGME_ATTR_KEY_INVALID' + This specifies if a sub key is invalid. It is representable + as a number, and is `1' if the key is invalid, and `0' + otherwise. + + `GPGME_ATTR_KEY_EXPIRED' + This specifies if a sub key is expired. It is representable + as a number, and is `1' if the key is expired, and `0' + otherwise. + + `GPGME_ATTR_KEY_DISABLED' + This specifies if a sub key is disabled. It is representable + as a number, and is `1' if the key is disabled, and `0' + otherwise. + + `GPGME_ATTR_KEY_CAPS' + This is a description of the capabilities of a sub key. It is + representable as a string. The string contains the letter + "e" if the key can be used for encryption, "s" if the key can + be used for signatures, and "c" if the key can be used for + certifications. + + `GPGME_ATTR_CAN_ENCRYPT' + This specifies if a sub key can be used for encryption. It is + representable as a number, and is `1' if the sub key can be + used for encryption, and `0' otherwise. + + `GPGME_ATTR_CAN_SIGN' + This specifies if a sub key can be used to create data + signatures. It is representable as a number, and is `1' if + the sub key can be used for signatures, and `0' otherwise. + + `GPGME_ATTR_CAN_CERTIFY' + This specifies if a sub key can be used to create key + certificates. It is representable as a number, and is `1' if + the sub key can be used for certifications, and `0' otherwise. + + `GPGME_ATTR_SERIAL' + The X.509 issuer serial attribute of the key. It is + representable as a string. + + `GPGME_ATTR_ISSUE' + The X.509 issuer name attribute of the key. It is + representable as a string. + + `GPGME_ATTR_CHAINID' + The X.509 chain ID can be used to build the certification + chain. It is representable as a string. + + -- Function: const char * gpgme_key_get_string_attr (gpgme_key_t KEY, + gpgme_attr_t WHAT, const void *RESERVED, int IDX) + The function `gpgme_key_get_string_attr' returns the value of the + string-representable attribute WHAT of key KEY. If the attribute + is an attribute of a sub key or an user ID, IDX specifies the sub + key or user ID of which the attribute value is returned. The + argument RESERVED is reserved for later use and should be `NULL'. + + The string returned is only valid as long as the key is valid. + + The function returns `0' if an attribute can't be returned as a + string, KEY is not a valid pointer, IDX out of range, or RESERVED + not `NULL'. + + -- Function: unsigned long gpgme_key_get_ulong_attr (gpgme_key_t KEY, + gpgme_attr_t WHAT, const void *RESERVED, int IDX) + The function `gpgme_key_get_ulong_attr' returns the value of the + number-representable attribute WHAT of key KEY. If the attribute + is an attribute of a sub key or an user ID, IDX specifies the sub + key or user ID of which the attribute value is returned. The + argument RESERVED is reserved for later use and should be `NULL'. + + The function returns `0' if the attribute can't be returned as a + number, KEY is not a valid pointer, IDX out of range, or RESERVED + not `NULL'. + + +File: gpgme.info, Node: Key Signatures, Next: Manipulating Keys, Prev: Information About Keys, Up: Key Management + +7.5.3 Key Signatures +-------------------- + +The following interfaces are deprecated and only provided for backward +compatibility. Don't use them. They will be removed in a future +version of GPGME. + + The signatures on a key are only available if the key was retrieved +via a listing operation with the `GPGME_KEYLIST_MODE_SIGS' mode +enabled, because it is expensive to retrieve all signatures of a key. + + So, before using the below interfaces to retrieve the signatures on a +key, you have to make sure that the key was listed with signatures +enabled. One convenient, but blocking, way to do this is to use the +function `gpgme_get_key'. + + -- Data type: gpgme_attr_t + The `gpgme_attr_t' type is used to specify a key signature + attribute. The following attributes are defined: + + `GPGME_ATTR_KEYID' + This is the key ID of the key which was used for the + signature. It is representable as a string. + + `GPGME_ATTR_ALGO' + This is the crypto algorithm used to create the signature. + It is representable as a string and as a number. The numbers + correspond to the `enum gcry_pk_algos' values in the gcrypt + library. + + `GPGME_ATTR_CREATED' + This is the timestamp at creation time of the signature. It + is representable as a number. + + `GPGME_ATTR_EXPIRE' + This is the expiration time of the signature. It is + representable as a number. + + `GPGME_ATTR_USERID' + This is the user ID associated with the signing key. The + user ID is representable as a number. + + `GPGME_ATTR_NAME' + This is the name belonging to a user ID. It is representable + as a string. + + `GPGME_ATTR_EMAIL' + This is the email address belonging to a user ID. It is + representable as a string. + + `GPGME_ATTR_COMMENT' + This is the comment belonging to a user ID. It is + representable as a string. + + `GPGME_ATTR_KEY_REVOKED' + This specifies if a key signature is a revocation signature. + It is representable as a number, and is `1' if the key is + revoked, and `0' otherwise. + + `GPGME_ATTR_SIG_CLASS' + This specifies the signature class of a key signature. It is + representable as a number. The meaning is specific to the + crypto engine. + + `GPGME_ATTR_SIG_CLASS' + This specifies the signature class of a key signature. It is + representable as a number. The meaning is specific to the + crypto engine. + + `GPGME_ATTR_SIG_STATUS' + This is the same value as returned by `gpgme_get_sig_status'. + + -- Function: const char * gpgme_key_sig_get_string_attr + (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t WHAT, + const void *RESERVED, int IDX) + The function `gpgme_key_sig_get_string_attr' returns the value of + the string-representable attribute WHAT of the signature IDX on + the user ID UID_IDX in the key KEY. The argument RESERVED is + reserved for later use and should be `NULL'. + + The string returned is only valid as long as the key is valid. + + The function returns `0' if an attribute can't be returned as a + string, KEY is not a valid pointer, UID_IDX or IDX out of range, + or RESERVED not `NULL'. + + -- Function: unsigned long gpgme_key_sig_get_ulong_attr + (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t WHAT, + const void *RESERVED, int IDX) + The function `gpgme_key_sig_get_ulong_attr' returns the value of + the number-representable attribute WHAT of the signature IDX on + the user ID UID_IDX in the key KEY. The argument RESERVED is + reserved for later use and should be `NULL'. + + The function returns `0' if an attribute can't be returned as a + string, KEY is not a valid pointer, UID_IDX or IDX out of range, + or RESERVED not `NULL'. + + +File: gpgme.info, Node: Manipulating Keys, Next: Generating Keys, Prev: Key Signatures, Up: Key Management + +7.5.4 Manipulating Keys +----------------------- + + -- Function: void gpgme_key_ref (gpgme_key_t KEY) + The function `gpgme_key_ref' acquires an additional reference for + the key KEY. + + -- Function: void gpgme_key_unref (gpgme_key_t KEY) + The function `gpgme_key_unref' releases a reference for the key + KEY. If this was the last reference, the key will be destroyed + and all resources associated to it will be released. + + The following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of GPGME. + + -- Function: void gpgme_key_release (gpgme_key_t KEY) + The function `gpgme_key_release' is equivalent to + `gpgme_key_unref'. + + +File: gpgme.info, Node: Generating Keys, Next: Exporting Keys, Prev: Manipulating Keys, Up: Key Management + +7.5.5 Generating Keys +--------------------- + + -- Function: gpgme_error_t gpgme_op_genkey (gpgme_ctx_t CTX, + const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET) + The function `gpgme_op_genkey' generates a new key pair in the + context CTX. The meaning of PUBLIC and SECRET depends on the + crypto backend. + + GnuPG does not support PUBLIC and SECRET, they should be `NULL'. + GnuPG will generate a key pair and add it to the standard key + ring. The fingerprint of the generated key is available with + `gpgme_op_genkey_result'. + + GpgSM requires PUBLIC to be a writable data object. GpgSM will + generate a secret key (which will be stored by `gpg-agent', and + return a certificate request in PUBLIC, which then needs to be + signed by the certification authority and imported before it can be + used. GpgSM does not make the fingerprint available. + + The argument PARMS specifies parameters for the key in an XML + string. The details about the format of PARMS are specific to the + crypto engine used by CTX. Here is an example for GnuPG as the + crypto engine (all parameters of OpenPGP key generation are + documented in the GPG manual): + + <GnupgKeyParms format="internal"> + Key-Type: default + Subkey-Type: default + Name-Real: Joe Tester + Name-Comment: with stupid passphrase + Name-Email: joe@foo.bar + Expire-Date: 0 + Passphrase: abc + </GnupgKeyParms> + + Here is an example for GpgSM as the crypto engine (all parameters + of OpenPGP key generation are documented in the GPGSM manual): + + <GnupgKeyParms format="internal"> + Key-Type: RSA + Key-Length: 1024 + Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester + Name-Email: joe@foo.bar + </GnupgKeyParms> + + Strings should be given in UTF-8 encoding. The only format + supported for now is "internal". The content of the + `GnupgKeyParms' container is passed verbatim to the crypto + backend. Control statements are not allowed. + + After the operation completed successfully, the result can be + retrieved with `gpgme_op_genkey_result'. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, `GPG_ERR_INV_VALUE' if + PARMS is not a valid XML string, `GPG_ERR_NOT_SUPPORTED' if PUBLIC + or SECRET is not valid, and `GPG_ERR_GENERAL' if no key was + created by the backend. + + -- Function: gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t CTX, + const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET) + The function `gpgme_op_genkey_start' initiates a `gpgme_op_genkey' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, `GPG_ERR_INV_VALUE' if + PARMS is not a valid XML string, and `GPG_ERR_NOT_SUPPORTED' if + PUBLIC or SECRET is not `NULL'. + + -- Data type: gpgme_genkey_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_genkey' operation. After successfully generating a key, + you can retrieve the pointer to the result with + `gpgme_op_genkey_result'. The structure contains the following + members: + + `unsigned int primary : 1' + This is a flag that is set to 1 if a primary key was created + and to 0 if not. + + `unsigned int sub : 1' + This is a flag that is set to 1 if a subkey was created and + to 0 if not. + + `char *fpr' + This is the fingerprint of the key that was created. If both + a primary and a sub key were generated, the fingerprint of + the primary key will be returned. If the crypto engine does + not provide the fingerprint, `fpr' will be a null pointer. + + -- Function: gpgme_genkey_result_t gpgme_op_genkey_result + (gpgme_ctx_t CTX) + The function `gpgme_op_genkey_result' returns a + `gpgme_genkey_result_t' pointer to a structure holding the result + of a `gpgme_op_genkey' operation. The pointer is only valid if the + last operation on the context was a `gpgme_op_genkey' or + `gpgme_op_genkey_start' operation, and if this operation finished + successfully. The returned pointer is only valid until the next + operation is started on the context. + + +File: gpgme.info, Node: Exporting Keys, Next: Importing Keys, Prev: Generating Keys, Up: Key Management + +7.5.6 Exporting Keys +-------------------- + +Exporting keys means the same as running `gpg' with the command +`--export'. However, a mode flag can be used to change the way the +export works. The available mode flags are described below, they may +be or-ed together. + +`GPGME_EXPORT_MODE_EXTERN' + If this bit is set, the output is send directly to the default + keyserver. This is currently only allowed for OpenPGP keys. It is + good practise to not send more than a few dozens key to a + keyserver at one time. Using this flag requires that the KEYDATA + argument of the export function is set to `NULL'. + +`GPGME_EXPORT_MODE_MINIMAL' + If this bit is set, the smallest possible key is exported. For + OpenPGP keys it removes all signatures except for the latest + self-signatures. For X.509 keys it has no effect. + + + -- Function: gpgme_error_t gpgme_op_export (gpgme_ctx_t CTX, + const char *PATTERN, gpgme_export_mode_t MODE, + gpgme_data_t KEYDATA) + The function `gpgme_op_export' extracts public keys and returns + them in the data buffer KEYDATA. The output format of the key + data returned is determined by the ASCII armor attribute set for + the context CTX, or, if that is not set, by the encoding specified + for KEYDATA. + + If PATTERN is `NULL', all available keys are returned. Otherwise, + PATTERN contains an engine specific expression that is used to + limit the list to all keys matching the pattern. + + MODE is usually 0; other values are described above. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + is not a valid empty data buffer, and passes through any errors + that are reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_export_start (gpgme_ctx_t CTX, + const char *PATTERN, gpgme_export_mode_t MODE, + gpgme_data_t KEYDATA) + The function `gpgme_op_export_start' initiates a `gpgme_op_export' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if KEYDATA is not a valid empty data buffer. + + -- Function: gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t CTX, + const char *PATTERN[], gpgme_export_mode_t MODE, + gpgme_data_t KEYDATA) + The function `gpgme_op_export' extracts public keys and returns + them in the data buffer KEYDATA. The output format of the key + data returned is determined by the ASCII armor attribute set for + the context CTX, or, if that is not set, by the encoding specified + for KEYDATA. + + If PATTERN or *PATTERN is `NULL', all available keys are returned. + Otherwise, PATTERN is a `NULL' terminated array of strings that + are used to limit the list to all keys matching at least one of + the patterns verbatim. + + MODE is usually 0; other values are described above. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + is not a valid empty data buffer, and passes through any errors + that are reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t CTX, + const char *PATTERN[], gpgme_export_mode_t MODE, + gpgme_data_t KEYDATA) + The function `gpgme_op_export_ext_start' initiates a + `gpgme_op_export_ext' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if KEYDATA is not a valid empty data buffer. + + -- Function: gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t CTX, + gpgme_key_t keys[], gpgme_export_mode_t MODE, + gpgme_data_t KEYDATA) + The function `gpgme_op_export_keys' extracts public keys and + returns them in the data buffer KEYDATA. The output format of the + key data returned is determined by the ASCII armor attribute set + for the context CTX, or, if that is not set, by the encoding + specified for KEYDATA. + + The keys to export are taken form the `NULL' terminated array + KEYS. Only keys of the the currently selected protocol of CTX + which do have a fingerprint set are considered for export. Other + keys specified by the KEYS are ignored. In particular OpenPGP + keys retrieved via an external key listing are not included. + + MODE is usually 0; other values are described above. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + is not a valid empty data buffer, `GPG_ERR_NO_DATA' if no useful + keys are in KEYS and passes through any errors that are reported + by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_export_keys_start + (gpgme_ctx_t CTX, gpgme_key_t KEYS[], + gpgme_export_mode_t MODE, gpgme_data_t KEYDATA) + The function `gpgme_op_export_keys_start' initiates a + `gpgme_op_export_ext' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if KEYDATA is not a valid empty data buffer, `GPG_ERR_NO_DATA' if + no useful keys are in KEYS and passes through any errors that are + reported by the crypto engine support routines. + + +File: gpgme.info, Node: Importing Keys, Next: Deleting Keys, Prev: Exporting Keys, Up: Key Management + +7.5.7 Importing Keys +-------------------- + +Importing keys means the same as running `gpg' with the command +`--import'. + + -- Function: gpgme_error_t gpgme_op_import (gpgme_ctx_t CTX, + gpgme_data_t KEYDATA) + The function `gpgme_op_import' adds the keys in the data buffer + KEYDATA to the key ring of the crypto engine used by CTX. The + format of KEYDATA can be ASCII armored, for example, but the + details are specific to the crypto engine. + + After the operation completed successfully, the result can be + retrieved with `gpgme_op_import_result'. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + import was completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + if CTX or KEYDATA is not a valid pointer, and `GPG_ERR_NO_DATA' if + KEYDATA is an empty data buffer. + + -- Function: gpgme_error_t gpgme_op_import_start (gpgme_ctx_t CTX, + gpgme_data_t KEYDATA) + The function `gpgme_op_import_start' initiates a `gpgme_op_import' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + import could be started successfully, `GPG_ERR_INV_VALUE' if + KEYDATA if CTX or KEYDATA is not a valid pointer, and + `GPG_ERR_NO_DATA' if KEYDATA is an empty data buffer. + + -- Function: gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t CTX, + gpgme_key_t *KEYS) + The function `gpgme_op_import_keys' adds the keys described by the + `NULL' terminated array KEYS to the key ring of the crypto engine + used by CTX. This function is the general interface to move a key + from one crypto engine to another as long as they are compatible. + In particular it is used to actually import and make keys + permanent which have been retrieved from an external source (i.e. + using `GPGME_KEYLIST_MODE_EXTERN'). (1) + + Only keys of the the currently selected protocol of CTX are + considered for import. Other keys specified by the KEYS are + ignored. As of now all considered keys must have been retrieved + using the same method, that is the used key listing mode must be + identical. + + After the operation completed successfully, the result can be + retrieved with `gpgme_op_import_result'. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + import was completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + if CTX or KEYDATA is not a valid pointer, `GPG_ERR_CONFLICT' if + the key listing mode does not match, and `GPG_ERR_NO_DATA' if no + keys are considered for export. + + -- Function: gpgme_error_t gpgme_op_import_keys_start + (gpgme_ctx_t CTX, gpgme_key_t *KEYS) + The function `gpgme_op_import_keys_start' initiates a + `gpgme_op_import_keys' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + import was completed successfully, `GPG_ERR_INV_VALUE' if KEYDATA + if CTX or KEYDATA is not a valid pointer, `GPG_ERR_CONFLICT' if + the key listing mode does not match, and `GPG_ERR_NO_DATA' if no + keys are considered for export. + + -- Data type: gpgme_import_status_t + This is a pointer to a structure used to store a part of the + result of a `gpgme_op_import' operation. For each considered key + one status is added that contains information about the result of + the import. The structure contains the following members: + + `gpgme_import_status_t next' + This is a pointer to the next status structure in the linked + list, or `NULL' if this is the last element. + + `char *fpr' + This is the fingerprint of the key that was considered. + + `gpgme_error_t result' + If the import was not successful, this is the error value + that caused the import to fail. Otherwise the error code is + `GPG_ERR_NO_ERROR'. + + `unsigned int status' + This is a bit-wise OR of the following flags that give more + information about what part of the key was imported. If the + key was already known, this might be 0. + + `GPGME_IMPORT_NEW' + The key was new. + + `GPGME_IMPORT_UID' + The key contained new user IDs. + + `GPGME_IMPORT_SIG' + The key contained new signatures. + + `GPGME_IMPORT_SUBKEY' + The key contained new sub keys. + + `GPGME_IMPORT_SECRET' + The key contained a secret key. + + -- Data type: gpgme_import_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_import' operation. After a successful import operation, + you can retrieve the pointer to the result with + `gpgme_op_import_result'. The structure contains the following + members: + + `int considered' + The total number of considered keys. + + `int no_user_id' + The number of keys without user ID. + + `int imported' + The total number of imported keys. + + `imported_rsa' + The number of imported RSA keys. + + `unchanged' + The number of unchanged keys. + + `new_user_ids' + The number of new user IDs. + + `new_sub_keys' + The number of new sub keys. + + `new_signatures' + The number of new signatures. + + `new_revocations' + The number of new revocations. + + `secret_read' + The total number of secret keys read. + + `secret_imported' + The number of imported secret keys. + + `secret_unchanged' + The number of unchanged secret keys. + + `not_imported' + The number of keys not imported. + + `gpgme_import_status_t imports' + A list of gpgme_import_status_t objects which contain more + information about the keys for which an import was attempted. + + -- Function: gpgme_import_result_t gpgme_op_import_result + (gpgme_ctx_t CTX) + The function `gpgme_op_import_result' returns a + `gpgme_import_result_t' pointer to a structure holding the result + of a `gpgme_op_import' operation. The pointer is only valid if + the last operation on the context was a `gpgme_op_import' or + `gpgme_op_import_start' operation, and if this operation finished + successfully. The returned pointer is only valid until the next + operation is started on the context. + + The following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of GPGME. + + -- Function: gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t CTX, + gpgme_data_t KEYDATA, int *NR) + The function `gpgme_op_import_ext' is equivalent to: + + gpgme_error_t err = gpgme_op_import (ctx, keydata); + if (!err) + { + gpgme_import_result_t result = gpgme_op_import_result (ctx); + *nr = result->considered; + } + + ---------- Footnotes ---------- + + (1) Thus it is a replacement for the usual workaround of exporting +and then importing a key to make an X.509 key permanent. + + +File: gpgme.info, Node: Deleting Keys, Next: Changing Passphrases, Prev: Importing Keys, Up: Key Management + +7.5.8 Deleting Keys +------------------- + + -- Function: gpgme_error_t gpgme_op_delete (gpgme_ctx_t CTX, + const gpgme_key_t KEY, int ALLOW_SECRET) + The function `gpgme_op_delete' deletes the key KEY from the key + ring of the crypto engine used by CTX. If ALLOW_SECRET is `0', + only public keys are deleted, otherwise secret keys are deleted as + well, if that is supported. + + The function returns the error code `GPG_ERR_NO_ERROR' if the key + was deleted successfully, `GPG_ERR_INV_VALUE' if CTX or KEY is not + a valid pointer, `GPG_ERR_NO_PUBKEY' if KEY could not be found in + the keyring, `GPG_ERR_AMBIGUOUS_NAME' if the key was not specified + unambiguously, and `GPG_ERR_CONFLICT' if the secret key for KEY is + available, but ALLOW_SECRET is zero. + + -- Function: gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t CTX, + const gpgme_key_t KEY, int ALLOW_SECRET) + The function `gpgme_op_delete_start' initiates a `gpgme_op_delete' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation was started successfully, and `GPG_ERR_INV_VALUE' if CTX + or KEY is not a valid pointer. + + +File: gpgme.info, Node: Changing Passphrases, Next: Advanced Key Editing, Prev: Deleting Keys, Up: Key Management + +7.5.9 Changing Passphrases +-------------------------- + + -- Function: gpgme_error_t gpgme_op_passwd (gpgme_ctx_t CTX, + const gpgme_key_t KEY, unsigned int FLAGS) + The function `gpgme_op_passwd' changes the passphrase of the + private key associated with KEY. The only allowed value for FLAGS + is `0'. The backend engine will usually popup a window to ask for + the old and the new passphrase. Thus this function is not useful + in a server application (where passphrases are not required + anyway). + + Note that old `gpg' engines (before version 2.0.15) do not support + this command and will silently ignore it. + + -- Function: gpgme_error_t gpgme_op_passwd_start (gpgme_ctx_t CTX, + const gpgme_key_t KEY, unsigned int FLAGS) + The function `gpgme_op_passwd_start' initiates a `gpgme_op_passwd' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns `0' if the operation was started successfully, + and an error code if one of the arguments is not valid or the + oepration could not be started. + + +File: gpgme.info, Node: Advanced Key Editing, Prev: Changing Passphrases, Up: Key Management + +7.5.10 Advanced Key Editing +--------------------------- + + -- Data type: gpgme_error_t (*gpgme_edit_cb_t) (void *HANDLE, +gpgme_status_code_t STATUS, const char *ARGS, int FD) + The `gpgme_edit_cb_t' type is the type of functions which GPGME + calls if it a key edit operation is on-going. The status code + STATUS and the argument line ARGS are passed through by GPGME from + the crypto engine. The file descriptor FD is -1 for normal status + messages. If STATUS indicates a command rather than a status + message, the response to the command should be written to FD. The + HANDLE is provided by the user at start of operation. + + The function should return `GPG_ERR_NO_ERROR' or an error value. + + -- Function: gpgme_error_t gpgme_op_edit (gpgme_ctx_t CTX, + gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE, + gpgme_data_t OUT) + The function `gpgme_op_edit' processes the key KEY interactively, + using the edit callback function FNC with the handle HANDLE. The + callback is invoked for every status and command request from the + crypto engine. The output of the crypto engine is written to the + data object OUT. + + Note that the protocol between the callback function and the crypto + engine is specific to the crypto engine and no further support in + implementing this protocol correctly is provided by GPGME. + + The function returns the error code `GPG_ERR_NO_ERROR' if the edit + operation completes successfully, `GPG_ERR_INV_VALUE' if CTX or + KEY is not a valid pointer, and any error returned by the crypto + engine or the edit callback handler. + + -- Function: gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t CTX, + gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE, + gpgme_data_t OUT) + The function `gpgme_op_edit_start' initiates a `gpgme_op_edit' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation was started successfully, and `GPG_ERR_INV_VALUE' if CTX + or KEY is not a valid pointer. + + -- Function: gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t CTX, + gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE, + gpgme_data_t OUT) + The function `gpgme_op_card_edit' is analogous to `gpgme_op_edit', + but should be used to process the smart card corresponding to the + key KEY. + + -- Function: gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t CTX, + gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE, + gpgme_data_t OUT) + The function `gpgme_op_card_edit_start' initiates a + `gpgme_op_card_edit' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation was started successfully, and `GPG_ERR_INV_VALUE' if CTX + or KEY is not a valid pointer. + + +File: gpgme.info, Node: Trust Item Management, Next: Crypto Operations, Prev: Key Management, Up: Contexts + +7.6 Trust Item Management +========================= + +*Caution:* The trust items interface is experimental. + + -- Data type: gpgme_trust_item_t + The `gpgme_trust_item_t' type is a pointer to a trust item object. + It has the following members: + + `char *keyid' + This is a string describing the key to which this trust items + belongs. + + `int type' + This is the type of the trust item. A value of 1 refers to a + key, a value of 2 refers to a user ID. + + `int level' + This is the trust level. + + `char *owner_trust' + The owner trust if `type' is 1. + + `char *validity' + The calculated validity. + + `char *name' + The user name if `type' is 2. + +* Menu: + +* Listing Trust Items:: Browsing the list of available trust items. +* Information About Trust Items:: Requesting information about trust items. +* Manipulating Trust Items:: Operations on trust items. + + +File: gpgme.info, Node: Listing Trust Items, Next: Information About Trust Items, Up: Trust Item Management + +7.6.1 Listing Trust Items +------------------------- + + -- Function: gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t CTX, + const char *PATTERN, int MAX_LEVEL) + The function `gpgme_op_trustlist_start' initiates a trust item + listing operation inside the context CTX. It sets everything up + so that subsequent invocations of `gpgme_op_trustlist_next' return + the trust items in the list. + + The string PATTERN contains an engine specific expression that is + used to limit the list to all trust items matching the pattern. It + can not be the empty string. + + The argument MAX_LEVEL is currently ignored. + + The context will be busy until either all trust items are received + (and `gpgme_op_trustlist_next' returns `GPG_ERR_EOF'), or + `gpgme_op_trustlist_end' is called to finish the operation. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and passes through any errors that are + reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t CTX, + gpgme_trust_item_t *R_ITEM) + The function `gpgme_op_trustlist_next' returns the next trust item + in the list created by a previous `gpgme_op_trustlist_start' + operation in the context CTX. The trust item can be destroyed + with `gpgme_trust_item_release'. *Note Manipulating Trust Items::. + + This is the only way to get at `gpgme_trust_item_t' objects in + GPGME. + + If the last trust item in the list has already been returned, + `gpgme_op_trustlist_next' returns `GPG_ERR_EOF'. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX or + R_ITEM is not a valid pointer, and `GPG_ERR_ENOMEM' if there is + not enough memory for the operation. + + -- Function: gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t CTX) + The function `gpgme_op_trustlist_end' ends a pending trust list + operation in the context CTX. + + The function returns the error code `GPG_ERR_INV_VALUE' if CTX is + not a valid pointer, and `GPG_ERR_ENOMEM' if at some time during + the operation there was not enough memory available. + + +File: gpgme.info, Node: Information About Trust Items, Next: Manipulating Trust Items, Prev: Listing Trust Items, Up: Trust Item Management + +7.6.2 Information About Trust Items +----------------------------------- + +The following interfaces are deprecated and only provided for backward +compatibility. Don't use them. They will be removed in a future +version of GPGME. + + Trust items have attributes which can be queried using the interfaces +below. The attribute identifiers are shared with those for key +attributes. *Note Information About Keys::. + + -- Function: const char * gpgme_trust_item_get_string_attr + (gpgme_trust_item_t ITEM, gpgme_attr_t WHAT, + const void *RESERVED, int IDX) + The function `gpgme_trust_item_get_string_attr' returns the value + of the string-representable attribute WHAT of trust item ITEM. + The arguments IDX and RESERVED are reserved for later use and + should be `0' and `NULL' respectively. + + The string returned is only valid as long as the key is valid. + + The function returns `0' if an attribute can't be returned as a + string, KEY is not a valid pointer, IDX out of range, or RESERVED + not `NULL'. + + -- Function: int gpgme_trust_item_get_int_attr + (gpgme_trust_item_t ITEM, gpgme_attr_t WHAT, + const void *RESERVED, int IDX) + The function `gpgme_trust_item_get_int_attr' returns the value of + the number-representable attribute WHAT of trust item ITEM. If + the attribute occurs more than once in the trust item, the index + is specified by IDX. However, currently no such attribute exists, + so IDX should be `0'. The argument RESERVED is reserved for later + use and should be `NULL'. + + The function returns `0' if the attribute can't be returned as a + number, KEY is not a valid pointer, IDX out of range, or RESERVED + not `NULL'. + + +File: gpgme.info, Node: Manipulating Trust Items, Prev: Information About Trust Items, Up: Trust Item Management + +7.6.3 Manipulating Trust Items +------------------------------ + + -- Function: void gpgme_trust_item_ref (gpgme_trust_item_t ITEM) + The function `gpgme_trust_item_ref' acquires an additional + reference for the trust item ITEM. + + -- Function: void gpgme_trust_item_unref (gpgme_trust_item_t ITEM) + The function `gpgme_trust_item_unref' releases a reference for the + trust item ITEM. If this was the last reference, the trust item + will be destroyed and all resources associated to it will be + released. + + The following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of GPGME. + + -- Function: void gpgme_trust_item_release (gpgme_trust_item_t ITEM) + The function `gpgme_trust_item_release' is an alias for + `gpgme_trust_item_unref'. + + +File: gpgme.info, Node: Crypto Operations, Next: Run Control, Prev: Trust Item Management, Up: Contexts + +7.7 Crypto Operations +===================== + +Sometimes, the result of a crypto operation returns a list of invalid +keys encountered in processing the request. The following structure is +used to hold information about such a key. + + -- Data type: gpgme_invalid_key_t + This is a pointer to a structure used to store a part of the + result of a crypto operation which takes user IDs as one input + parameter. The structure contains the following members: + + `gpgme_invalid_key_t next' + This is a pointer to the next invalid key structure in the + linked list, or `NULL' if this is the last element. + + `char *fpr' + The fingerprint or key ID of the invalid key encountered. + + `gpgme_error_t reason' + An error code describing the reason why the key was found + invalid. + +* Menu: + +* Decrypt:: Decrypting a ciphertext. +* Verify:: Verifying a signature. +* Decrypt and Verify:: Decrypting a signed ciphertext. +* Sign:: Creating a signature. +* Encrypt:: Encrypting a plaintext. + + +File: gpgme.info, Node: Decrypt, Next: Verify, Up: Crypto Operations + +7.7.1 Decrypt +------------- + + -- Function: gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t CTX, + gpgme_data_t CIPHER, gpgme_data_t PLAIN) + The function `gpgme_op_decrypt' decrypts the ciphertext in the + data object CIPHER and stores it into the data object PLAIN. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + ciphertext could be decrypted successfully, `GPG_ERR_INV_VALUE' if + CTX, CIPHER or PLAIN is not a valid pointer, `GPG_ERR_NO_DATA' if + CIPHER does not contain any data to decrypt, + `GPG_ERR_DECRYPT_FAILED' if CIPHER is not a valid cipher text, + `GPG_ERR_BAD_PASSPHRASE' if the passphrase for the secret key + could not be retrieved, and passes through any errors that are + reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t CTX, + gpgme_data_t CIPHER, gpgme_data_t PLAIN) + The function `gpgme_op_decrypt_start' initiates a + `gpgme_op_decrypt' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if CIPHER or PLAIN is not a valid pointer. + + -- Data type: gpgme_recipient_t + This is a pointer to a structure used to store information about + the recipient of an encrypted text which is decrypted in a + `gpgme_op_decrypt' operation. This information (except for the + status field) is even available before the operation finished + successfully, for example in a passphrase callback. The structure + contains the following members: + + `gpgme_recipient_t next' + This is a pointer to the next recipient structure in the + linked list, or `NULL' if this is the last element. + + `gpgme_pubkey_algo_t' + The public key algorithm used in the encryption. + + `unsigned int wrong_key_usage : 1' + This is true if the key was not used according to its policy. + + `char *keyid' + This is the key ID of the key (in hexadecimal digits) used as + recipient. + + `gpgme_error_t status' + This is an error number with the error code GPG_ERR_NO_SECKEY + if the secret key for this recipient is not available, and 0 + otherwise. + + -- Data type: gpgme_decrypt_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_decrypt' operation. After successfully decrypting data, + you can retrieve the pointer to the result with + `gpgme_op_decrypt_result'. The structure contains the following + members: + + `char *unsupported_algorithm' + If an unsupported algorithm was encountered, this string + describes the algorithm that is not supported. + + `unsigned int wrong_key_usage : 1' + This is true if the key was not used according to its policy. + + `gpgme_recipient_t recipients' + This is a linked list of recipients to which this message was + encrypted. + + `char *file_name' + This is the filename of the original plaintext message file + if it is known, otherwise this is a null pointer. + + -- Function: gpgme_decrypt_result_t gpgme_op_decrypt_result + (gpgme_ctx_t CTX) + The function `gpgme_op_decrypt_result' returns a + `gpgme_decrypt_result_t' pointer to a structure holding the result + of a `gpgme_op_decrypt' operation. The pointer is only valid if + the last operation on the context was a `gpgme_op_decrypt' or + `gpgme_op_decrypt_start' operation. If the operation failed this + might be a `NULL' pointer. The returned pointer is only valid + until the next operation is started on the context. + + +File: gpgme.info, Node: Verify, Next: Decrypt and Verify, Prev: Decrypt, Up: Crypto Operations + +7.7.2 Verify +------------ + + -- Function: gpgme_error_t gpgme_op_verify (gpgme_ctx_t CTX, + gpgme_data_t SIG, gpgme_data_t SIGNED_TEXT, + gpgme_data_t PLAIN) + The function `gpgme_op_verify' verifies that the signature in the + data object SIG is a valid signature. If SIG is a detached + signature, then the signed text should be provided in SIGNED_TEXT + and PLAIN should be a null pointer. Otherwise, if SIG is a normal + (or cleartext) signature, SIGNED_TEXT should be a null pointer and + PLAIN should be a writable data object that will contain the + plaintext after successful verification. + + The results of the individual signature verifications can be + retrieved with `gpgme_op_verify_result'. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be completed successfully, `GPG_ERR_INV_VALUE' if + CTX, SIG or PLAIN is not a valid pointer, `GPG_ERR_NO_DATA' if SIG + does not contain any data to verify, and passes through any errors + that are reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t CTX, + gpgme_data_t SIG, gpgme_data_t SIGNED_TEXT, + gpgme_data_t PLAIN) + The function `gpgme_op_verify_start' initiates a `gpgme_op_verify' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, `GPG_ERR_INV_VALUE' if + CTX, SIG or PLAIN is not a valid pointer, and `GPG_ERR_NO_DATA' if + SIG or PLAIN does not contain any data to verify. + + -- Data type: gpgme_sig_notation_t + This is a pointer to a structure used to store a part of the + result of a `gpgme_op_verify' operation. The structure contains + the following members: + + `gpgme_sig_notation_t next' + This is a pointer to the next new signature notation + structure in the linked list, or `NULL' if this is the last + element. + + `char *name' + The name of the notation field. If this is `NULL', then the + member `value' will contain a policy URL. + + `int name_len' + The length of the `name' field. For strings the length is + counted without the trailing binary zero. + + `char *value' + The value of the notation field. If `name' is `NULL', then + this is a policy URL. + + `int value_len' + The length of the `value' field. For strings the length is + counted without the trailing binary zero. + + `gpgme_sig_notation_flags_t flags' + The accumulated flags field. This field contains the flags + associated with the notation data in an accumulated form + which can be used as an argument to the function + `gpgme_sig_notation_add'. The value `flags' is a bitwise-or + combination of one or multiple of the following bit values: + + `GPGME_SIG_NOTATION_HUMAN_READABLE' + The `GPGME_SIG_NOTATION_HUMAN_READABLE' symbol specifies + that the notation data is in human readable form + + `GPGME_SIG_NOTATION_CRITICAL' + The `GPGME_SIG_NOTATION_CRITICAL' symbol specifies that + the notation data is critical. + + + `unsigned int human_readable : 1' + This is true if the `GPGME_SIG_NOTATION_HUMAN_READABLE' flag + is set and false otherwise. This flag is only valid for + notation data, not for policy URLs. + + `unsigned int critical : 1' + This is true if the `GPGME_SIG_NOTATION_CRITICAL' flag is set + and false otherwise. This flag is valid for notation data + and policy URLs. + + + -- Data type: gpgme_signature_t + This is a pointer to a structure used to store a part of the + result of a `gpgme_op_verify' operation. The structure contains + the following members: + + `gpgme_signature_t next' + This is a pointer to the next new signature structure in the + linked list, or `NULL' if this is the last element. + + `gpgme_sigsum_t summary' + This is a bit vector giving a summary of the signature + status. It provides an easy interface to a defined semantic + of the signature status. Checking just one bit is sufficient + to see whether a signature is valid without any restrictions. + + The defined bits are: + `GPGME_SIGSUM_VALID' + The signature is fully valid. + + `GPGME_SIGSUM_GREEN' + The signature is good but one might want to display some + extra information. Check the other bits. + + `GPGME_SIGSUM_RED' + The signature is bad. It might be useful to check other + bits and display more information, i.e. a revoked + certificate might not render a signature invalid when + the message was received prior to the cause for the + revocation. + + `GPGME_SIGSUM_KEY_REVOKED' + The key or at least one certificate has been revoked. + + `GPGME_SIGSUM_KEY_EXPIRED' + The key or one of the certificates has expired. It is + probably a good idea to display the date of the + expiration. + + `GPGME_SIGSUM_SIG_EXPIRED' + The signature has expired. + + `GPGME_SIGSUM_KEY_MISSING' + Can't verify due to a missing key or certificate. + + `GPGME_SIGSUM_CRL_MISSING' + The CRL (or an equivalent mechanism) is not available. + + `GPGME_SIGSUM_CRL_TOO_OLD' + Available CRL is too old. + + `GPGME_SIGSUM_BAD_POLICY' + A policy requirement was not met. + + `GPGME_SIGSUM_SYS_ERROR' + A system error occured. + + `char *fpr' + This is the fingerprint or key ID of the signature. + + `gpgme_error_t status' + This is the status of the signature. In particular, the + following status codes are of interest: + + `GPG_ERR_NO_ERROR' + This status indicates that the signature is valid. For + the combined result this status means that all + signatures are valid. + + `GPG_ERR_SIG_EXPIRED' + This status indicates that the signature is valid but + expired. For the combined result this status means + that all signatures are valid and expired. + + `GPG_ERR_KEY_EXPIRED' + This status indicates that the signature is valid but + the key used to verify the signature has expired. For + the combined result this status means that all + signatures are valid and all keys are expired. + + `GPG_ERR_CERT_REVOKED' + This status indicates that the signature is valid but + the key used to verify the signature has been revoked. + For the combined result this status means that all + signatures are valid and all keys are revoked. + + `GPG_ERR_BAD_SIGNATURE' + This status indicates that the signature is invalid. + For the combined result this status means that all + signatures are invalid. + + `GPG_ERR_NO_PUBKEY' + This status indicates that the signature could not be + verified due to a missing key. For the combined + result this status means that all signatures could not + be checked due to missing keys. + + `GPG_ERR_GENERAL' + This status indicates that there was some other error + which prevented the signature verification. + + `gpgme_sig_notation_t notations' + This is a linked list with the notation data and policy URLs. + + `unsigned long timestamp' + The creation timestamp of this signature. + + `unsigned long exp_timestamp' + The expiration timestamp of this signature, or 0 if the + signature does not expire. + + `unsigned int wrong_key_usage : 1' + This is true if the key was not used according to its policy. + + `unsigned int pka_trust : 2' + This is set to the trust information gained by means of the + PKA system. Values are: + `0' + No PKA information available or verification not + possible. + + `1' + PKA verification failed. + + `2' + PKA verification succeeded. + + `3' + Reserved for future use. + Depending on the configuration of the engine, this metric may + also be reflected by the validity of the signature. + + `unsigned int chain_model : 1' + This is true if the validity of the signature has been + checked using the chain model. In the chain model the time + the signature has been created must be within the validity + period of the certificate and the time the certificate itself + has been created must be within the validity period of the + issuing certificate. In contrast the default validation model + checks the validity of signature as well at the entire + certificate chain at the current time. + + `gpgme_validity_t validity' + The validity of the signature. + + `gpgme_error_t validity_reason' + If a signature is not valid, this provides a reason why. + + `gpgme_pubkey_algo_t' + The public key algorithm used to create this signature. + + `gpgme_hash_algo_t' + The hash algorithm used to create this signature. + + -- Data type: gpgme_verify_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_verify' operation. After verifying a signature, you can + retrieve the pointer to the result with `gpgme_op_verify_result'. + If the operation failed this might be a `NULL' pointer. The + structure contains the following member: + + `gpgme_signature_t signatures' + A linked list with information about all signatures for which + a verification was attempted. + + `char *file_name' + This is the filename of the original plaintext message file + if it is known, otherwise this is a null pointer. + + -- Function: gpgme_verify_result_t gpgme_op_verify_result + (gpgme_ctx_t CTX) + The function `gpgme_op_verify_result' returns a + `gpgme_verify_result_t' pointer to a structure holding the result + of a `gpgme_op_verify' operation. The pointer is only valid if + the last operation on the context was a `gpgme_op_verify', + `gpgme_op_verify_start', `gpgme_op_decrypt_verify' or + `gpgme_op_decrypt_verify_start' operation, and if this operation + finished successfully (for `gpgme_op_decrypt_verify' and + `gpgme_op_decrypt_verify_start', the error code `GPG_ERR_NO_DATA' + counts as successful in this context). The returned pointer is + only valid until the next operation is started on the context. + + The following interfaces are deprecated and only provided for +backward compatibility. Don't use them. They will be removed in a +future version of GPGME. + + -- Data type: enum gpgme_sig_stat_t + The `gpgme_sig_stat_t' type holds the result of a signature check, + or the combined result of all signatures. The following results + are possible: + + `GPGME_SIG_STAT_NONE' + This status should not occur in normal operation. + + `GPGME_SIG_STAT_GOOD' + This status indicates that the signature is valid. For the + combined result this status means that all signatures are + valid. + + `GPGME_SIG_STAT_GOOD_EXP' + This status indicates that the signature is valid but + expired. For the combined result this status means that all + signatures are valid and expired. + + `GPGME_SIG_STAT_GOOD_EXPKEY' + This status indicates that the signature is valid but the key + used to verify the signature has expired. For the combined + result this status means that all signatures are valid and + all keys are expired. + + `GPGME_SIG_STAT_BAD' + This status indicates that the signature is invalid. For the + combined result this status means that all signatures are + invalid. + + `GPGME_SIG_STAT_NOKEY' + This status indicates that the signature could not be + verified due to a missing key. For the combined result this + status means that all signatures could not be checked due to + missing keys. + + `GPGME_SIG_STAT_NOSIG' + This status indicates that the signature data provided was + not a real signature. + + `GPGME_SIG_STAT_ERROR' + This status indicates that there was some other error which + prevented the signature verification. + + `GPGME_SIG_STAT_DIFF' + For the combined result this status means that at least two + signatures have a different status. You can get each key's + status with `gpgme_get_sig_status'. + + -- Function: const char * gpgme_get_sig_status (gpgme_ctx_t CTX, + int IDX, gpgme_sig_stat_t *R_STAT, time_t *R_CREATED) + The function `gpgme_get_sig_status' is equivalent to: + + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + { + sig = sig->next; + idx--; + } + if (!sig || idx) + return NULL; + + if (r_stat) + { + switch (gpg_err_code (sig->status)) + { + case GPG_ERR_NO_ERROR: + *r_stat = GPGME_SIG_STAT_GOOD; + break; + + case GPG_ERR_BAD_SIGNATURE: + *r_stat = GPGME_SIG_STAT_BAD; + break; + + case GPG_ERR_NO_PUBKEY: + *r_stat = GPGME_SIG_STAT_NOKEY; + break; + + case GPG_ERR_NO_DATA: + *r_stat = GPGME_SIG_STAT_NOSIG; + break; + + case GPG_ERR_SIG_EXPIRED: + *r_stat = GPGME_SIG_STAT_GOOD_EXP; + break; + + case GPG_ERR_KEY_EXPIRED: + *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY; + break; + + default: + *r_stat = GPGME_SIG_STAT_ERROR; + break; + } + } + if (r_created) + *r_created = sig->timestamp; + return sig->fpr; + + -- Function: const char * gpgme_get_sig_string_attr (gpgme_ctx_t CTX, + int IDX, gpgme_attr_t WHAT, int WHATIDX) + The function `gpgme_get_sig_string_attr' is equivalent to: + + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + { + sig = sig->next; + idx--; + } + if (!sig || idx) + return NULL; + + switch (what) + { + case GPGME_ATTR_FPR: + return sig->fpr; + + case GPGME_ATTR_ERRTOK: + if (whatidx == 1) + return sig->wrong_key_usage ? "Wrong_Key_Usage" : ""; + else + return ""; + default: + break; + } + + return NULL; + + -- Function: const char * gpgme_get_sig_ulong_attr (gpgme_ctx_t CTX, + int IDX, gpgme_attr_t WAHT, int WHATIDX) + The function `gpgme_get_sig_ulong_attr' is equivalent to: + + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + { + sig = sig->next; + idx--; + } + if (!sig || idx) + return 0; + + switch (what) + { + case GPGME_ATTR_CREATED: + return sig->timestamp; + + case GPGME_ATTR_EXPIRE: + return sig->exp_timestamp; + + case GPGME_ATTR_VALIDITY: + return (unsigned long) sig->validity; + + case GPGME_ATTR_SIG_STATUS: + switch (sig->status) + { + case GPG_ERR_NO_ERROR: + return GPGME_SIG_STAT_GOOD; + + case GPG_ERR_BAD_SIGNATURE: + return GPGME_SIG_STAT_BAD; + + case GPG_ERR_NO_PUBKEY: + return GPGME_SIG_STAT_NOKEY; + + case GPG_ERR_NO_DATA: + return GPGME_SIG_STAT_NOSIG; + + case GPG_ERR_SIG_EXPIRED: + return GPGME_SIG_STAT_GOOD_EXP; + + case GPG_ERR_KEY_EXPIRED: + return GPGME_SIG_STAT_GOOD_EXPKEY; + + default: + return GPGME_SIG_STAT_ERROR; + } + + case GPGME_ATTR_SIG_SUMMARY: + return sig->summary; + + default: + break; + } + return 0; + + -- Function: const char * gpgme_get_sig_key (gpgme_ctx_t CTX, int IDX, + gpgme_key_t *R_KEY) + The function `gpgme_get_sig_key' is equivalent to: + + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + { + sig = sig->next; + idx--; + } + if (!sig || idx) + return gpg_error (GPG_ERR_EOF); + + return gpgme_get_key (ctx, sig->fpr, r_key, 0); + + +File: gpgme.info, Node: Decrypt and Verify, Next: Sign, Prev: Verify, Up: Crypto Operations + +7.7.3 Decrypt and Verify +------------------------ + + -- Function: gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t CTX, + gpgme_data_t CIPHER, gpgme_data_t PLAIN) + The function `gpgme_op_decrypt_verify' decrypts the ciphertext in + the data object CIPHER and stores it into the data object PLAIN. + If CIPHER contains signatures, they will be verified. + + After the operation completed, `gpgme_op_decrypt_result' and + `gpgme_op_verify_result' can be used to retrieve more information + about the signatures. + + If the error code `GPG_ERR_NO_DATA' is returned, CIPHER does not + contain any data to decrypt. However, it might still be signed. + The information about detected signatures is available with + `gpgme_op_verify_result' in this case. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + ciphertext could be decrypted successfully, `GPG_ERR_INV_VALUE' if + CTX, CIPHER or PLAIN is not a valid pointer, `GPG_ERR_NO_DATA' if + CIPHER does not contain any data to decrypt, + `GPG_ERR_DECRYPT_FAILED' if CIPHER is not a valid cipher text, + `GPG_ERR_BAD_PASSPHRASE' if the passphrase for the secret key + could not be retrieved, and passes through any errors that are + reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t CTX, + gpgme_data_t CIPHER, gpgme_data_t PLAIN) + The function `gpgme_op_decrypt_verify_start' initiates a + `gpgme_op_decrypt_verify' operation. It can be completed by + calling `gpgme_wait' on the context. *Note Waiting For + Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, `GPG_ERR_INV_VALUE' if + CTX, CIPHER, PLAIN or R_STAT is not a valid pointer, and + `GPG_ERR_NO_DATA' if CIPHER does not contain any data to decrypt. + + +File: gpgme.info, Node: Sign, Next: Encrypt, Prev: Decrypt and Verify, Up: Crypto Operations + +7.7.4 Sign +---------- + +A signature can contain signatures by one or more keys. The set of +keys used to create a signatures is contained in a context, and is +applied to all following signing operations in this context (until the +set is changed). + +* Menu: + +* Selecting Signers:: How to choose the keys to sign with. +* Creating a Signature:: How to create a signature. +* Signature Notation Data:: How to add notation data to a signature. + + +File: gpgme.info, Node: Selecting Signers, Next: Creating a Signature, Up: Sign + +7.7.4.1 Selecting Signers +......................... + + -- Function: void gpgme_signers_clear (gpgme_ctx_t CTX) + The function `gpgme_signers_clear' releases a reference for each + key on the signers list and removes the list of signers from the + context CTX. + + Every context starts with an empty list. + + -- Function: gpgme_error_t gpgme_signers_add (gpgme_ctx_t CTX, + const gpgme_key_t KEY) + The function `gpgme_signers_add' adds the key KEY to the list of + signers in the context CTX. + + Calling this function acquires an additional reference for the key. + + -- Function: gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t CTX, + int SEQ) + The function `gpgme_signers_enum' returns the SEQth key in the + list of signers in the context CTX. An additional reference is + acquired for the user. + + If SEQ is out of range, `NULL' is returned. + + +File: gpgme.info, Node: Creating a Signature, Next: Signature Notation Data, Prev: Selecting Signers, Up: Sign + +7.7.4.2 Creating a Signature +............................ + + -- Data type: enum gpgme_sig_mode_t + The `gpgme_sig_mode_t' type is used to specify the desired type of + a signature. The following modes are available: + + `GPGME_SIG_MODE_NORMAL' + A normal signature is made, the output includes the plaintext + and the signature. + + `GPGME_SIG_MODE_DETACH' + A detached signature is made. + + `GPGME_SIG_MODE_CLEAR' + A clear text signature is made. The ASCII armor and text + mode settings of the context are ignored. + + -- Function: gpgme_error_t gpgme_op_sign (gpgme_ctx_t CTX, + gpgme_data_t PLAIN, gpgme_data_t SIG, gpgme_sig_mode_t MODE) + The function `gpgme_op_sign' creates a signature for the text in + the data object PLAIN and returns it in the data object SIG. The + type of the signature created is determined by the ASCII armor + (or, if that is not set, by the encoding specified for SIG), the + text mode attributes set for the context CTX and the requested + signature mode MODE. + + After the operation completed successfully, the result can be + retrieved with `gpgme_op_sign_result'. + + If an S/MIME signed message is created using the CMS crypto engine, + the number of certificates to include in the message can be + specified with `gpgme_set_include_certs'. *Note Included + Certificates::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + signature could be created successfully, `GPG_ERR_INV_VALUE' if + CTX, PLAIN or SIG is not a valid pointer, `GPG_ERR_NO_DATA' if the + signature could not be created, `GPG_ERR_BAD_PASSPHRASE' if the + passphrase for the secret key could not be retrieved, + `GPG_ERR_UNUSABLE_SECKEY' if there are invalid signers, and passes + through any errors that are reported by the crypto engine support + routines. + + -- Function: gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t CTX, + gpgme_data_t PLAIN, gpgme_data_t SIG, gpgme_sig_mode_t MODE) + The function `gpgme_op_sign_start' initiates a `gpgme_op_sign' + operation. It can be completed by calling `gpgme_wait' on the + context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if CTX, PLAIN or SIG is not a valid pointer. + + -- Data type: gpgme_new_signature_t + This is a pointer to a structure used to store a part of the + result of a `gpgme_op_sign' operation. The structure contains the + following members: + + `gpgme_new_signature_t next' + This is a pointer to the next new signature structure in the + linked list, or `NULL' if this is the last element. + + `gpgme_sig_mode_t type' + The type of this signature. + + `gpgme_pubkey_algo_t' + The public key algorithm used to create this signature. + + `gpgme_hash_algo_t' + The hash algorithm used to create this signature. + + `unsigned int sig_class' + The signature class of this signature. + + `long int timestamp' + The creation timestamp of this signature. + + `char *fpr' + The fingerprint of the key which was used to create this + signature. + + -- Data type: gpgme_sign_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_sign' operation. After successfully generating a + signature, you can retrieve the pointer to the result with + `gpgme_op_sign_result'. The structure contains the following + members: + + `gpgme_invalid_key_t invalid_signers' + A linked list with information about all invalid keys for + which a signature could not be created. + + `gpgme_new_signature_t signatures' + A linked list with information about all signatures created. + + -- Function: gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t CTX) + The function `gpgme_op_sign_result' returns a + `gpgme_sign_result_t' pointer to a structure holding the result of + a `gpgme_op_sign' operation. The pointer is only valid if the + last operation on the context was a `gpgme_op_sign', + `gpgme_op_sign_start', `gpgme_op_encrypt_sign' or + `gpgme_op_encrypt_sign_start' operation. If that operation + failed, the function might return a `NULL' pointer. The returned + pointer is only valid until the next operation is started on the + context. + + +File: gpgme.info, Node: Signature Notation Data, Prev: Creating a Signature, Up: Sign + +7.7.4.3 Signature Notation Data +............................... + +Using the following functions, you can attach arbitrary notation data +to a signature. This information is then available to the user when +the signature is verified. + + -- Function: void gpgme_sig_notation_clear (gpgme_ctx_t CTX) + The function `gpgme_sig_notation_clear' removes the notation data + from the context CTX. Subsequent signing operations from this + context will not include any notation data. + + Every context starts with an empty notation data list. + + -- Function: gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t CTX, + const char *NAME, const char *VALUE, + gpgme_sig_notation_flags_t FLAGS) + The function `gpgme_sig_notation_add' adds the notation data with + the name NAME and the value VALUE to the context CTX. + + Subsequent signing operations will include this notation data, as + well as any other notation data that was added since the creation + of the context or the last `gpgme_sig_notation_clear' operation. + + The arguments NAME and VALUE must be `NUL'-terminated strings in + human-readable form. The flag `GPGME_SIG_NOTATION_HUMAN_READABLE' + is implied (non-human-readable notation data is currently not + supported). The strings must be in UTF-8 encoding. + + If NAME is `NULL', then VALUE should be a policy URL. + + The function `gpgme_sig_notation_add' returns the error code + `GPG_ERR_NO_ERROR' if the notation data could be added + successfully, `GPG_ERR_INV_VALUE' if CTX is not a valid pointer, + or if NAME, VALUE and FLAGS are an invalid combination. The + function also passes through any errors that are reported by the + crypto engine support routines. + + -- Function: gpgme_sig_notation_t gpgme_sig_notation_get + (const gpgme_ctx_t CTX) + The function `gpgme_sig_notation_get' returns the linked list of + notation data structures that are contained in the context CTX. + + If CTX is not a valid pointer, or there is no notation data added + for this context, `NULL' is returned. + + +File: gpgme.info, Node: Encrypt, Prev: Sign, Up: Crypto Operations + +7.7.5 Encrypt +------------- + +One plaintext can be encrypted for several recipients at the same time. +The list of recipients is created independently of any context, and +then passed to the encryption operation. + +* Menu: + +* Encrypting a Plaintext:: How to encrypt a plaintext. + + +File: gpgme.info, Node: Encrypting a Plaintext, Up: Encrypt + +7.7.5.1 Encrypting a Plaintext +.............................. + + -- Function: gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t CTX, + gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS, + gpgme_data_t PLAIN, gpgme_data_t CIPHER) + The function `gpgme_op_encrypt' encrypts the plaintext in the data + object PLAIN for the recipients RECP and stores the ciphertext in + the data object CIPHER. The type of the ciphertext created is + determined by the ASCII armor (or, if that is not set, by the + encoding specified for CIPHER) and the text mode attributes set + for the context CTX. + + KEY must be a `NULL'-terminated array of keys. The user must keep + references for all keys during the whole duration of the call (but + see `gpgme_op_encrypt_start' for the requirements with the + asynchronous variant). + + The value in FLAGS is a bitwise-or combination of one or multiple + of the following bit values: + + `GPGME_ENCRYPT_ALWAYS_TRUST' + The `GPGME_ENCRYPT_ALWAYS_TRUST' symbol specifies that all the + recipients in RECP should be trusted, even if the keys do not + have a high enough validity in the keyring. This flag should + be used with care; in general it is not a good idea to use + any untrusted keys. + + `GPGME_ENCRYPT_NO_ENCRYPT_TO' + The `GPGME_ENCRYPT_NO_ENCRYPT_TO' symbol specifies that no + default or hidden default recipients as configured in the + crypto backend should be included. This can be useful for + managing different user profiles. + + If `GPG_ERR_UNUSABLE_PUBKEY' is returned, some recipients in RECP + are invalid, but not all. In this case the plaintext might be + encrypted for all valid recipients and returned in CIPHER (if this + happens depends on the crypto engine). More information about the + invalid recipients is available with `gpgme_op_encrypt_result'. + + If RECP is `NULL', symmetric rather than public key encryption is + performed. Symmetrically encrypted cipher text can be deciphered + with `gpgme_op_decrypt'. Note that in this case the crypto + backend needs to retrieve a passphrase from the user. Symmetric + encryption is currently only supported for the OpenPGP crypto + backend. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + ciphertext could be created successfully, `GPG_ERR_INV_VALUE' if + CTX, RECP, PLAIN or CIPHER is not a valid pointer, + `GPG_ERR_UNUSABLE_PUBKEY' if RECP contains some invalid + recipients, `GPG_ERR_BAD_PASSPHRASE' if the passphrase for the + symmetric key could not be retrieved, and passes through any + errors that are reported by the crypto engine support routines. + + -- Function: gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t CTX, + gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS, + gpgme_data_t PLAIN, gpgme_data_t CIPHER) + The function `gpgme_op_encrypt_start' initiates a + `gpgme_op_encrypt' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + References to the keys only need to be held for the duration of + this call. The user can release its references to the keys after + this function returns, even if the operation is not yet finished. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, `GPG_ERR_INV_VALUE' if + CTX, RSET, PLAIN or CIPHER is not a valid pointer, and + `GPG_ERR_UNUSABLE_PUBKEY' if RSET does not contain any valid + recipients. + + -- Data type: gpgme_encrypt_result_t + This is a pointer to a structure used to store the result of a + `gpgme_op_encrypt' operation. After successfully encrypting data, + you can retrieve the pointer to the result with + `gpgme_op_encrypt_result'. The structure contains the following + members: + + `gpgme_invalid_key_t invalid_recipients' + A linked list with information about all invalid keys for + which the data could not be encrypted. + + -- Function: gpgme_encrypt_result_t gpgme_op_encrypt_result + (gpgme_ctx_t CTX) + The function `gpgme_op_encrypt_result' returns a + `gpgme_encrypt_result_t' pointer to a structure holding the result + of a `gpgme_op_encrypt' operation. The pointer is only valid if + the last operation on the context was a `gpgme_op_encrypt', + `gpgme_op_encrypt_start', `gpgme_op_sign' or `gpgme_op_sign_start' + operation. If this operation failed, this might be a `NULL' + pointer. The returned pointer is only valid until the next + operation is started on the context. + + -- Function: gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t CTX, + gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS, + gpgme_data_t PLAIN, gpgme_data_t CIPHER) + The function `gpgme_op_encrypt_sign' does a combined encrypt and + sign operation. It is used like `gpgme_op_encrypt', but the + ciphertext also contains signatures for the signers listed in CTX. + + The combined encrypt and sign operation is currently only available + for the OpenPGP crypto engine. + + -- Function: gpgme_error_t gpgme_op_encrypt_sign_start + (gpgme_ctx_t CTX, gpgme_key_t RECP, + gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN, + gpgme_data_t CIPHER) + The function `gpgme_op_encrypt_sign_start' initiates a + `gpgme_op_encrypt_sign' operation. It can be completed by calling + `gpgme_wait' on the context. *Note Waiting For Completion::. + + The function returns the error code `GPG_ERR_NO_ERROR' if the + operation could be started successfully, and `GPG_ERR_INV_VALUE' + if CTX, RSET, PLAIN or CIPHER is not a valid pointer. + + +File: gpgme.info, Node: Run Control, Prev: Crypto Operations, Up: Contexts + +7.8 Run Control +=============== + +GPGME supports running operations synchronously and asynchronously. +You can use asynchronous operation to set up a context up to initiating +the desired operation, but delay performing it to a later point. + + Furthermore, you can use an external event loop to control exactly +when GPGME runs. This ensures that GPGME only runs when necessary and +also prevents it from blocking for a long time. + +* Menu: + +* Waiting For Completion:: Waiting until an operation is completed. +* Using External Event Loops:: Advanced control over what happens when. +* Cancellation:: How to end pending operations prematurely. + + +File: gpgme.info, Node: Waiting For Completion, Next: Using External Event Loops, Up: Run Control + +7.8.1 Waiting For Completion +---------------------------- + + -- Function: gpgme_ctx_t gpgme_wait (gpgme_ctx_t CTX, + gpgme_error_t *STATUS, int HANG) + The function `gpgme_wait' continues the pending operation within + the context CTX. In particular, it ensures the data exchange + between GPGME and the crypto backend and watches over the run time + status of the backend process. + + If HANG is true, the function does not return until the operation + is completed or cancelled. Otherwise the function will not block + for a long time. + + The error status of the finished operation is returned in STATUS + if `gpgme_wait' does not return `NULL'. + + The CTX argument can be `NULL'. In that case, `gpgme_wait' waits + for any context to complete its operation. + + `gpgme_wait' can be used only in conjunction with any context that + has a pending operation initiated with one of the + `gpgme_op_*_start' functions except `gpgme_op_keylist_start' and + `gpgme_op_trustlist_start' (for which you should use the + corresponding `gpgme_op_*_next' functions). If CTX is `NULL', all + of such contexts are waited upon and possibly returned. + Synchronous operations running in parallel, as well as key and + trust item list operations, do not affect `gpgme_wait'. + + In a multi-threaded environment, only one thread should ever call + `gpgme_wait' at any time, irregardless if CTX is specified or not. + This means that all calls to this function should be fully + synchronized by locking primitives. It is safe to start + asynchronous operations while a thread is running in `gpgme_wait'. + + The function returns the CTX of the context which has finished the + operation. If HANG is false, and the timeout expires, `NULL' is + returned and `*status' will be set to 0. If an error occurs, + `NULL' is returned and the error is returned in `*status'. + + +File: gpgme.info, Node: Using External Event Loops, Next: Cancellation, Prev: Waiting For Completion, Up: Run Control + +7.8.2 Using External Event Loops +-------------------------------- + +GPGME hides the complexity of the communication between the library and +the crypto engine. The price of this convenience is that the calling +thread can block arbitrary long waiting for the data returned by the +crypto engine. In single-threaded programs, in particular if they are +interactive, this is an unwanted side-effect. OTOH, if `gpgme_wait' is +used without the HANG option being enabled, it might be called +unnecessarily often, wasting CPU time that could be used otherwise. + + The I/O callback interface described in this section lets the user +take control over what happens when. GPGME will provide the user with +the file descriptors that should be monitored, and the callback +functions that should be invoked when a file descriptor is ready for +reading or writing. It is then the user's responsibility to decide +when to check the file descriptors and when to invoke the callback +functions. Usually this is done in an event loop, that also checks for +events in other parts of the program. If the callback functions are +only called when the file descriptors are ready, GPGME will never +block. This gives the user more control over the program flow, and +allows to perform other tasks when GPGME would block otherwise. + + By using this advanced mechanism, GPGME can be integrated smoothly +into GUI toolkits like GTK+ even for single-threaded programs. + +* Menu: + +* I/O Callback Interface:: How I/O callbacks are registered. +* Registering I/O Callbacks:: How to use I/O callbacks for a context. +* I/O Callback Example:: An example how to use I/O callbacks. +* I/O Callback Example GTK+:: How to use GPGME with GTK+. +* I/O Callback Example GDK:: How to use GPGME with GDK. +* I/O Callback Example Qt:: How to use GPGME with Qt. + + +File: gpgme.info, Node: I/O Callback Interface, Next: Registering I/O Callbacks, Up: Using External Event Loops + +7.8.2.1 I/O Callback Interface +.............................. + + -- Data type: gpgme_error_t (*gpgme_io_cb_t) (void *DATA, int FD) + The `gpgme_io_cb_t' type is the type of functions which GPGME + wants to register as I/O callback handlers using the + `gpgme_register_io_cb_t' functions provided by the user. + + DATA and FD are provided by GPGME when the I/O callback handler is + registered, and should be passed through to the handler when it is + invoked by the user because it noticed activity on the file + descriptor FD. + + The callback handler always returns `0', but you should consider + the return value to be reserved for later use. + + -- Data type: gpgme_error_t (*gpgme_register_io_cb_t) (void *DATA, +int FD, int DIR, gpgme_io_cb_t FNC, void *FNC_DATA, void **TAG) + The `gpgme_register_io_cb_t' type is the type of functions which + can be called by GPGME to register an I/O callback function FNC + for the file descriptor FD with the user. FNC_DATA should be + passed as the first argument to FNC when the handler is invoked + (the second argument should be FD). If DIR is 0, FNC should be + called by the user when FD is ready for writing. If DIR is 1, FNC + should be called when FD is ready for reading. + + DATA was provided by the user when registering the + `gpgme_register_io_cb_t' function with GPGME and will always be + passed as the first argument when registering a callback function. + For example, the user can use this to determine the event loop to + which the file descriptor should be added. + + GPGME will call this function when a crypto operation is initiated + in a context for which the user has registered I/O callback + handler functions with `gpgme_set_io_cbs'. It can also call this + function when it is in an I/O callback handler for a file + descriptor associated to this context. + + The user should return a unique handle in TAG identifying this I/O + callback registration, which will be passed to the + `gpgme_register_io_cb_t' function without interpretation when the + file descriptor should not be monitored anymore. + + -- Data type: void (*gpgme_remove_io_cb_t) (void *TAG) + The `gpgme_remove_io_cb_t' type is the type of functions which can + be called by GPGME to remove an I/O callback handler that was + registered before. TAG is the handle that was returned by the + `gpgme_register_io_cb_t' for this I/O callback. + + GPGME can call this function when a crypto operation is in an I/O + callback. It will also call this function when the context is + destroyed while an operation is pending. + + -- Data type: enum gpgme_event_io_t + The `gpgme_event_io_t' type specifies the type of an event that is + reported to the user by GPGME as a consequence of an I/O + operation. The following events are defined: + + `GPGME_EVENT_START' + The operation is fully initialized now, and you can start to + run the registered I/O callback handlers now. Note that + registered I/O callback handlers must not be run before this + event is signalled. TYPE_DATA is `NULL' and reserved for + later use. + + `GPGME_EVENT_DONE' + The operation is finished, the last I/O callback for this + operation was removed. The accompanying TYPE_DATA points to a + `gpgme_error_t' variable that contains the status of the + operation that finished. This event is signalled after the + last I/O callback has been removed. + + `GPGME_EVENT_NEXT_KEY' + In a `gpgme_op_keylist_start' operation, the next key was + received from the crypto engine. The accompanying TYPE_DATA + is a `gpgme_key_t' variable that contains the key with one + reference for the user. + + `GPGME_EVENT_NEXT_TRUSTITEM' + In a `gpgme_op_trustlist_start' operation, the next trust item + was received from the crypto engine. The accompanying + TYPE_DATA is a `gpgme_trust_item_t' variable that contains + the trust item with one reference for the user. + + -- Data type: void (*gpgme_event_io_cb_t) (void *DATA, +gpgme_event_io_t TYPE, void *TYPE_DATA) + The `gpgme_event_io_cb_t' type is the type of functions which can + be called by GPGME to signal an event for an operation running in + a context which has I/O callback functions registered by the user. + + DATA was provided by the user when registering the + `gpgme_event_io_cb_t' function with GPGME and will always be + passed as the first argument when registering a callback function. + For example, the user can use this to determine the context in + which this event has occured. + + TYPE will specify the type of event that has occured. TYPE_DATA + specifies the event further, as described in the above list of + possible `gpgme_event_io_t' types. + + GPGME can call this function in an I/O callback handler. + + +File: gpgme.info, Node: Registering I/O Callbacks, Next: I/O Callback Example, Prev: I/O Callback Interface, Up: Using External Event Loops + +7.8.2.2 Registering I/O Callbacks +................................. + + -- Data type: struct gpgme_io_cb_ts + This structure is used to store the I/O callback interface + functions described in the previous section. It has the following + members: + + `gpgme_register_io_cb_t add' + This is the function called by GPGME to register an I/O + callback handler. It must be specified. + + `void *add_data' + This is passed as the first argument to the `add' function + when it is called by GPGME. For example, it can be used to + determine the event loop to which the file descriptor should + be added. + + `gpgme_remove_io_cb_t remove' + This is the function called by GPGME to remove an I/O + callback handler. It must be specified. + + `gpgme_event_io_cb_t event' + This is the function called by GPGME to signal an event for + an operation. It must be specified, because at least the + start event must be processed. + + `void *event_data' + This is passed as the first argument to the `event' function + when it is called by GPGME. For example, it can be used to + determine the context in which the event has occured. + + -- Function: void gpgme_set_io_cbs (gpgme_ctx_t CTX, + struct gpgme_io_cb_ts *IO_CBS) + The function `gpgme_set_io_cbs' enables the I/O callback interface + for the context CTX. The I/O callback functions are specified by + IO_CBS. + + If IO_CBS->`add' is `NULL', the I/O callback interface is disabled + for the context, and normal operation is restored. + + -- Function: void gpgme_get_io_cbs (gpgme_ctx_t CTX, + struct gpgme_io_cb_ts *IO_CBS) + The function `gpgme_get_io_cbs' returns the I/O callback functions + set with `gpgme_set_io_cbs' in IO_CBS. + + +File: gpgme.info, Node: I/O Callback Example, Next: I/O Callback Example GTK+, Prev: Registering I/O Callbacks, Up: Using External Event Loops + +7.8.2.3 I/O Callback Example +............................ + +To actually use an external event loop, you have to implement the I/O +callback functions that are used by GPGME to register and unregister +file descriptors. Furthermore, you have to actually monitor these file +descriptors for activity and call the appropriate I/O callbacks. + + The following example illustrates how to do that. The example uses +locking to show in which way the callbacks and the event loop can run +concurrently. For the event loop, we use a fixed array. For a +real-world implementation, you should use a dynamically sized structure +because the number of file descriptors needed for a crypto operation in +GPGME is not predictable. + + #include <assert.h> + #include <errno.h> + #include <stdlib.h> + #include <pthread.h> + #include <sys/types.h> + #include <gpgme.h> + + /* The following structure holds the result of a crypto operation. */ + struct op_result + { + int done; + gpgme_error_t err; + }; + + /* The following structure holds the data associated with one I/O + callback. */ + struct one_fd + { + int fd; + int dir; + gpgme_io_cb_t fnc; + void *fnc_data; + void *loop; + }; + + struct event_loop + { + pthread_mutex_t lock; + #define MAX_FDS 32 + /* Unused slots are marked with FD being -1. */ + struct one_fd fds[MAX_FDS]; + }; + + The following functions implement the I/O callback interface. + + gpgme_error_t + add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data, + void **r_tag) + { + struct event_loop *loop = data; + struct one_fd *fds = loop->fds; + int i; + + pthread_mutex_lock (&loop->lock); + for (i = 0; i < MAX_FDS; i++) + { + if (fds[i].fd == -1) + { + fds[i].fd = fd; + fds[i].dir = dir; + fds[i].fnc = fnc; + fds[i].fnc_data = fnc_data; + fds[i].loop = loop; + break; + } + } + pthread_mutex_unlock (&loop->lock); + if (i == MAX_FDS) + return gpg_error (GPG_ERR_GENERAL); + *r_tag = &fds[i]; + return 0; + } + + void + remove_io_cb (void *tag) + { + struct one_fd *fd = tag; + struct event_loop *loop = fd->loop; + + pthread_mutex_lock (&loop->lock); + fd->fd = -1; + pthread_mutex_unlock (&loop->lock); + } + + void + event_io_cb (void *data, gpgme_event_io_t type, void *type_data) + { + struct op_result *result = data; + + /* We don't support list operations here. */ + if (type == GPGME_EVENT_DONE) + { + result->done = 1; + result->err = *type_data; + } + } + + The final missing piece is the event loop, which will be presented +next. We only support waiting for the success of a single operation. + + int + do_select (struct event_loop *loop) + { + fd_set rfds; + fd_set wfds; + int i, n; + int any = 0; + struct one_fd *fdlist = loop->fds; + + pthread_mutex_lock (&loop->lock); + FD_ZERO (&rfds); + FD_ZERO (&wfds); + for (i = 0; i < MAX_FDS; i++) + if (fdlist[i].fd != -1) + FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds); + pthread_mutex_unlock (&loop->unlock); + + do + { + n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0); + } + while (n < 0 && errno == EINTR); + + if (n < 0) + return n; /* Error or timeout. */ + + pthread_mutex_lock (&loop->lock); + for (i = 0; i < MAX_FDS && n; i++) + { + if (fdlist[i].fd != -1) + { + if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds)) + { + assert (n); + n--; + any = 1; + /* The I/O callback handler can register/remove callbacks, + so we have to unlock the file descriptor list. */ + pthread_mutex_unlock (&loop->lock); + (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd); + pthread_mutex_lock (&loop->lock); + } + } + } + pthread_mutex_unlock (&loop->lock); + return any; + } + + void + wait_for_op (struct event_loop *loop, struct op_result *result) + { + int ret; + + do + { + ret = do_select (loop); + } + while (ret >= 0 && !result->done); + } + + The main function shows how to put it all together. + + int + main (int argc, char *argv[]) + { + struct event_loop loop; + struct op_result result; + gpgme_ctx_t ctx; + gpgme_error_t err; + gpgme_data_t sig, text; + int i; + struct gpgme_io_cb_ts io_cbs = + { + add_io_cb, + &loop, + remove_io_cb, + event_io_cb, + &result + }; + + init_gpgme (void); + + /* Initialize the loop structure. */ + pthread_mutex_init (&loop.lock, NULL); + for (i = 0; i < MAX_FDS; i++) + loop->fds[i].fd = -1; + + /* Initialize the result structure. */ + result.done = 0; + + err = gpgme_data_new_from_file (&sig, "signature", 1); + if (!err) + err = gpgme_data_new_from_file (&text, "text", 1); + if (!err) + err = gpgme_new (&ctx); + if (!err) + { + gpgme_set_io_cbs (ctx, &io_cbs); + err = gpgme_op_verify_start (ctx, sig, text, NULL); + } + if (err) + { + fprintf (stderr, "gpgme error: %s: %s\n", + gpgme_strsource (err), gpgme_strerror (err)); + exit (1); + } + + wait_for_op (&loop, &result); + if (!result.done) + { + fprintf (stderr, "select error\n"); + exit (1); + } + if (!result.err) + { + fprintf (stderr, "verification failed: %s: %s\n", + gpgme_strsource (result.err), gpgme_strerror (result.err)); + exit (1); + } + /* Evaluate verify result. */ + ... + return 0; + } + + +File: gpgme.info, Node: I/O Callback Example GTK+, Next: I/O Callback Example GDK, Prev: I/O Callback Example, Up: Using External Event Loops + +7.8.2.4 I/O Callback Example GTK+ +................................. + +The I/O callback interface can be used to integrate GPGME with the GTK+ +event loop. The following code snippets shows how this can be done +using the appropriate register and remove I/O callback functions. In +this example, the private data of the register I/O callback function is +unused. The event notifications is missing because it does not require +any GTK+ specific setup. + + #include <gtk/gtk.h> + + struct my_gpgme_io_cb + { + gpgme_io_cb_t fnc; + void *fnc_data; + guint input_handler_id + }; + + void + my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) + { + struct my_gpgme_io_cb *iocb = data; + (*(iocb->fnc)) (iocb->data, source); + } + + void + my_gpgme_remove_io_cb (void *data) + { + struct my_gpgme_io_cb *iocb = data; + gtk_input_remove (data->input_handler_id); + } + + void + my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc, + void *fnc_data, void **tag) + { + struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); + iocb->fnc = fnc; + iocb->data = fnc_data; + iocb->input_handler_id = gtk_input_add_full (fd, dir + ? GDK_INPUT_READ + : GDK_INPUT_WRITE, + my_gpgme_io_callback, + 0, iocb, NULL); + *tag = iocb; + return 0; + } + + +File: gpgme.info, Node: I/O Callback Example GDK, Next: I/O Callback Example Qt, Prev: I/O Callback Example GTK+, Up: Using External Event Loops + +7.8.2.5 I/O Callback Example GDK +................................ + +The I/O callback interface can also be used to integrate GPGME with the +GDK event loop. The following code snippets shows how this can be done +using the appropriate register and remove I/O callback functions. In +this example, the private data of the register I/O callback function is +unused. The event notifications is missing because it does not require +any GDK specific setup. + + It is very similar to the GTK+ example in the previous section. + + #include <gdk/gdk.h> + + struct my_gpgme_io_cb + { + gpgme_io_cb_t fnc; + void *fnc_data; + gint tag; + }; + + void + my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) + { + struct my_gpgme_io_cb *iocb = data; + (*(iocb->fnc)) (iocb->data, source); + } + + void + my_gpgme_remove_io_cb (void *data) + { + struct my_gpgme_io_cb *iocb = data; + gdk_input_remove (data->tag); + } + + void + my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc, + void *fnc_data, void **tag) + { + struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); + iocb->fnc = fnc; + iocb->data = fnc_data; + iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE, + my_gpgme_io_callback, iocb, NULL); + *tag = iocb; + return 0; + } + + +File: gpgme.info, Node: I/O Callback Example Qt, Prev: I/O Callback Example GDK, Up: Using External Event Loops + +7.8.2.6 I/O Callback Example Qt +............................... + +The I/O callback interface can also be used to integrate GPGME with the +Qt event loop. The following code snippets show how this can be done +using the appropriate register and remove I/O callback functions. In +this example, the private data of the register I/O callback function is +unused. The event notifications is missing because it does not require +any Qt specific setup. + + #include <qsocketnotifier.h> + #include <qapplication.h> + + struct IOCB { + IOCB( GpgmeIOCb f, void * d, QSocketNotifier * n ) + : func( f ), data( d ), notifier( n ) {} + GpgmeIOCb func; + void * data; + QSocketNotifier * notifier; + } + + class MyApp : public QApplication { + + // ... + + static void registerGpgmeIOCallback( void * data, int fd, int dir, + GpgmeIOCb func, void * func_data, + void ** tag ) { + QSocketNotifier * n = + new QSocketNotifier( fd, dir ? QSocketNotifier::Read + : QSocketNotifier::Write ); + connect( n, SIGNAL(activated(int)), + qApp, SLOT(slotGpgmeIOCallback(int)) ); + qApp->mIOCBs.push_back( IOCB( func, func_data, n ) ); + *tag = (void*)n; + } + + static void removeGpgmeIOCallback( void * tag ) { + if ( !tag ) return; + QSocketNotifier * n = static_cast<QSocketNotifier*>( tag ); + for ( QValueList<IOCB>::iterator it = qApp->mIOCBs.begin() ; + it != qApp->mIOCBs.end() ; ++it ) + if ( it->notifier == n ) { + delete it->notifier; + qApp->mIOCBs.erase( it ); + return; + } + } + + public slots: + void slotGpgmeIOCallback( int fd ) { + for ( QValueList<IOCB>::const_iterator it = mIOCBs.begin() ; + it != mIOCBs.end() ; ++it ) + if ( it->notifier && it->notifier->socket() == fd ) + (*(it->func)) ( it->func_data, fd ); + } + + // ... + + private: + QValueList<IOCB> mIOCBs; + // ... + }; + + +File: gpgme.info, Node: Cancellation, Prev: Using External Event Loops, Up: Run Control + +7.8.3 Cancellation +------------------ + +Sometimes you do not want to wait for an operation to finish. GPGME +provides two different functions to achieve that. The function +`gpgme_cancel' takes effect immediately. When it returns, the +operation is effectively canceled. However, it has some limitations +and can not be used with synchronous operations. In contrast, the +function `gpgme_cancel_async' can be used with any context and from any +thread, but it is not guaranteed to take effect immediately. Instead, +cancellation occurs at the next possible time (typically the next time +I/O occurs in the target context). + + -- Function: gpgme_ctx_t gpgme_cancel (gpgme_ctx_t CTX) + The function `gpgme_cancel' attempts to cancel a pending operation + in the context CTX. This only works if you use the global event + loop or your own event loop. + + If you use the global event loop, you must not call `gpgme_wait' + or `gpgme_wait' during cancellation. After successful + cancellation, you can call `gpgme_wait' (optionally waiting on + CTX), and the context CTX will appear as if it had finished with + the error code `GPG_ERR_CANCEL'. + + If you use your an external event loop, you must ensure that no I/O + callbacks are invoked for this context (for example by halting the + event loop). On successful cancellation, all registered I/O + callbacks for this context will be unregistered, and a + `GPGME_EVENT_DONE' event with the error code `GPG_ERR_CANCEL' will + be signaled. + + The function returns an error code if the cancellation failed (in + this case the state of CTX is not modified). + + -- Function: gpgme_ctx_t gpgme_cancel_async (gpgme_ctx_t CTX) + The function `gpgme_cancel' attempts to cancel a pending operation + in the context CTX. This can be called by any thread at any time + after starting an operation on the context, but will not take + effect immediately. The actual cancellation happens at the next + time GPGME processes I/O in that context. + + The function returns an error code if the cancellation failed (in + this case the state of CTX is not modified). + + +File: gpgme.info, Node: UI Server Protocol, Next: Library Copying, Prev: Contexts, Up: Top + +Appendix A The GnuPG UI Server Protocol +*************************************** + +This section specifies the protocol used between clients and a User +Interface Server (UI server). This protocol helps to build a system +where all cryptographic operations are done by a server and the server +is responsible for all dialogs. Although GPGME has no direct support +for this protocol it is believed that servers will utilize the GPGME +library; thus having the specification included in this manual is an +appropriate choice. This protocol should be referenced as `The GnuPG +UI Server Protocol'. + +A server needs to implement these commands:(1) + +* Menu: + +* UI Server Encrypt:: Encrypt a message. +* UI Server Sign:: Sign a message. +* UI Server Decrypt:: Decrypt a message. +* UI Server Verify:: Verify a message. +* UI Server Set Input Files:: Specifying the input files to operate on. +* UI Server Sign/Encrypt Files:: Encrypting and signing files. +* UI Server Verify/Decrypt Files:: Decrypting and verifying files. +* UI Server Import/Export Keys:: Managing certificates. +* UI Server Checksum Files:: Create and verify checksums for files. +* Miscellaneous UI Server Commands:: Commands not related to a specific operation. + + ---------- Footnotes ---------- + + (1) In all examples we assume that the connection has already been +established; see the Assuan manual for details. + + +File: gpgme.info, Node: UI Server Encrypt, Next: UI Server Sign, Up: UI Server Protocol + +A.1 UI Server: Encrypt a Message +================================ + +Before encryption can be done the recipients must be set using the +command: + + -- Command: RECIPIENT STRING + Set the recipient for the encryption. STRING is an RFC-2822 + recipient name ("mailbox" as per section 3.4). This command may + or may not check the recipient for validity right away; if it does + not all recipients are expected to be checked at the time of the + `ENCRYPT' command. All `RECIPIENT' commands are cumulative until a + successful `ENCRYPT' command or until a `RESET' command. + Linefeeds are obviously not allowed in STRING and should be folded + into spaces (which are equivalent). + +To tell the server the source and destination of the data, the next two +commands are to be used: + + -- Command: INPUT FD=N + Set the file descriptor for the message to be encrypted to N. The + message send to the server is binary encoded. + + GpgOL is a Windows only program, thus N is not a libc file + descriptor but a regular system handle. Given that the Assuan + connection works over a socket, it is not possible to use regular + inheritance to make the file descriptor available to the server. + Thus `DuplicateHandle' needs to be used to duplicate a handle to + the server process. This is the reason that the server needs to + implement the `GETINFO pid' command. Sending this command a second + time replaces the file descriptor set by the last one. + + -- Command: OUTPUT FD=N + Set the file descriptor to be used for the output (i.e. the + encrypted message) to N. For OpenPGP, the output needs to be + ASCII armored; for CMS, the output needs to be Base-64 encoded. + For details on the file descriptor, see the `INPUT' command. + +The setting of the recipients, the data source and destination may +happen in any order, even intermixed. If this has been done the actual +encryption operation is called using: + + -- Command: ENCRYPT --protocol=NAME + This command reads the plaintext from the file descriptor set by + the `INPUT' command, encrypts it and writes the ciphertext to the + file descriptor set by the `OUTPUT' command. The server may (and + should) overlap reading and writing. The recipients used for the + encryption are all the recipients set so far. If any recipient is + not usable the server should take appropriate measures to notify + the user about the problem and may cancel the operation by + returning an error code. The used file descriptors are void after + this command; the recipient list is only cleared if the server + returns success. + + Because GpgOL uses a streaming mode of operation the server is not + allowed to auto select the protocol and must obey to the mandatory + PROTOCOL parameter: + + `OpenPGP' + Use the OpenPGP protocol (RFC-2440). + + `CMS' + Use the CMS (PKCS#7) protocol (RFC-3852). + + + To support automagically selection of the protocol depending on the +selected keys, the server MAY implement the command: + + -- Command: PREP_ENCRYPT [--protocol=NAME] [--expect-sign] + This commands considers all recipients set so far and decides + whether it is able to take input and start the actual encryption. + This is kind of a dry-run `ENCRYPT' without requiring or using the + input and output file descriptors. The server shall cache the + result of any user selection to avoid asking this again when the + actual `ENCRYPT' command is send. The `--protocol' option is + optional; if it is not given, the server should allow the user to + select the protocol to be used based on the recipients given or by + any other means. + + If `--expect-sign' is given the server should expect that the + message will also be signed and use this hint to present a unified + recipient and signer selection dialog if possible and desired. A + selected signer should then be cached for the expected SIGN command + (which is expected in the same session but possible on another + connection). + + If this command is given again before a successful `ENCRYPT' + command, the second one takes effect. + + Before sending the OK response the server shall tell the client the + protocol to be used (either the one given by the argument or the + one selected by the user) by means of a status line: + + -- Status line: PROTOCOL NAME + Advise the client to use the protocol NAME for the `ENCRYPT' + command. The valid protocol names are listed under the + description of the `ENCRYPT' command. The server shall emit + exactly one PROTOCOL status line. + +Here is an example of a complete encryption sequence; client lines are +indicated by a C:, server responses by C:: + + C: RESET + S: OK + C: RECIPIENT foo@example.net + S: OK + C: RECIPIENT bar@example.com + S: OK + C: PREP_ENCRYPT + S: S PROTOCOL OpenPGP + S: OK + C: INPUT FD=17 + S: OK + C: OUTPUT FD=18 + S: OK + C: ENCRYPT + S: OK + + +File: gpgme.info, Node: UI Server Sign, Next: UI Server Decrypt, Prev: UI Server Encrypt, Up: UI Server Protocol + +A.2 UI Server: Sign a Message +============================= + +The server needs to implement opaque signing as well as detached +signing. Due to the nature of OpenPGP messages it is always required to +send the entire message to the server; sending just the hash is not +possible. The following two commands are required to set the input and +output file descriptors: + + -- Command: INPUT FD=N + Set the file descriptor for the message to be signed to N. The + message send to the server is binary encoded. For details on the + file descriptor, see the description of `INPUT' in the `ENCRYPT' + section. + + -- Command: OUTPUT FD=N + Set the file descriptor to be used for the output. The output is + either the complete signed message or in case of a detached + signature just that detached signature. For OpenPGP, the output + needs to be ASCII armored; for CMS, the output needs to be Base-64 + encoded. For details on the file descriptor, see the `INPUT' + command. + +To allow the server the selection of a non-default signing key the +client may optionally use the `SENDER' command, see *note command +SENDER::. + +The signing operation is then initiated by: + + -- Command: SIGN --protocol=NAME [--detached] + Sign the data set with the `INPUT' command and write it to the sink + set by OUTPUT. NAME is the signing protocol used for the message. + For a description of the allowed protocols see the `ENCRYPT' + command. With option `--detached' given, a detached signature is + created; this is actually the usual way the command is used. + +The client expects the server to send at least this status information +before the final OK response: + + -- Status line: MICALG STRING + The STRING represents the hash algorithm used to create the + signature. It is used with MOSS style signature messages and + defined by PGP/MIME (RFC-3156) and S/MIME (RFC-3851). The GPGME + library has a supporting function `gpgme_hash_algo_name' to return + the algorithm name as a string. This string needs to be + lowercased and for OpenPGP prefixed with "`pgp-'". + + +File: gpgme.info, Node: UI Server Decrypt, Next: UI Server Verify, Prev: UI Server Sign, Up: UI Server Protocol + +A.3 UI Server: Decrypt a Message +================================ + +Decryption may include the verification of OpenPGP messages. This is +due to the often used combined signing/encryption modus of OpenPGP. The +client may pass an option to the server to inhibit the signature +verification. The following two commands are required to set the input +and output file descriptors: + + -- Command: INPUT FD=N + Set the file descriptor for the message to be decrypted to N. The + message send to the server is either binary encoded or -- in the + case of OpenPGP -- ASCII armored. For details on the file + descriptor, see the description of `INPUT' in the `ENCRYPT' + section. + + -- Command: OUTPUT FD=N + Set the file descriptor to be used for the output. The output is + binary encoded. For details on the file descriptor, see the + description of `INPUT' in the `ENCRYPT' section. + +The decryption is started with the command: + + -- Command: DECRYPT --protocol=NAME [--no-verify] + NAME is the encryption protocol used for the message. For a + description of the allowed protocols see the `ENCRYPT' command. + This argument is mandatory. If the option `--no-verify' is given, + the server should not try to verify a signature, in case the input + data is an OpenPGP combined message. + + +File: gpgme.info, Node: UI Server Verify, Next: UI Server Set Input Files, Prev: UI Server Decrypt, Up: UI Server Protocol + +A.4 UI Server: Verify a Message +=============================== + +The server needs to support the verification of opaque signatures as +well as detached signatures. The kind of input sources controls what +kind message is to be verified. + + -- Command: MESSAGE FD=N + This command is used with detached signatures to set the file + descriptor for the signed data to N. The data is binary encoded + (used verbatim). For details on the file descriptor, see the + description of `INPUT' in the `ENCRYPT' section. + + -- Command: INPUT FD=N + Set the file descriptor for the opaque message or the signature + part of a detached signature to N. The message send to the server + is either binary encoded or - in the case of OpenPGP - ASCII + armored. For details on the file descriptor, see the description + of `INPUT' in the `ENCRYPT' section. + + -- Command: OUTPUT FD=N + Set the file descriptor to be used for the output. The output is + binary encoded and only used for opaque signatures. For details + on the file descriptor, see the description of `INPUT' in the + `ENCRYPT' section. + +The verification is then started using: + + -- Command: VERIFY --protocol=NAME [--silent] + NAME is the signing protocol used for the message. For a + description of the allowed protocols see the `ENCRYPT' command. + This argument is mandatory. Depending on the combination of + `MESSAGE' `INPUT' and `OUTPUT' commands, the server needs to + select the appropriate verification mode: + + MESSAGE and INPUT + This indicates a detached signature. Output data is not + applicable. + + INPUT + This indicates an opaque signature. As no output command has + been given, the server is only required to check the + signature. + + INPUT and OUTPUT + This indicates an opaque signature. The server shall write + the signed data to the file descriptor set by the output + command. This data shall even be written if the signatures + can't be verified. + + With `--silent' the server shall not display any dialog; this is for +example used by the client to get the content of opaque signed +messages. The client expects the server to send at least this status +information before the final OK response: + + -- Status line: SIGSTATUS FLAG DISPLAYSTRING + Returns the status for the signature and a short string explaining + the status. Valid values for FLAG are: + + `none' + The message has a signature but it could not not be verified + due to a missing key. + + `green' + The signature is fully valid. + + `yellow' + The signature is valid but additional information was shown + regarding the validity of the key. + + `red' + The signature is not valid. + + DISPLAYSTRING is a percent-and-plus-encoded string with a short + human readable description of the status. For example + + S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@example.net> + + Note that this string needs to fit into an Assuan line and should + be short enough to be displayed as short one-liner on the clients + window. As usual the encoding of this string is UTF-8 and it + should be send in its translated form. + + The server shall send one status line for every signature found on + the message. + + + +File: gpgme.info, Node: UI Server Set Input Files, Next: UI Server Sign/Encrypt Files, Prev: UI Server Verify, Up: UI Server Protocol + +A.5 UI Server: Specifying the input files to operate on. +======================================================== + +All file related UI server commands operate on a number of input files +or directories, specified by one or more `FILE' commands: + + -- Command: FILE NAME [-continued] + Add the file or directory NAME to the list of pathnames to be + processed by the server. The parameter NAME must be an absolute + path name (including the drive letter) and is percent espaced (in + particular, the characters %, = and white space characters are + always escaped). The option `--continued' is present for all but + the last `FILE' command. + + +File: gpgme.info, Node: UI Server Sign/Encrypt Files, Next: UI Server Verify/Decrypt Files, Prev: UI Server Set Input Files, Up: UI Server Protocol + +A.6 UI Server: Encrypting and signing files. +============================================ + +First, the input files need to be specified by one or more `FILE' +commands. Afterwards, the actual operation is requested: + + -- Command: ENCRYPT_FILES -nohup + -- Command: SIGN_FILES -nohup + -- Command: ENCRYPT_SIGN_FILES -nohup + Request that the files specified by `FILE' are encrypted and/or + signed. The command selects the default action. The UI server may + allow the user to change this default afterwards interactively, and + even abort the operation or complete it only on some of the + selected files and directories. + + What it means to encrypt or sign a file or directory is specific to + the preferences of the user, the functionality the UI server + provides, and the selected protocol. Typically, for each input + file a new file is created under the original filename plus a + protocol specific extension (like `.gpg' or `.sig'), which contain + the encrypted/signed file or a detached signature. For + directories, the server may offer multiple options to the user + (for example ignore or process recursively). + + The `ENCRYPT_SIGN_FILES' command requests a combined sign and + encrypt operation. It may not be available for all protocols (for + example, it is available for OpenPGP but not for CMS). + + The option `--nohup' is mandatory. It is currently unspecified + what should happen if `--nohup' is not present. Because `--nohup' + is present, the server always returns `OK' promptly, and completes + the operation asynchronously. + + +File: gpgme.info, Node: UI Server Verify/Decrypt Files, Next: UI Server Import/Export Keys, Prev: UI Server Sign/Encrypt Files, Up: UI Server Protocol + +A.7 UI Server: Decrypting and verifying files. +============================================== + +First, the input files need to be specified by one or more `FILE' +commands. Afterwards, the actual operation is requested: + + -- Command: DECRYPT_FILES -nohup + -- Command: VERIFY_FILES -nohup + -- Command: DECRYPT_VERIFY_FILES -nohup + Request that the files specified by `FILE' are decrypted and/or + verified. The command selects the default action. The UI server + may allow the user to change this default afterwards + interactively, and even abort the operation or complete it only on + some of the selected files and directories. + + What it means to decrypt or verify a file or directory is specific + to the preferences of the user, the functionality the UI server + provides, and the selected protocol. Typically, for decryption, a + new file is created for each input file under the original + filename minus a protocol specific extension (like `.gpg') which + contains the original plaintext. For verification a status is + displayed for each signed input file, indicating if it is signed, + and if yes, if the signature is valid. For files that are signed + and encrypted, the `VERIFY' command transiently decrypts the file + to verify the enclosed signature. For directories, the server may + offer multiple options to the user (for example ignore or process + recursively). + + The option `--nohup' is mandatory. It is currently unspecified + what should happen if `--nohup' is not present. Because `--nohup' + is present, the server always returns `OK' promptly, and completes + the operation asynchronously. + + +File: gpgme.info, Node: UI Server Import/Export Keys, Next: UI Server Checksum Files, Prev: UI Server Verify/Decrypt Files, Up: UI Server Protocol + +A.8 UI Server: Managing certificates. +===================================== + +First, the input files need to be specified by one or more `FILE' +commands. Afterwards, the actual operation is requested: + + -- Command: IMPORT_FILES -nohup + Request that the certificates contained in the files specified by + `FILE' are imported into the local certificate databases. + + For directories, the server may offer multiple options to the user + (for example ignore or process recursively). + + The option `--nohup' is mandatory. It is currently unspecified + what should happen if `--nohup' is not present. Because `--nohup' + is present, the server always returns `OK' promptly, and completes + the operation asynchronously. + + FIXME: It may be nice to support an `EXPORT' command as well, which +is enabled by the context menu of the background of a directory. + + +File: gpgme.info, Node: UI Server Checksum Files, Next: Miscellaneous UI Server Commands, Prev: UI Server Import/Export Keys, Up: UI Server Protocol + +A.9 UI Server: Create and verify checksums for files. +===================================================== + +First, the input files need to be specified by one or more `FILE' +commands. Afterwards, the actual operation is requested: + + -- Command: CHECKSUM_CREATE_FILES -nohup + Request that checksums are created for the files specifed by + `FILE'. The choice of checksum algorithm and the destination + storage and format for the created checksums depend on the + preferences of the user and the functionality provided by the UI + server. For directories, the server may offer multiple options to + the user (for example ignore or process recursively). + + The option `--nohup' is mandatory. It is currently unspecified + what should happen if `--nohup' is not present. Because `--nohup' + is present, the server always returns `OK' promptly, and completes + the operation asynchronously. + + -- Command: CHECKSUM_VERIFY_FILES -nohup + Request that checksums are created for the files specifed by + `FILE' and verified against previously created and stored + checksums. The choice of checksum algorithm and the source storage + and format for previously created checksums depend on the + preferences of the user and the functionality provided by the UI + server. For directories, the server may offer multiple options to + the user (for example ignore or process recursively). + + If the source storage of previously created checksums is available + to the user through the Windows shell, this command may also + accept such checksum files as `FILE' arguments. In this case, the + UI server should instead verify the checksum of the referenced + files as if they were given as INPUT files. + + The option `--nohup' is mandatory. It is currently unspecified + what should happen if `--nohup' is not present. Because `--nohup' + is present, the server always returns `OK' promptly, and completes + the operation asynchronously. + + +File: gpgme.info, Node: Miscellaneous UI Server Commands, Prev: UI Server Checksum Files, Up: UI Server Protocol + +A.10 Miscellaneous UI Server Commands +===================================== + +The server needs to implement the following commands which are not +related to a specific command: + + -- Command: GETINFO WHAT + This is a multi purpose command, commonly used to return a variety + of information. The required subcommands as described by the WHAT + parameter are: + + `pid' + Return the process id of the server in decimal notation using + an Assuan data line. + +To allow the server to pop up the windows in the correct relation to the +client, the client is advised to tell the server by sending the option: + + -- Command option: window-id NUMBER + The NUMBER represents the native window ID of the clients current + window. On Windows systems this is a windows handle (`HWND') and + on X11 systems it is the `X Window ID'. The number needs to be + given as a hexadecimal value so that it is easier to convey pointer + values (e.g. `HWND'). + +A client may want to fire up the certificate manager of the server. To +do this it uses the Assuan command: + + -- Command: START_KEYMANAGER + The server shall pop up the main window of the key manager (aka + certificate manager). The client expects that the key manager is + brought into the foregound and that this command immediatley + returns (does not wait until the key manager has been fully + brought up). + +A client may want to fire up the configuration dialog of the server. To +do this it uses the Assuan command: + + -- Command: START_CONFDIALOG + The server shall pop up its configuration dialog. The client + expects that this dialog is brought into the foregound and that + this command immediatley returns (i.e. it does not wait until the + dialog has been fully brought up). + +When doing an operation on a mail, it is useful to let the server know +the address of the sender: + + -- Command: SENDER [--info] [--protocol=NAME] EMAIL + EMAIL is the plain ASCII encoded address ("addr-spec" as per + RFC-2822) enclosed in angle brackets. The address set with this + command is valid until a successful completion of the operation or + until a `RESET' command. A second command overrides the effect of + the first one; if EMAIL is not given and `--info' is not used, the + server shall use the default signing key. + + If option `--info' is not given, the server shall also suggest a + protocol to use for signing. The client may use this suggested + protocol on its own discretion. The same status line as with + PREP_ENCRYPT is used for this. + + The option `--protocol' may be used to give the server a hint on + which signing protocol should be preferred. + +To allow the UI-server to visually identify a running operation or to +associate operations the server MAY support the command: + + -- Command: SESSION NUMBER [STRING] + The NUMBER is an arbitrary value, a server may use to associate + simultaneous running sessions. It is a 32 bit unsigned integer + with `0' as a special value indicating that no session association + shall be done. + + If STRING is given, the server may use this as the title of a + window or, in the case of an email operation, to extract the + sender's address. The string may contain spaces; thus no + plus-escaping is used. + + This command may be used at any time and overrides the effect of + the last command. A `RESET' undoes the effect of this command. + + + +File: gpgme.info, Node: Library Copying, Next: Copying, Prev: UI Server Protocol, Up: Top + +GNU Lesser General Public License +********************************* + + Version 2.1, February 1999 + + Copyright (C) 1991, 1999 Free Software Foundation, Inc. + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + [This is the first released version of the Lesser GPL. It also counts + as the successor of the GNU Library Public License, version 2, hence the + version number 2.1.] + +Preamble +======== + +The licenses for most software are designed to take away your freedom +to share and change it. By contrast, the GNU General Public Licenses +are intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. + + This license, the Lesser General Public License, applies to some +specially designated software--typically libraries--of the Free +Software Foundation and other authors who decide to use it. You can use +it too, but we suggest you first think carefully about whether this +license or the ordinary General Public License is the better strategy to +use in any particular case, based on the explanations below. + + When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of it +in new free programs; and that you are informed that you can do these +things. + + To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + + For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know that +what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and is +quite different from the ordinary General Public License. We use this +license for certain libraries in order to permit linking those +libraries into non-free programs. + + When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + We call this license the "Lesser" General Public License because it +does _Less_ to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it +becomes a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of free +software. For example, permission to use the GNU C Library in non-free +programs enables many more people to use the whole GNU operating +system, as well as its variant, the GNU/Linux operating system. + + Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run that +program using a modified version of the Library. + + The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +"work based on the library" and a "work that uses the library". The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + + GNU LESSER GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + 0. This License Agreement applies to any software library or other + program which contains a notice placed by the copyright holder or + other authorized party saying it may be distributed under the + terms of this Lesser General Public License (also called "this + License"). Each licensee is addressed as "you". + + A "library" means a collection of software functions and/or data + prepared so as to be conveniently linked with application programs + (which use some of those functions and data) to form executables. + + The "Library", below, refers to any such software library or work + which has been distributed under these terms. A "work based on the + Library" means either the Library or any derivative work under + copyright law: that is to say, a work containing the Library or a + portion of it, either verbatim or with modifications and/or + translated straightforwardly into another language. (Hereinafter, + translation is included without limitation in the term + "modification".) + + "Source code" for a work means the preferred form of the work for + making modifications to it. For a library, complete source code + means all the source code for all modules it contains, plus any + associated interface definition files, plus the scripts used to + control compilation and installation of the library. + + Activities other than copying, distribution and modification are + not covered by this License; they are outside its scope. The act + of running a program using the Library is not restricted, and + output from such a program is covered only if its contents + constitute a work based on the Library (independent of the use of + the Library in a tool for writing it). Whether that is true + depends on what the Library does and what the program that uses + the Library does. + + 1. You may copy and distribute verbatim copies of the Library's + complete source code as you receive it, in any medium, provided + that you conspicuously and appropriately publish on each copy an + appropriate copyright notice and disclaimer of warranty; keep + intact all the notices that refer to this License and to the + absence of any warranty; and distribute a copy of this License + along with the Library. + + You may charge a fee for the physical act of transferring a copy, + and you may at your option offer warranty protection in exchange + for a fee. + + 2. You may modify your copy or copies of the Library or any portion + of it, thus forming a work based on the Library, and copy and + distribute such modifications or work under the terms of Section 1 + above, provided that you also meet all of these conditions: + + a. The modified work must itself be a software library. + + b. You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + + c. You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. + + d. If a facility in the modified Library refers to a function or + a table of data to be supplied by an application program that + uses the facility, other than as an argument passed when the + facility is invoked, then you must make a good faith effort + to ensure that, in the event an application does not supply + such function or table, the facility still operates, and + performs whatever part of its purpose remains meaningful. + + (For example, a function in a library to compute square roots + has a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function + must be optional: if the application does not supply it, the + square root function must still compute square roots.) + + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the + Library, and can be reasonably considered independent and separate + works in themselves, then this License, and its terms, do not + apply to those sections when you distribute them as separate + works. But when you distribute the same sections as part of a + whole which is a work based on the Library, the distribution of + the whole must be on the terms of this License, whose permissions + for other licensees extend to the entire whole, and thus to each + and every part regardless of who wrote it. + + Thus, it is not the intent of this section to claim rights or + contest your rights to work written entirely by you; rather, the + intent is to exercise the right to control the distribution of + derivative or collective works based on the Library. + + In addition, mere aggregation of another work not based on the + Library with the Library (or with a work based on the Library) on + a volume of a storage or distribution medium does not bring the + other work under the scope of this License. + + 3. You may opt to apply the terms of the ordinary GNU General Public + License instead of this License to a given copy of the Library. + To do this, you must alter all the notices that refer to this + License, so that they refer to the ordinary GNU General Public + License, version 2, instead of to this License. (If a newer + version than version 2 of the ordinary GNU General Public License + has appeared, then you can specify that version instead if you + wish.) Do not make any other change in these notices. + + Once this change is made in a given copy, it is irreversible for + that copy, so the ordinary GNU General Public License applies to + all subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of + the Library into a program that is not a library. + + 4. You may copy and distribute the Library (or a portion or + derivative of it, under Section 2) in object code or executable + form under the terms of Sections 1 and 2 above provided that you + accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software + interchange. + + If distribution of object code is made by offering access to copy + from a designated place, then offering equivalent access to copy + the source code from the same place satisfies the requirement to + distribute the source code, even though third parties are not + compelled to copy the source along with the object code. + + 5. A program that contains no derivative of any portion of the + Library, but is designed to work with the Library by being + compiled or linked with it, is called a "work that uses the + Library". Such a work, in isolation, is not a derivative work of + the Library, and therefore falls outside the scope of this License. + + However, linking a "work that uses the Library" with the Library + creates an executable that is a derivative of the Library (because + it contains portions of the Library), rather than a "work that + uses the library". The executable is therefore covered by this + License. Section 6 states terms for distribution of such + executables. + + When a "work that uses the Library" uses material from a header + file that is part of the Library, the object code for the work may + be a derivative work of the Library even though the source code is + not. Whether this is true is especially significant if the work + can be linked without the Library, or if the work is itself a + library. The threshold for this to be true is not precisely + defined by law. + + If such an object file uses only numerical parameters, data + structure layouts and accessors, and small macros and small inline + functions (ten lines or less in length), then the use of the object + file is unrestricted, regardless of whether it is legally a + derivative work. (Executables containing this object code plus + portions of the Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may + distribute the object code for the work under the terms of Section + 6. Any executables containing that work also fall under Section 6, + whether or not they are linked directly with the Library itself. + + 6. As an exception to the Sections above, you may also combine or + link a "work that uses the Library" with the Library to produce a + work containing portions of the Library, and distribute that work + under terms of your choice, provided that the terms permit + modification of the work for the customer's own use and reverse + engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the + Library is used in it and that the Library and its use are covered + by this License. You must supply a copy of this License. If the + work during execution displays copyright notices, you must include + the copyright notice for the Library among them, as well as a + reference directing the user to the copy of this License. Also, + you must do one of these things: + + a. Accompany the work with the complete corresponding + machine-readable source code for the Library including + whatever changes were used in the work (which must be + distributed under Sections 1 and 2 above); and, if the work + is an executable linked with the Library, with the complete + machine-readable "work that uses the Library", as object code + and/or source code, so that the user can modify the Library + and then relink to produce a modified executable containing + the modified Library. (It is understood that the user who + changes the contents of definitions files in the Library will + not necessarily be able to recompile the application to use + the modified definitions.) + + b. Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (1) uses at run + time a copy of the library already present on the user's + computer system, rather than copying library functions into + the executable, and (2) will operate properly with a modified + version of the library, if the user installs one, as long as + the modified version is interface-compatible with the version + that the work was made with. + + c. Accompany the work with a written offer, valid for at least + three years, to give the same user the materials specified in + Subsection 6a, above, for a charge no more than the cost of + performing this distribution. + + d. If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the + above specified materials from the same place. + + e. Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + + For an executable, the required form of the "work that uses the + Library" must include any data and utility programs needed for + reproducing the executable from it. However, as a special + exception, the materials to be distributed need not include + anything that is normally distributed (in either source or binary + form) with the major components (compiler, kernel, and so on) of + the operating system on which the executable runs, unless that + component itself accompanies the executable. + + It may happen that this requirement contradicts the license + restrictions of other proprietary libraries that do not normally + accompany the operating system. Such a contradiction means you + cannot use both them and the Library together in an executable + that you distribute. + + 7. You may place library facilities that are a work based on the + Library side-by-side in a single library together with other + library facilities not covered by this License, and distribute + such a combined library, provided that the separate distribution + of the work based on the Library and of the other library + facilities is otherwise permitted, and provided that you do these + two things: + + a. Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + + b. Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same + work. + + 8. You may not copy, modify, sublicense, link with, or distribute the + Library except as expressly provided under this License. Any + attempt otherwise to copy, modify, sublicense, link with, or + distribute the Library is void, and will automatically terminate + your rights under this License. However, parties who have + received copies, or rights, from you under this License will not + have their licenses terminated so long as such parties remain in + full compliance. + + 9. You are not required to accept this License, since you have not + signed it. However, nothing else grants you permission to modify + or distribute the Library or its derivative works. These actions + are prohibited by law if you do not accept this License. + Therefore, by modifying or distributing the Library (or any work + based on the Library), you indicate your acceptance of this + License to do so, and all its terms and conditions for copying, + distributing or modifying the Library or works based on it. + + 10. Each time you redistribute the Library (or any work based on the + Library), the recipient automatically receives a license from the + original licensor to copy, distribute, link with or modify the + Library subject to these terms and conditions. You may not impose + any further restrictions on the recipients' exercise of the rights + granted herein. You are not responsible for enforcing compliance + by third parties with this License. + + 11. If, as a consequence of a court judgment or allegation of patent + infringement or for any other reason (not limited to patent + issues), conditions are imposed on you (whether by court order, + agreement or otherwise) that contradict the conditions of this + License, they do not excuse you from the conditions of this + License. If you cannot distribute so as to satisfy simultaneously + your obligations under this License and any other pertinent + obligations, then as a consequence you may not distribute the + Library at all. For example, if a patent license would not permit + royalty-free redistribution of the Library by all those who + receive copies directly or indirectly through you, then the only + way you could satisfy both it and this License would be to refrain + entirely from distribution of the Library. + + If any portion of this section is held invalid or unenforceable + under any particular circumstance, the balance of the section is + intended to apply, and the section as a whole is intended to apply + in other circumstances. + + It is not the purpose of this section to induce you to infringe any + patents or other property right claims or to contest validity of + any such claims; this section has the sole purpose of protecting + the integrity of the free software distribution system which is + implemented by public license practices. Many people have made + generous contributions to the wide range of software distributed + through that system in reliance on consistent application of that + system; it is up to the author/donor to decide if he or she is + willing to distribute software through any other system and a + licensee cannot impose that choice. + + This section is intended to make thoroughly clear what is believed + to be a consequence of the rest of this License. + + 12. If the distribution and/or use of the Library is restricted in + certain countries either by patents or by copyrighted interfaces, + the original copyright holder who places the Library under this + License may add an explicit geographical distribution limitation + excluding those countries, so that distribution is permitted only + in or among countries not thus excluded. In such case, this + License incorporates the limitation as if written in the body of + this License. + + 13. The Free Software Foundation may publish revised and/or new + versions of the Lesser General Public License from time to time. + Such new versions will be similar in spirit to the present version, + but may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Library specifies a version number of this License which applies + to it and "any later version", you have the option of following + the terms and conditions either of that version or of any later + version published by the Free Software Foundation. If the Library + does not specify a license version number, you may choose any + version ever published by the Free Software Foundation. + + 14. If you wish to incorporate parts of the Library into other free + programs whose distribution conditions are incompatible with these, + write to the author to ask for permission. For software which is + copyrighted by the Free Software Foundation, write to the Free + Software Foundation; we sometimes make exceptions for this. Our + decision will be guided by the two goals of preserving the free + status of all derivatives of our free software and of promoting + the sharing and reuse of software generally. + + NO WARRANTY + 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO + WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE + LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT + HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT + WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT + NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE + QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE + LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY + SERVICING, REPAIR OR CORRECTION. + + 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY + MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE + LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR + INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF + DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU + OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY + OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS +How to Apply These Terms to Your New Libraries +============================================== + +If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of +the ordinary General Public License). + + To apply these terms, attach the following notices to the library. +It is safest to attach them to the start of each source file to most +effectively convey the exclusion of warranty; and each file should have +at least the "copyright" line and a pointer to where the full notice is +found. + + ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES. + Copyright (C) YEAR NAME OF AUTHOR + + This library is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at + your option) any later version. + + This library is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, + USA. + + Also add information on how to contact you by electronic and paper +mail. + + You should also get your employer (if you work as a programmer) or +your school, if any, to sign a "copyright disclaimer" for the library, +if necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the library + `Frob' (a library for tweaking knobs) written by James Random Hacker. + + SIGNATURE OF TY COON, 1 April 1990 + Ty Coon, President of Vice + + That's all there is to it! + diff --git a/doc/gpgme.info-2 b/doc/gpgme.info-2 new file mode 100644 index 0000000..cb7c5d1 --- /dev/null +++ b/doc/gpgme.info-2 @@ -0,0 +1,1309 @@ +This is /home/wk/w/gpgme/doc/gpgme.info, produced by makeinfo version +4.13 from /home/wk/w/gpgme/doc/gpgme.texi. + +INFO-DIR-SECTION GNU Libraries +START-INFO-DIR-ENTRY +* GPGME: (gpgme). Adding support for cryptography to your program. +END-INFO-DIR-ENTRY + + Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 g10 +Code GmbH. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 3 of the + License, or (at your option) any later version. The text of the + license can be found in the section entitled "Copying". + + This document is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + + This file documents the GPGME library. + + This is Edition 1.3.2, last updated 2 May 2012, of `The `GnuPG Made +Easy' Reference Manual', for Version 1.3.2. + + Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 g10 +Code GmbH. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 3 of the + License, or (at your option) any later version. The text of the + license can be found in the section entitled "Copying". + + This document is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + + +File: gpgme.info, Node: Copying, Next: Concept Index, Prev: Library Copying, Up: Top + +GNU General Public License +************************** + + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/' + + Everyone is permitted to copy and distribute verbatim copies of this + license document, but changing it is not allowed. + +Preamble +======== + +The GNU General Public License is a free, copyleft license for software +and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program-to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you +have certain responsibilities if you distribute copies of the software, +or if you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the +manufacturer can do so. This is fundamentally incompatible with the +aim of protecting users' freedom to change the software. The +systematic pattern of such abuse occurs in the area of products for +individuals to use, which is precisely where it is most unacceptable. +Therefore, we have designed this version of the GPL to prohibit the +practice for those products. If such problems arise substantially in +other domains, we stand ready to extend this provision to those domains +in future versions of the GPL, as needed to protect the freedom of +users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public + License. + + "Copyright" also means copyright-like laws that apply to other + kinds of works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this + License. Each licensee is addressed as "you". "Licensees" and + "recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the + work in a fashion requiring copyright permission, other than the + making of an exact copy. The resulting work is called a "modified + version" of the earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work + based on the Program. + + To "propagate" a work means to do anything with it that, without + permission, would make you directly or secondarily liable for + infringement under applicable copyright law, except executing it + on a computer or modifying a private copy. Propagation includes + copying, distribution (with or without modification), making + available to the public, and in some countries other activities as + well. + + To "convey" a work means any kind of propagation that enables other + parties to make or receive copies. Mere interaction with a user + through a computer network, with no transfer of a copy, is not + conveying. + + An interactive user interface displays "Appropriate Legal Notices" + to the extent that it includes a convenient and prominently visible + feature that (1) displays an appropriate copyright notice, and (2) + tells the user that there is no warranty for the work (except to + the extent that warranties are provided), that licensees may + convey the work under this License, and how to view a copy of this + License. If the interface presents a list of user commands or + options, such as a menu, a prominent item in the list meets this + criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work + for making modifications to it. "Object code" means any + non-source form of a work. + + A "Standard Interface" means an interface that either is an + official standard defined by a recognized standards body, or, in + the case of interfaces specified for a particular programming + language, one that is widely used among developers working in that + language. + + The "System Libraries" of an executable work include anything, + other than the work as a whole, that (a) is included in the normal + form of packaging a Major Component, but which is not part of that + Major Component, and (b) serves only to enable use of the work + with that Major Component, or to implement a Standard Interface + for which an implementation is available to the public in source + code form. A "Major Component", in this context, means a major + essential component (kernel, window system, and so on) of the + specific operating system (if any) on which the executable work + runs, or a compiler used to produce the work, or an object code + interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all + the source code needed to generate, install, and (for an executable + work) run the object code and to modify the work, including + scripts to control those activities. However, it does not include + the work's System Libraries, or general-purpose tools or generally + available free programs which are used unmodified in performing + those activities but which are not part of the work. For example, + Corresponding Source includes interface definition files + associated with source files for the work, and the source code for + shared libraries and dynamically linked subprograms that the work + is specifically designed to require, such as by intimate data + communication or control flow between those subprograms and other + parts of the work. + + The Corresponding Source need not include anything that users can + regenerate automatically from other parts of the Corresponding + Source. + + The Corresponding Source for a work in source code form is that + same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of + copyright on the Program, and are irrevocable provided the stated + conditions are met. This License explicitly affirms your unlimited + permission to run the unmodified Program. The output from running + a covered work is covered by this License only if the output, + given its content, constitutes a covered work. This License + acknowledges your rights of fair use or other equivalent, as + provided by copyright law. + + You may make, run and propagate covered works that you do not + convey, without conditions so long as your license otherwise + remains in force. You may convey covered works to others for the + sole purpose of having them make modifications exclusively for + you, or provide you with facilities for running those works, + provided that you comply with the terms of this License in + conveying all material for which you do not control copyright. + Those thus making or running the covered works for you must do so + exclusively on your behalf, under your direction and control, on + terms that prohibit them from making any copies of your + copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under + the conditions stated below. Sublicensing is not allowed; section + 10 makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological + measure under any applicable law fulfilling obligations under + article 11 of the WIPO copyright treaty adopted on 20 December + 1996, or similar laws prohibiting or restricting circumvention of + such measures. + + When you convey a covered work, you waive any legal power to forbid + circumvention of technological measures to the extent such + circumvention is effected by exercising rights under this License + with respect to the covered work, and you disclaim any intention + to limit operation or modification of the work as a means of + enforcing, against the work's users, your or third parties' legal + rights to forbid circumvention of technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you + receive it, in any medium, provided that you conspicuously and + appropriately publish on each copy an appropriate copyright notice; + keep intact all notices stating that this License and any + non-permissive terms added in accord with section 7 apply to the + code; keep intact all notices of the absence of any warranty; and + give all recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, + and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to + produce it from the Program, in the form of source code under the + terms of section 4, provided that you also meet all of these + conditions: + + a. The work must carry prominent notices stating that you + modified it, and giving a relevant date. + + b. The work must carry prominent notices stating that it is + released under this License and any conditions added under + section 7. This requirement modifies the requirement in + section 4 to "keep intact all notices". + + c. You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable + section 7 additional terms, to the whole of the work, and all + its parts, regardless of how they are packaged. This License + gives no permission to license the work in any other way, but + it does not invalidate such permission if you have separately + received it. + + d. If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has + interactive interfaces that do not display Appropriate Legal + Notices, your work need not make them do so. + + A compilation of a covered work with other separate and independent + works, which are not by their nature extensions of the covered + work, and which are not combined with it such as to form a larger + program, in or on a volume of a storage or distribution medium, is + called an "aggregate" if the compilation and its resulting + copyright are not used to limit the access or legal rights of the + compilation's users beyond what the individual works permit. + Inclusion of a covered work in an aggregate does not cause this + License to apply to the other parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms + of sections 4 and 5, provided that you also convey the + machine-readable Corresponding Source under the terms of this + License, in one of these ways: + + a. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for + as long as you offer spare parts or customer support for that + product model, to give anyone who possesses the object code + either (1) a copy of the Corresponding Source for all the + software in the product that is covered by this License, on a + durable physical medium customarily used for software + interchange, for a price no more than your reasonable cost of + physically performing this conveying of source, or (2) access + to copy the Corresponding Source from a network server at no + charge. + + c. Convey individual copies of the object code with a copy of + the written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, + and only if you received the object code with such an offer, + in accord with subsection 6b. + + d. Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access + to the Corresponding Source in the same way through the same + place at no further charge. You need not require recipients + to copy the Corresponding Source along with the object code. + If the place to copy the object code is a network server, the + Corresponding Source may be on a different server (operated + by you or a third party) that supports equivalent copying + facilities, provided you maintain clear directions next to + the object code saying where to find the Corresponding Source. + Regardless of what server hosts the Corresponding Source, you + remain obligated to ensure that it is available for as long + as needed to satisfy these requirements. + + e. Convey the object code using peer-to-peer transmission, + provided you inform other peers where the object code and + Corresponding Source of the work are being offered to the + general public at no charge under subsection 6d. + + + A separable portion of the object code, whose source code is + excluded from the Corresponding Source as a System Library, need + not be included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means + any tangible personal property which is normally used for personal, + family, or household purposes, or (2) anything designed or sold for + incorporation into a dwelling. In determining whether a product + is a consumer product, doubtful cases shall be resolved in favor of + coverage. For a particular product received by a particular user, + "normally used" refers to a typical or common use of that class of + product, regardless of the status of the particular user or of the + way in which the particular user actually uses, or expects or is + expected to use, the product. A product is a consumer product + regardless of whether the product has substantial commercial, + industrial or non-consumer uses, unless such uses represent the + only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, + procedures, authorization keys, or other information required to + install and execute modified versions of a covered work in that + User Product from a modified version of its Corresponding Source. + The information must suffice to ensure that the continued + functioning of the modified object code is in no case prevented or + interfered with solely because modification has been made. + + If you convey an object code work under this section in, or with, + or specifically for use in, a User Product, and the conveying + occurs as part of a transaction in which the right of possession + and use of the User Product is transferred to the recipient in + perpetuity or for a fixed term (regardless of how the transaction + is characterized), the Corresponding Source conveyed under this + section must be accompanied by the Installation Information. But + this requirement does not apply if neither you nor any third party + retains the ability to install modified object code on the User + Product (for example, the work has been installed in ROM). + + The requirement to provide Installation Information does not + include a requirement to continue to provide support service, + warranty, or updates for a work that has been modified or + installed by the recipient, or for the User Product in which it + has been modified or installed. Access to a network may be denied + when the modification itself materially and adversely affects the + operation of the network or violates the rules and protocols for + communication across the network. + + Corresponding Source conveyed, and Installation Information + provided, in accord with this section must be in a format that is + publicly documented (and with an implementation available to the + public in source code form), and must require no special password + or key for unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of + this License by making exceptions from one or more of its + conditions. Additional permissions that are applicable to the + entire Program shall be treated as though they were included in + this License, to the extent that they are valid under applicable + law. If additional permissions apply only to part of the Program, + that part may be used separately under those permissions, but the + entire Program remains governed by this License without regard to + the additional permissions. + + When you convey a copy of a covered work, you may at your option + remove any additional permissions from that copy, or from any part + of it. (Additional permissions may be written to require their own + removal in certain cases when you modify the work.) You may place + additional permissions on material, added by you to a covered work, + for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material + you add to a covered work, you may (if authorized by the copyright + holders of that material) supplement the terms of this License + with terms: + + a. Disclaiming warranty or limiting liability differently from + the terms of sections 15 and 16 of this License; or + + b. Requiring preservation of specified reasonable legal notices + or author attributions in that material or in the Appropriate + Legal Notices displayed by works containing it; or + + c. Prohibiting misrepresentation of the origin of that material, + or requiring that modified versions of such material be + marked in reasonable ways as different from the original + version; or + + d. Limiting the use for publicity purposes of names of licensors + or authors of the material; or + + e. Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f. Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified + versions of it) with contractual assumptions of liability to + the recipient, for any liability that these contractual + assumptions directly impose on those licensors and authors. + + All other non-permissive additional terms are considered "further + restrictions" within the meaning of section 10. If the Program as + you received it, or any part of it, contains a notice stating that + it is governed by this License along with a term that is a further + restriction, you may remove that term. If a license document + contains a further restriction but permits relicensing or + conveying under this License, you may add to a covered work + material governed by the terms of that license document, provided + that the further restriction does not survive such relicensing or + conveying. + + If you add terms to a covered work in accord with this section, you + must place, in the relevant source files, a statement of the + additional terms that apply to those files, or a notice indicating + where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in + the form of a separately written license, or stated as exceptions; + the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly + provided under this License. Any attempt otherwise to propagate or + modify it is void, and will automatically terminate your rights + under this License (including any patent licenses granted under + the third paragraph of section 11). + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly + and finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from + you under this License. If your rights have been terminated and + not permanently reinstated, you do not qualify to receive new + licenses for the same material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or + run a copy of the Program. Ancillary propagation of a covered work + occurring solely as a consequence of using peer-to-peer + transmission to receive a copy likewise does not require + acceptance. However, nothing other than this License grants you + permission to propagate or modify any covered work. These actions + infringe copyright if you do not accept this License. Therefore, + by modifying or propagating a covered work, you indicate your + acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically + receives a license from the original licensors, to run, modify and + propagate that work, subject to this License. You are not + responsible for enforcing compliance by third parties with this + License. + + An "entity transaction" is a transaction transferring control of an + organization, or substantially all assets of one, or subdividing an + organization, or merging organizations. If propagation of a + covered work results from an entity transaction, each party to that + transaction who receives a copy of the work also receives whatever + licenses to the work the party's predecessor in interest had or + could give under the previous paragraph, plus a right to + possession of the Corresponding Source of the work from the + predecessor in interest, if the predecessor has it or can get it + with reasonable efforts. + + You may not impose any further restrictions on the exercise of the + rights granted or affirmed under this License. For example, you + may not impose a license fee, royalty, or other charge for + exercise of rights granted under this License, and you may not + initiate litigation (including a cross-claim or counterclaim in a + lawsuit) alleging that any patent claim is infringed by making, + using, selling, offering for sale, or importing the Program or any + portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this + License of the Program or a work on which the Program is based. + The work thus licensed is called the contributor's "contributor + version". + + A contributor's "essential patent claims" are all patent claims + owned or controlled by the contributor, whether already acquired or + hereafter acquired, that would be infringed by some manner, + permitted by this License, of making, using, or selling its + contributor version, but do not include claims that would be + infringed only as a consequence of further modification of the + contributor version. For purposes of this definition, "control" + includes the right to grant patent sublicenses in a manner + consistent with the requirements of this License. + + Each contributor grants you a non-exclusive, worldwide, + royalty-free patent license under the contributor's essential + patent claims, to make, use, sell, offer for sale, import and + otherwise run, modify and propagate the contents of its + contributor version. + + In the following three paragraphs, a "patent license" is any + express agreement or commitment, however denominated, not to + enforce a patent (such as an express permission to practice a + patent or covenant not to sue for patent infringement). To + "grant" such a patent license to a party means to make such an + agreement or commitment not to enforce a patent against the party. + + If you convey a covered work, knowingly relying on a patent + license, and the Corresponding Source of the work is not available + for anyone to copy, free of charge and under the terms of this + License, through a publicly available network server or other + readily accessible means, then you must either (1) cause the + Corresponding Source to be so available, or (2) arrange to deprive + yourself of the benefit of the patent license for this particular + work, or (3) arrange, in a manner consistent with the requirements + of this License, to extend the patent license to downstream + recipients. "Knowingly relying" means you have actual knowledge + that, but for the patent license, your conveying the covered work + in a country, or your recipient's use of the covered work in a + country, would infringe one or more identifiable patents in that + country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or + arrangement, you convey, or propagate by procuring conveyance of, a + covered work, and grant a patent license to some of the parties + receiving the covered work authorizing them to use, propagate, + modify or convey a specific copy of the covered work, then the + patent license you grant is automatically extended to all + recipients of the covered work and works based on it. + + A patent license is "discriminatory" if it does not include within + the scope of its coverage, prohibits the exercise of, or is + conditioned on the non-exercise of one or more of the rights that + are specifically granted under this License. You may not convey a + covered work if you are a party to an arrangement with a third + party that is in the business of distributing software, under + which you make payment to the third party based on the extent of + your activity of conveying the work, and under which the third + party grants, to any of the parties who would receive the covered + work from you, a discriminatory patent license (a) in connection + with copies of the covered work conveyed by you (or copies made + from those copies), or (b) primarily for and in connection with + specific products or compilations that contain the covered work, + unless you entered into that arrangement, or that patent license + was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting + any implied license or other defenses to infringement that may + otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, + agreement or otherwise) that contradict the conditions of this + License, they do not excuse you from the conditions of this + License. If you cannot convey a covered work so as to satisfy + simultaneously your obligations under this License and any other + pertinent obligations, then as a consequence you may not convey it + at all. For example, if you agree to terms that obligate you to + collect a royalty for further conveying from those to whom you + convey the Program, the only way you could satisfy both those + terms and this License would be to refrain entirely from conveying + the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have + permission to link or combine any covered work with a work licensed + under version 3 of the GNU Affero General Public License into a + single combined work, and to convey the resulting work. The terms + of this License will continue to apply to the part which is the + covered work, but the special requirements of the GNU Affero + General Public License, section 13, concerning interaction through + a network will apply to the combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new + versions of the GNU General Public License from time to time. + Such new versions will be similar in spirit to the present + version, but may differ in detail to address new problems or + concerns. + + Each version is given a distinguishing version number. If the + Program specifies that a certain numbered version of the GNU + General Public License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that numbered version or of any later version published by the + Free Software Foundation. If the Program does not specify a + version number of the GNU General Public License, you may choose + any version ever published by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future + versions of the GNU General Public License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Program. + + Later license versions may give you additional or different + permissions. However, no additional obligations are imposed on any + author or copyright holder as a result of your choosing to follow a + later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY + APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE + COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" + WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE + RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. + SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL + NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES + AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU + FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR + CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE + THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA + BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD + PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER + PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF + THE POSSIBILITY OF SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided + above cannot be given local legal effect according to their terms, + reviewing courts shall apply local law that most closely + approximates an absolute waiver of all civil liability in + connection with the Program, unless a warranty or assumption of + liability accompanies a copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS +How to Apply These Terms to Your New Programs +============================================= + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is +safest to attach them to the start of each source file to most +effectively state the exclusion of warranty; and each file should have +at least the "copyright" line and a pointer to where the full notice is +found. + ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. + Copyright (C) YEAR NAME OF AUTHOR + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or (at + your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see `http://www.gnu.org/licenses/'. + + Also add information on how to contact you by electronic and paper +mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + PROGRAM Copyright (C) YEAR NAME OF AUTHOR + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. + + The hypothetical commands `show w' and `show c' should show the +appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an "about box". + + You should also get your employer (if you work as a programmer) or +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. For more information on this, and how to apply and follow +the GNU GPL, see `http://www.gnu.org/licenses/'. + + The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Lesser General Public License instead of this License. But first, +please read `http://www.gnu.org/philosophy/why-not-lgpl.html'. + + + +File: gpgme.info, Node: Function and Data Index, Prev: Concept Index, Up: Top + +Function and Data Index +*********************** + + +* Menu: + +* AM_PATH_GPGME: Using Automake. (line 13) +* AM_PATH_GPGME_PTH: Using Automake. (line 15) +* AM_PATH_GPGME_PTHREAD: Using Automake. (line 17) +* CHECKSUM_CREATE_FILES: UI Server Checksum Files. + (line 10) +* CHECKSUM_VERIFY_FILES: UI Server Checksum Files. + (line 23) +* DECRYPT: UI Server Decrypt. (line 27) +* DECRYPT_FILES: UI Server Verify/Decrypt Files. + (line 10) +* DECRYPT_VERIFY_FILES: UI Server Verify/Decrypt Files. + (line 12) +* ENCRYPT: UI Server Encrypt. (line 46) +* ENCRYPT_FILES: UI Server Sign/Encrypt Files. + (line 10) +* ENCRYPT_SIGN_FILES: UI Server Sign/Encrypt Files. + (line 12) +* enum gpgme_data_encoding_t: Data Buffer Meta-Data. + (line 28) +* enum gpgme_event_io_t: I/O Callback Interface. + (line 57) +* enum gpgme_hash_algo_t: Hash Algorithms. (line 10) +* enum gpgme_protocol_t: Protocols and Engines. + (line 17) +* enum gpgme_pubkey_algo_t: Public Key Algorithms. + (line 10) +* enum gpgme_sig_mode_t: Creating a Signature. + (line 7) +* enum gpgme_sig_stat_t: Verify. (line 277) +* FILE: UI Server Set Input Files. + (line 10) +* GETINFO: Miscellaneous UI Server Commands. + (line 10) +* gpgme_attr_t <1>: Key Signatures. (line 20) +* gpgme_attr_t: Information About Keys. + (line 42) +* gpgme_cancel: Cancellation. (line 17) +* gpgme_cancel_async: Cancellation. (line 38) +* gpgme_check_version: Library Version Check. + (line 8) +* gpgme_ctx_get_engine_info: Crypto Engine. (line 14) +* gpgme_ctx_set_engine_info: Crypto Engine. (line 27) +* gpgme_ctx_t: Contexts. (line 13) +* gpgme_data_encoding_t: Data Buffer Meta-Data. + (line 28) +* gpgme_data_get_encoding: Data Buffer Meta-Data. + (line 69) +* gpgme_data_get_file_name: Data Buffer Meta-Data. + (line 7) +* gpgme_data_new: Memory Based Data Buffers. + (line 13) +* gpgme_data_new_from_cbs: Callback Based Data Buffers. + (line 80) +* gpgme_data_new_from_fd: File Based Data Buffers. + (line 12) +* gpgme_data_new_from_file: Memory Based Data Buffers. + (line 40) +* gpgme_data_new_from_filepart: Memory Based Data Buffers. + (line 58) +* gpgme_data_new_from_mem: Memory Based Data Buffers. + (line 24) +* gpgme_data_new_from_stream: File Based Data Buffers. + (line 31) +* gpgme_data_new_with_read_cb: Callback Based Data Buffers. + (line 98) +* gpgme_data_read: Data Buffer I/O Operations. + (line 8) +* gpgme_data_read_cb_t: Callback Based Data Buffers. + (line 12) +* gpgme_data_release: Destroying Data Buffers. + (line 7) +* gpgme_data_release_and_get_mem: Destroying Data Buffers. + (line 13) +* gpgme_data_release_cb_t: Callback Based Data Buffers. + (line 53) +* gpgme_data_rewind: Data Buffer I/O Operations. + (line 62) +* gpgme_data_seek: Data Buffer I/O Operations. + (line 27) +* gpgme_data_seek_cb_t: Callback Based Data Buffers. + (line 44) +* gpgme_data_set_encoding: Data Buffer Meta-Data. + (line 75) +* gpgme_data_set_file_name: Data Buffer Meta-Data. + (line 18) +* gpgme_data_t: Exchanging Data. (line 14) +* gpgme_data_write: Data Buffer I/O Operations. + (line 18) +* gpgme_data_write_cb_t: Callback Based Data Buffers. + (line 28) +* gpgme_decrypt_result_t: Decrypt. (line 58) +* gpgme_edit_cb_t: Advanced Key Editing. + (line 8) +* gpgme_encrypt_result_t: Encrypting a Plaintext. + (line 76) +* gpgme_engine_check_version: Engine Version Check. + (line 8) +* gpgme_engine_info_t: Engine Information. (line 7) +* gpgme_err_code: Error Values. (line 44) +* gpgme_err_code_from_errno: Error Values. (line 101) +* gpgme_err_code_t: Error Values. (line 7) +* gpgme_err_code_to_errno: Error Values. (line 106) +* gpgme_err_make: Error Values. (line 60) +* gpgme_err_make_from_errno: Error Values. (line 87) +* gpgme_err_source: Error Values. (line 52) +* gpgme_err_source_t: Error Values. (line 14) +* gpgme_error: Error Values. (line 69) +* gpgme_error_from_errno: Error Values. (line 92) +* gpgme_error_t: Error Values. (line 25) +* gpgme_error_t (*gpgme_edit_cb_t) (void *HANDLE, gpgme_status_code_t STATUS, const char *ARGS, int FD): Advanced Key Editing. + (line 8) +* gpgme_error_t (*gpgme_io_cb_t) (void *DATA, int FD): I/O Callback Interface. + (line 7) +* gpgme_error_t (*gpgme_passphrase_cb_t)(void *HOOK, const char *UID_HINT, const char *PASSPHRASE_INFO, int PREV_WAS_BAD, int FD): Passphrase Callback. + (line 8) +* gpgme_error_t (*gpgme_register_io_cb_t) (void *DATA, int FD, int DIR, gpgme_io_cb_t FNC, void *FNC_DATA, void **TAG): I/O Callback Interface. + (line 21) +* gpgme_event_io_t <1>: Registering I/O Callbacks. + (line 7) +* gpgme_event_io_t: I/O Callback Interface. + (line 57) +* gpgme_free: Destroying Data Buffers. + (line 26) +* gpgme_genkey_result_t: Generating Keys. (line 75) +* gpgme_get_armor: ASCII Armor. (line 14) +* gpgme_get_engine_info: Engine Information. (line 47) +* gpgme_get_include_certs: Included Certificates. + (line 40) +* gpgme_get_io_cbs: Registering I/O Callbacks. + (line 46) +* gpgme_get_key: Listing Keys. (line 149) +* gpgme_get_keylist_mode: Key Listing Mode. (line 64) +* gpgme_get_passphrase_cb: Passphrase Callback. (line 54) +* gpgme_get_progress_cb: Progress Meter Callback. + (line 33) +* gpgme_get_protocol: Protocol Selection. (line 22) +* gpgme_get_protocol_name: Protocols and Engines. + (line 47) +* gpgme_get_sig_key: Verify. (line 477) +* gpgme_get_sig_status: Verify. (line 326) +* gpgme_get_sig_string_attr: Verify. (line 381) +* gpgme_get_sig_ulong_attr: Verify. (line 415) +* gpgme_get_textmode: Text Mode. (line 21) +* gpgme_hash_algo_name: Hash Algorithms. (line 40) +* gpgme_hash_algo_t: Hash Algorithms. (line 10) +* gpgme_import_result_t: Importing Keys. (line 111) +* gpgme_import_status_t: Importing Keys. (line 73) +* gpgme_invalid_key_t: Crypto Operations. (line 11) +* gpgme_io_cb_t: I/O Callback Interface. + (line 7) +* gpgme_key_get_string_attr: Information About Keys. + (line 185) +* gpgme_key_get_ulong_attr: Information About Keys. + (line 199) +* gpgme_key_ref: Manipulating Keys. (line 7) +* gpgme_key_release: Manipulating Keys. (line 20) +* gpgme_key_sig_get_string_attr: Key Signatures. (line 78) +* gpgme_key_sig_get_ulong_attr: Key Signatures. (line 92) +* gpgme_key_sig_t: Key Management. (line 82) +* gpgme_key_t: Key Management. (line 190) +* gpgme_key_unref: Manipulating Keys. (line 11) +* gpgme_keylist_result_t: Listing Keys. (line 125) +* gpgme_new: Creating Contexts. (line 7) +* gpgme_new_signature_t: Creating a Signature. + (line 58) +* gpgme_op_card_edit: Advanced Key Editing. + (line 50) +* gpgme_op_card_edit_start: Advanced Key Editing. + (line 57) +* gpgme_op_decrypt: Decrypt. (line 8) +* gpgme_op_decrypt_result: Decrypt. (line 81) +* gpgme_op_decrypt_start: Decrypt. (line 22) +* gpgme_op_decrypt_verify: Decrypt and Verify. (line 8) +* gpgme_op_delete: Deleting Keys. (line 8) +* gpgme_op_delete_start: Deleting Keys. (line 22) +* gpgme_op_edit: Advanced Key Editing. + (line 21) +* gpgme_op_edit_start: Advanced Key Editing. + (line 39) +* gpgme_op_encrypt: Encrypting a Plaintext. + (line 9) +* gpgme_op_encrypt_result: Encrypting a Plaintext. + (line 88) +* gpgme_op_encrypt_sign: Encrypting a Plaintext. + (line 100) +* gpgme_op_encrypt_sign_start: Encrypting a Plaintext. + (line 111) +* gpgme_op_encrypt_start: Encrypting a Plaintext. + (line 61) +* gpgme_op_export: Exporting Keys. (line 27) +* gpgme_op_export_ext: Exporting Keys. (line 58) +* gpgme_op_export_ext_start: Exporting Keys. (line 79) +* gpgme_op_export_keys: Exporting Keys. (line 90) +* gpgme_op_export_keys_start: Exporting Keys. (line 113) +* gpgme_op_export_start: Exporting Keys. (line 47) +* gpgme_op_genkey: Generating Keys. (line 8) +* gpgme_op_genkey_result: Generating Keys. (line 97) +* gpgme_op_genkey_start: Generating Keys. (line 65) +* gpgme_op_import: Importing Keys. (line 11) +* gpgme_op_import_ext: Importing Keys. (line 176) +* gpgme_op_import_keys: Importing Keys. (line 37) +* gpgme_op_import_keys_start: Importing Keys. (line 62) +* gpgme_op_import_result: Importing Keys. (line 162) +* gpgme_op_import_start: Importing Keys. (line 26) +* gpgme_op_keylist_end: Listing Keys. (line 82) +* gpgme_op_keylist_ext_start: Listing Keys. (line 36) +* gpgme_op_keylist_next: Listing Keys. (line 67) +* gpgme_op_keylist_result: Listing Keys. (line 137) +* gpgme_op_keylist_start: Listing Keys. (line 8) +* gpgme_op_passwd: Changing Passphrases. + (line 8) +* gpgme_op_passwd_start: Changing Passphrases. + (line 20) +* gpgme_op_sign: Creating a Signature. + (line 23) +* gpgme_op_sign_result: Creating a Signature. + (line 100) +* gpgme_op_sign_start: Creating a Signature. + (line 49) +* gpgme_op_trustlist_end: Listing Trust Items. (line 45) +* gpgme_op_trustlist_next: Listing Trust Items. (line 29) +* gpgme_op_trustlist_start: Listing Trust Items. (line 8) +* gpgme_op_verify: Verify. (line 9) +* gpgme_op_verify_result: Verify. (line 261) +* gpgme_op_verify_start: Verify. (line 29) +* gpgme_passphrase_cb_t: Passphrase Callback. (line 8) +* gpgme_progress_cb_t: Progress Meter Callback. + (line 8) +* gpgme_protocol_t <1>: Engine Information. (line 7) +* gpgme_protocol_t: Protocols and Engines. + (line 17) +* gpgme_pubkey_algo_name: Public Key Algorithms. + (line 50) +* gpgme_pubkey_algo_t: Public Key Algorithms. + (line 10) +* gpgme_recipient_t: Decrypt. (line 31) +* gpgme_register_io_cb_t: I/O Callback Interface. + (line 21) +* gpgme_release: Destroying Contexts. (line 7) +* gpgme_result_ref: Result Management. (line 15) +* gpgme_result_unref: Result Management. (line 21) +* gpgme_set_armor: ASCII Armor. (line 7) +* gpgme_set_engine_info: Engine Configuration. + (line 14) +* gpgme_set_include_certs: Included Certificates. + (line 8) +* gpgme_set_io_cbs: Registering I/O Callbacks. + (line 37) +* gpgme_set_keylist_mode: Key Listing Mode. (line 8) +* gpgme_set_locale: Locale. (line 16) +* gpgme_set_passphrase_cb: Passphrase Callback. (line 35) +* gpgme_set_progress_cb: Progress Meter Callback. + (line 18) +* gpgme_set_protocol: Protocol Selection. (line 8) +* gpgme_set_textmode: Text Mode. (line 7) +* gpgme_sig_mode_t: Creating a Signature. + (line 7) +* gpgme_sig_notation_add: Signature Notation Data. + (line 20) +* gpgme_sig_notation_clear: Signature Notation Data. + (line 11) +* gpgme_sig_notation_get: Signature Notation Data. + (line 43) +* gpgme_sig_notation_t: Verify. (line 39) +* gpgme_sig_stat_t: Verify. (line 277) +* gpgme_sign_result_t: Creating a Signature. + (line 86) +* gpgme_signature_t: Verify. (line 92) +* gpgme_signers_add: Selecting Signers. (line 15) +* gpgme_signers_clear: Selecting Signers. (line 7) +* gpgme_signers_enum: Selecting Signers. (line 22) +* gpgme_strerror: Error Strings. (line 7) +* gpgme_strerror_r: Error Strings. (line 17) +* gpgme_strsource: Error Strings. (line 27) +* gpgme_sub_key_t: Key Management. (line 12) +* gpgme_trust_item_get_int_attr: Information About Trust Items. + (line 31) +* gpgme_trust_item_get_string_attr: Information About Trust Items. + (line 17) +* gpgme_trust_item_ref: Manipulating Trust Items. + (line 7) +* gpgme_trust_item_release: Manipulating Trust Items. + (line 21) +* gpgme_trust_item_t: Trust Item Management. + (line 9) +* gpgme_trust_item_unref: Manipulating Trust Items. + (line 11) +* gpgme_user_id_t: Key Management. (line 155) +* gpgme_validity_t: Information About Keys. + (line 10) +* gpgme_verify_result_t: Verify. (line 245) +* gpgme_wait: Waiting For Completion. + (line 8) +* IMPORT_FILES: UI Server Import/Export Keys. + (line 10) +* INPUT <1>: UI Server Verify. (line 17) +* INPUT <2>: UI Server Decrypt. (line 13) +* INPUT <3>: UI Server Sign. (line 13) +* INPUT: UI Server Encrypt. (line 23) +* MESSAGE: UI Server Verify. (line 11) +* MICALG: UI Server Sign. (line 43) +* off_t (*gpgme_data_seek_cb_t) (void *HANDLE, off_t OFFSET, int WHENCE): Callback Based Data Buffers. + (line 44) +* OUTPUT <1>: UI Server Verify. (line 24) +* OUTPUT <2>: UI Server Decrypt. (line 20) +* OUTPUT <3>: UI Server Sign. (line 19) +* OUTPUT: UI Server Encrypt. (line 36) +* PREP_ENCRYPT: UI Server Encrypt. (line 72) +* PROTOCOL: UI Server Encrypt. (line 97) +* RECIPIENT: UI Server Encrypt. (line 10) +* SENDER: Miscellaneous UI Server Commands. + (line 51) +* SESSION: Miscellaneous UI Server Commands. + (line 70) +* SIGN: UI Server Sign. (line 33) +* SIGN_FILES: UI Server Sign/Encrypt Files. + (line 11) +* SIGSTATUS: UI Server Verify. (line 59) +* ssize_t (*gpgme_data_read_cb_t) (void *HANDLE, void *BUFFER, size_t SIZE): Callback Based Data Buffers. + (line 12) +* ssize_t (*gpgme_data_write_cb_t) (void *HANDLE, const void *BUFFER, size_t SIZE): Callback Based Data Buffers. + (line 28) +* START_CONFDIALOG: Miscellaneous UI Server Commands. + (line 42) +* START_KEYMANAGER: Miscellaneous UI Server Commands. + (line 32) +* struct gpgme_data_cbs: Callback Based Data Buffers. + (line 58) +* struct gpgme_io_cb_ts: Registering I/O Callbacks. + (line 7) +* VERIFY: UI Server Verify. (line 32) +* VERIFY_FILES: UI Server Verify/Decrypt Files. + (line 11) +* void (*gpgme_data_release_cb_t) (void *HANDLE): Callback Based Data Buffers. + (line 53) +* void (*gpgme_event_io_cb_t) (void *DATA, gpgme_event_io_t TYPE, void *TYPE_DATA): I/O Callback Interface. + (line 89) +* void (*gpgme_progress_cb_t)(void *HOOK, const char *WHAT, int TYPE, int CURRENT, int TOTAL): Progress Meter Callback. + (line 8) +* void (*gpgme_remove_io_cb_t) (void *TAG): I/O Callback Interface. + (line 47) +* window-id: Miscellaneous UI Server Commands. + (line 22) + + +File: gpgme.info, Node: Concept Index, Next: Function and Data Index, Prev: Copying, Up: Top + +Concept Index +************* + + +* Menu: + +* aborting operations: Cancellation. (line 6) +* algorithms: Algorithms. (line 6) +* algorithms, hash: Hash Algorithms. (line 6) +* algorithms, message digest: Hash Algorithms. (line 6) +* algorithms, public key: Public Key Algorithms. (line 6) +* armor mode: ASCII Armor. (line 6) +* ASCII armor: ASCII Armor. (line 6) +* attributes, of a key: Information About Keys. + (line 6) +* attributes, of a trust item: Information About Trust Items. + (line 6) +* autoconf: Using Automake. (line 6) +* automake: Using Automake. (line 6) +* backend: Protocols and Engines. (line 6) +* callback, passphrase: Passphrase Callback. (line 6) +* callback, progress meter: Progress Meter Callback. + (line 6) +* cancelling operations: Cancellation. (line 6) +* canonical text mode: Text Mode. (line 6) +* certificates, included: Included Certificates. (line 6) +* CMS: Cryptographic Message Syntax. + (line 6) +* compiler flags: Building the Source. (line 6) +* compiler options: Building the Source. (line 6) +* configuration of crypto backend: Engine Configuration. (line 6) +* context: Contexts. (line 6) +* context, armor mode: ASCII Armor. (line 6) +* context, attributes: Context Attributes. (line 6) +* context, configuring engine: Crypto Engine. (line 6) +* context, creation: Creating Contexts. (line 6) +* context, destruction: Destroying Contexts. (line 6) +* context, result of operation: Result Management. (line 6) +* context, selecting protocol: Protocol Selection. (line 6) +* context, text mode: Text Mode. (line 6) +* crypto backend: Protocols and Engines. (line 6) +* crypto engine: Protocols and Engines. (line 6) +* cryptographic message syntax: Cryptographic Message Syntax. + (line 6) +* cryptographic operation: Crypto Operations. (line 6) +* cryptographic operation, aborting: Cancellation. (line 6) +* cryptographic operation, cancelling: Cancellation. (line 6) +* cryptographic operation, decryption: Decrypt. (line 6) +* cryptographic operation, decryption and verification: Decrypt and Verify. + (line 6) +* cryptographic operation, encryption: Encrypt. (line 6) +* cryptographic operation, running: Run Control. (line 6) +* cryptographic operation, signature check: Verify. (line 6) +* cryptographic operation, signing: Sign. (line 6) +* cryptographic operation, verification: Verify. (line 6) +* cryptographic operation, wait for: Waiting For Completion. + (line 6) +* data buffer, creation: Creating Data Buffers. (line 6) +* data buffer, destruction: Destroying Data Buffers. + (line 6) +* data buffer, encoding: Data Buffer Meta-Data. (line 6) +* data buffer, file name: Data Buffer Meta-Data. (line 6) +* data buffer, I/O operations: Data Buffer I/O Operations. + (line 6) +* data buffer, manipulation: Manipulating Data Buffers. + (line 6) +* data buffer, meta-data: Data Buffer Meta-Data. (line 6) +* data buffer, read: Data Buffer I/O Operations. + (line 6) +* data buffer, seek: Data Buffer I/O Operations. + (line 6) +* data buffer, write: Data Buffer I/O Operations. + (line 6) +* data, exchanging: Exchanging Data. (line 6) +* decryption: Decrypt. (line 6) +* decryption and verification: Decrypt and Verify. (line 6) +* encryption: Encrypt. (line 6) +* engine: Protocols and Engines. (line 6) +* engine, configuration of: Engine Configuration. (line 6) +* engine, configuration per context: Crypto Engine. (line 6) +* engine, GnuPG: OpenPGP. (line 6) +* engine, GpgSM: Cryptographic Message Syntax. + (line 6) +* engine, information about: Engine Information. (line 6) +* error codes: Error Values. (line 6) +* error codes, list of <1>: Error Codes. (line 6) +* error codes, list of: Error Sources. (line 6) +* error codes, printing of: Error Strings. (line 6) +* error handling: Error Handling. (line 6) +* error sources: Error Values. (line 6) +* error sources, printing of: Error Strings. (line 6) +* error strings: Error Strings. (line 6) +* error values: Error Values. (line 6) +* error values, printing of: Error Strings. (line 6) +* event loop, external: Using External Event Loops. + (line 6) +* GDK, using GPGME with: I/O Callback Example GDK. + (line 6) +* GnuPG: OpenPGP. (line 6) +* GpgSM: Cryptographic Message Syntax. + (line 6) +* GTK+, using GPGME with: I/O Callback Example GTK+. + (line 6) +* hash algorithms: Hash Algorithms. (line 6) +* header file: Header. (line 6) +* include file: Header. (line 6) +* key listing: Listing Keys. (line 6) +* key listing mode: Key Listing Mode. (line 6) +* key listing, mode of: Key Listing Mode. (line 6) +* key listing, start: Listing Keys. (line 6) +* key management: Key Management. (line 6) +* key ring, add: Generating Keys. (line 6) +* key ring, delete from: Deleting Keys. (line 6) +* key ring, export from: Exporting Keys. (line 6) +* key ring, import to: Importing Keys. (line 6) +* key ring, list: Listing Keys. (line 6) +* key ring, search: Listing Keys. (line 6) +* key, attributes: Information About Keys. + (line 6) +* key, creation: Generating Keys. (line 6) +* key, delete: Deleting Keys. (line 6) +* key, edit: Advanced Key Editing. (line 6) +* key, export: Exporting Keys. (line 6) +* key, import: Importing Keys. (line 6) +* key, information about: Information About Keys. + (line 6) +* key, manipulation: Manipulating Keys. (line 6) +* key, signatures: Key Signatures. (line 6) +* largefile support: Largefile Support (LFS). + (line 6) +* LFS: Largefile Support (LFS). + (line 6) +* LGPL, Lesser General Public License: Library Copying. (line 6) +* libtool: Using Libtool. (line 6) +* listing keys: Listing Keys. (line 6) +* locale, default: Locale. (line 6) +* locale, of a context: Locale. (line 6) +* message digest algorithms: Hash Algorithms. (line 6) +* multi-threading: Multi Threading. (line 6) +* notation data <1>: Signature Notation Data. + (line 6) +* notation data: Verify. (line 6) +* OpenPGP: OpenPGP. (line 6) +* passphrase callback: Passphrase Callback. (line 6) +* passphrase, change: Changing Passphrases. (line 6) +* policy URL: Signature Notation Data. + (line 6) +* progress meter callback: Progress Meter Callback. + (line 6) +* protocol: Protocols and Engines. (line 6) +* protocol, CMS: Cryptographic Message Syntax. + (line 6) +* protocol, GnuPG: OpenPGP. (line 6) +* protocol, S/MIME: Cryptographic Message Syntax. + (line 6) +* protocol, selecting: Protocol Selection. (line 6) +* public key algorithms: Public Key Algorithms. (line 6) +* Qt, using GPGME with: I/O Callback Example Qt. + (line 6) +* run control: Run Control. (line 6) +* S/MIME: Cryptographic Message Syntax. + (line 6) +* sign: Sign. (line 6) +* signal handling: Signal Handling. (line 6) +* signals: Signal Handling. (line 6) +* signature check: Decrypt and Verify. (line 6) +* signature notation data <1>: Signature Notation Data. + (line 6) +* signature notation data: Verify. (line 6) +* signature, creation: Sign. (line 6) +* signature, selecting signers: Selecting Signers. (line 6) +* signature, verification: Verify. (line 6) +* signatures, on a key: Key Signatures. (line 6) +* signers, selecting: Selecting Signers. (line 6) +* text mode: Text Mode. (line 6) +* thread-safeness: Multi Threading. (line 6) +* trust item: Trust Item Management. (line 6) +* trust item list: Listing Trust Items. (line 6) +* trust item, attributes: Information About Trust Items. + (line 6) +* trust item, information about: Information About Trust Items. + (line 6) +* trust item, manipulation: Manipulating Trust Items. + (line 6) +* UI server: UI Server Protocol. (line 6) +* user interface server: UI Server Protocol. (line 6) +* verification: Verify. (line 6) +* verification and decryption: Decrypt and Verify. (line 6) +* version check, of the engines: Engine Version Check. (line 6) +* version check, of the library: Library Version Check. (line 6) +* wait for completion: Waiting For Completion. + (line 6) + + diff --git a/doc/gpgme.texi b/doc/gpgme.texi new file mode 100644 index 0000000..61cdb37 --- /dev/null +++ b/doc/gpgme.texi @@ -0,0 +1,5787 @@ +\input texinfo @c -*- mode: texinfo; coding: latin-1; -*- +@documentencoding ISO-8859-1 +@setfilename gpgme.info +@settitle The `GnuPG Made Easy' Reference Manual + +@dircategory GNU Libraries +@direntry +* @acronym{GPGME}: (gpgme). Adding support for cryptography to your program. +@end direntry + +@c Unify some of the indices. +@syncodeindex tp fn +@syncodeindex pg fn + +@copying +Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, +2008, 2010 g10 Code GmbH. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 3 of the License, or (at your +option) any later version. The text of the license can be found in the +section entitled ``Copying''. +@end quotation + +This document is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. +@end copying + +@include version.texi + +@c Macros used by the description of the UI server protocol +@macro clnt + @sc{c:} @c +@end macro +@macro srvr + @sc{s:} @c +@end macro + + +@c +@c T I T L E P A G E +@c +@ifinfo +This file documents the @acronym{GPGME} library. + +This is Edition @value{EDITION}, last updated @value{UPDATED}, of +@cite{The `GnuPG Made Easy' Reference Manual}, for Version +@value{VERSION}. + +@c NOTE: Don't forget to update the year for the TeX version, too. +@insertcopying + +@end ifinfo + +@c We do not want that bastard short titlepage. +@c @iftex +@c @shorttitlepage The `GnuPG Made Easy' Reference Manual +@c @end iftex +@titlepage +@center @titlefont{The `GnuPG Made Easy'} +@sp 1 +@center @titlefont{Reference Manual} +@sp 6 +@center Edition @value{EDITION} +@sp 1 +@center last updated @value{UPDATED} +@sp 1 +@center for version @value{VERSION} +@page +@vskip 0pt plus 1filll +Published by g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany + +@insertcopying +@end titlepage +@page + +@summarycontents +@contents + +@ifnottex +@node Top +@top Main Menu +This is Edition @value{EDITION}, last updated @value{UPDATED}, of +@cite{The `GnuPG Made Easy' Reference Manual}, for Version +@value{VERSION} of the @acronym{GPGME} library. +@end ifnottex + +@menu +* Introduction:: How to use this manual. +* Preparation:: What you should do before using the library. +* Protocols and Engines:: Supported crypto protocols. +* Algorithms:: Supported algorithms. +* Error Handling:: Error numbers and their meanings. +* Exchanging Data:: Passing data to and from @acronym{GPGME}. +* Contexts:: Handling @acronym{GPGME} contexts. + +Appendices + +* UI Server Protocol:: The GnuPG UI Server Protocol. + +* Library Copying:: The GNU Lesser General Public License says + how you can copy and share `GnuPG Made Easy'. +* Copying:: The GNU General Public License says how you + can copy and share this manual. + +Indices + +* Concept Index:: Index of concepts and programs. +* Function and Data Index:: Index of functions, variables and data types. + + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* Getting Started:: Purpose of the manual, and how to use it. +* Features:: Reasons to install and use @acronym{GPGME}. +* Overview:: Basic architecture of the @acronym{GPGME} library. + +Preparation + +* Header:: What header file you need to include. +* Building the Source:: Compiler options to be used. +* Largefile Support (LFS):: How to use @acronym{GPGME} with LFS. +* Using Automake:: Compiler options to be used the easy way. +* Using Libtool:: Avoiding compiler options entirely. +* Library Version Check:: Getting and verifying the library version. +* Signal Handling:: How @acronym{GPGME} affects signal handling. +* Multi Threading:: How @acronym{GPGME} can be used in an MT environment. + +Protocols and Engines + +* Engine Version Check:: Verifying the engine version. +* Engine Information:: Obtaining more information about the engines. +* Engine Configuration:: Changing the engine configuration. +* OpenPGP:: Support for the OpenPGP protocol. +* Cryptographic Message Syntax:: Support for the CMS. + +Algorithms + +* Public Key Algorithms:: A list of all public key algorithms. +* Hash Algorithms:: A list of all hash algorithms. + +Error Handling + +* Error Values:: The error value and what it means. +* Error Codes:: A list of important error codes. +* Error Sources:: A list of important error sources. +* Error Strings:: How to get a descriptive string from a value. + +Exchanging Data + +* Creating Data Buffers:: Creating new data buffers. +* Destroying Data Buffers:: Releasing data buffers. +* Manipulating Data Buffers:: Operations on data buffers. + +Creating Data Buffers + +* Memory Based Data Buffers:: Creating memory based data buffers. +* File Based Data Buffers:: Creating file based data buffers. +* Callback Based Data Buffers:: Creating callback based data buffers. + +Manipulating Data Buffers + +* Data Buffer I/O Operations:: I/O operations on data buffers. +* Data Buffer Meta-Data:: Meta-data manipulation of data buffers. + +Contexts + +* Creating Contexts:: Creating new @acronym{GPGME} contexts. +* Destroying Contexts:: Releasing @acronym{GPGME} contexts. +* Result Management:: Managing the result of crypto operations. +* Context Attributes:: Setting properties of a context. +* Key Management:: Managing keys with @acronym{GPGME}. +* Trust Item Management:: Managing trust items with @acronym{GPGME}. +* Crypto Operations:: Using a context for cryptography. +* Run Control:: Controlling how operations are run. + +Context Attributes + +* Protocol Selection:: Selecting the protocol used by a context. +* Crypto Engine:: Configuring the crypto engine. +* ASCII Armor:: Requesting @acronym{ASCII} armored output. +* Text Mode:: Choosing canonical text mode. +* Included Certificates:: Including a number of certificates. +* Key Listing Mode:: Selecting key listing mode. +* Passphrase Callback:: Getting the passphrase from the user. +* Progress Meter Callback:: Being informed about the progress. +* Locale:: Setting the locale of a context. + +Key Management + +* Listing Keys:: Browsing the list of available keys. +* Information About Keys:: Requesting detailed information about keys. +* Key Signatures:: Listing the signatures on a key. +* Manipulating Keys:: Operations on keys. +* Generating Keys:: Creating new key pairs. +* Exporting Keys:: Retrieving key data from the key ring. +* Importing Keys:: Adding keys to the key ring. +* Deleting Keys:: Removing keys from the key ring. +* Advanced Key Editing:: Advanced key edit operation. + +Trust Item Management + +* Listing Trust Items:: Browsing the list of available trust items. +* Information About Trust Items:: Requesting information about trust items. +* Manipulating Trust Items:: Operations on trust items. + +Crypto Operations + +* Decrypt:: Decrypting a ciphertext. +* Verify:: Verifying a signature. +* Decrypt and Verify:: Decrypting a signed ciphertext. +* Sign:: Creating a signature. +* Encrypt:: Encrypting a plaintext. + +Sign + +* Selecting Signers:: How to choose the keys to sign with. +* Creating a Signature:: How to create a signature. +* Signature Notation Data:: How to add notation data to a signature. + +Encrypt + +* Encrypting a Plaintext:: How to encrypt a plaintext. + +Run Control + +* Waiting For Completion:: Waiting until an operation is completed. +* Using External Event Loops:: Advanced control over what happens when. +* Cancellation:: How to end pending operations prematurely. + +Using External Event Loops + +* I/O Callback Interface:: How I/O callbacks are registered. +* Registering I/O Callbacks:: How to use I/O callbacks for a context. +* I/O Callback Example:: An example how to use I/O callbacks. +* I/O Callback Example GTK+:: How to integrate @acronym{GPGME} in GTK+. +* I/O Callback Example GDK:: How to integrate @acronym{GPGME} in GDK. +* I/O Callback Example Qt:: How to integrate @acronym{GPGME} in Qt. + +@end detailmenu +@end menu + +@node Introduction +@chapter Introduction + +`GnuPG Made Easy' (@acronym{GPGME}) is a C language library that +allows to add support for cryptography to a program. It is designed +to make access to public key crypto engines like GnuPG or GpgSM easier +for applications. @acronym{GPGME} provides a high-level crypto API +for encryption, decryption, signing, signature verification and key +management. + +@acronym{GPGME} uses GnuPG and GpgSM as its backends to support +OpenPGP and the Cryptographic Message Syntax (CMS). + +@menu +* Getting Started:: Purpose of the manual, and how to use it. +* Features:: Reasons to install and use @acronym{GPGME}. +* Overview:: Basic architecture of the @acronym{GPGME} library. +@end menu + + +@node Getting Started +@section Getting Started + +This manual documents the @acronym{GPGME} library programming +interface. All functions and data types provided by the library are +explained. + +The reader is assumed to possess basic knowledge about cryptography in +general, and public key cryptography in particular. The underlying +cryptographic engines that are used by the library are not explained, +but where necessary, special features or requirements by an engine are +mentioned as far as they are relevant to @acronym{GPGME} or its users. + +This manual can be used in several ways. If read from the beginning +to the end, it gives a good introduction into the library and how it +can be used in an application. Forward references are included where +necessary. Later on, the manual can be used as a reference manual to +get just the information needed about any particular interface of the +library. Experienced programmers might want to start looking at the +examples at the end of the manual, and then only read up those parts +of the interface which are unclear. + + +@node Features +@section Features + +@acronym{GPGME} has a couple of advantages over other libraries doing +a similar job, and over implementing support for GnuPG or other crypto +engines into your application directly. + +@table @asis +@item it's free software +Anybody can use, modify, and redistribute it under the terms of the GNU +Lesser General Public License (@pxref{Library Copying}). + +@item it's flexible +@acronym{GPGME} provides transparent support for several cryptographic +protocols by different engines. Currently, @acronym{GPGME} supports +the OpenPGP protocol using GnuPG as the backend, and the Cryptographic +Message Syntax using GpgSM as the backend. + +@item it's easy +@acronym{GPGME} hides the differences between the protocols and +engines from the programmer behind an easy-to-use interface. This way +the programmer can focus on the other parts of the program, and still +integrate strong cryptography in his application. Once support for +@acronym{GPGME} has been added to a program, it is easy to add support +for other crypto protocols once @acronym{GPGME} backends provide them. +@end table + + +@node Overview +@section Overview + +@acronym{GPGME} provides a data abstraction that is used to pass data +to the crypto engine, and receive returned data from it. Data can be +read from memory or from files, but it can also be provided by a +callback function. + +The actual cryptographic operations are always set within a context. +A context provides configuration parameters that define the behaviour +of all operations performed within it. Only one operation per context +is allowed at any time, but when one operation is finished, you can +run the next operation in the same context. There can be more than +one context, and all can run different operations at the same time. + +Furthermore, @acronym{GPGME} has rich key management facilities +including listing keys, querying their attributes, generating, +importing, exporting and deleting keys, and acquiring information +about the trust path. + +With some precautions, @acronym{GPGME} can be used in a multi-threaded +environment, although it is not completely thread safe and thus needs +the support of the application. + + +@node Preparation +@chapter Preparation + +To use @acronym{GPGME}, you have to perform some changes to your +sources and the build system. The necessary changes are small and +explained in the following sections. At the end of this chapter, it +is described how the library is initialized, and how the requirements +of the library are verified. + +@menu +* Header:: What header file you need to include. +* Building the Source:: Compiler options to be used. +* Largefile Support (LFS):: How to use @acronym{GPGME} with LFS. +* Using Automake:: Compiler options to be used the easy way. +* Using Libtool:: Avoiding compiler options entirely. +* Library Version Check:: Getting and verifying the library version. +* Signal Handling:: How @acronym{GPGME} affects signal handling. +* Multi Threading:: How @acronym{GPGME} can be used in an MT environment. +@end menu + + +@node Header +@section Header +@cindex header file +@cindex include file + +All interfaces (data types and functions) of the library are defined +in the header file `gpgme.h'. You must include this in all programs +using the library, either directly or through some other header file, +like this: + +@example +#include <gpgme.h> +@end example + +The name space of @acronym{GPGME} is @code{gpgme_*} for function names +and data types and @code{GPGME_*} for other symbols. Symbols internal +to @acronym{GPGME} take the form @code{_gpgme_*} and @code{_GPGME_*}. + +Because @acronym{GPGME} makes use of the GPG Error library, using +@acronym{GPGME} will also use the @code{GPG_ERR_*} name space +directly, and the @code{gpg_err*} and @code{gpg_str*} name space +indirectly. + + +@node Building the Source +@section Building the Source +@cindex compiler options +@cindex compiler flags + +If you want to compile a source file including the `gpgme.h' header +file, you must make sure that the compiler can find it in the +directory hierarchy. This is accomplished by adding the path to the +directory in which the header file is located to the compilers include +file search path (via the @option{-I} option). + +However, the path to the include file is determined at the time the +source is configured. To solve this problem, gpgme ships with a small +helper program @command{gpgme-config} that knows about the path to the +include file and other configuration options. The options that need +to be added to the compiler invocation at compile time are output by +the @option{--cflags} option to @command{gpgme-config}. The following +example shows how it can be used at the command line: + +@example +gcc -c foo.c `gpgme-config --cflags` +@end example + +Adding the output of @samp{gpgme-config --cflags} to the compiler +command line will ensure that the compiler can find the +@acronym{GPGME} header file. + +A similar problem occurs when linking the program with the library. +Again, the compiler has to find the library files. For this to work, +the path to the library files has to be added to the library search +path (via the @option{-L} option). For this, the option +@option{--libs} to @command{gpgme-config} can be used. For +convenience, this option also outputs all other options that are +required to link the program with @acronym{GPGME} (in particular, the +@samp{-lgpgme} option). The example shows how to link @file{foo.o} +with the @acronym{GPGME} library to a program @command{foo}. + +@example +gcc -o foo foo.o `gpgme-config --libs` +@end example + +Of course you can also combine both examples to a single command by +specifying both options to @command{gpgme-config}: + +@example +gcc -o foo foo.c `gpgme-config --cflags --libs` +@end example + +If you want to link to one of the thread-safe versions of +@acronym{GPGME}, you must specify the @option{--thread} option before +any other option to select the thread package you want to link with. +Supported thread packages are @option{--thread=pth} and +@option{--thread=pthread}. + + +@node Largefile Support (LFS) +@section Largefile Support (LFS) +@cindex largefile support +@cindex LFS + +@acronym{GPGME} is compiled with largefile support by default, if it +is available on the system. This means that GPGME supports files +larger than two gigabyte in size, if the underlying operating system +can. On some systems, largefile support is already the default. On +such systems, nothing special is required. However, some systems +provide only support for files up to two gigabyte in size by default. +Support for larger file sizes has to be specifically enabled. + +To make a difficult situation even more complex, such systems provide +two different types of largefile support. You can either get all +relevant functions replaced with alternatives that are largefile +capable, or you can get new functions and data types for largefile +support added. Those new functions have the same name as their +smallfile counterparts, but with a suffix of 64. + +An example: The data type @code{off_t} is 32 bit wide on GNU/Linux PC +systems. To address offsets in large files, you can either enable +largefile support add-on. Then a new data type @code{off64_t} is +provided, which is 64 bit wide. Or you can replace the existing +@code{off_t} data type with its 64 bit wide counterpart. All +occurences of @code{off_t} are then automagically replaced. + +As if matters were not complex enough, there are also two different +types of file descriptors in such systems. This is important because +if file descriptors are exchanged between programs that use a +different maximum file size, certain errors must be produced on some +file descriptors to prevent subtle overflow bugs from occuring. + +As you can see, supporting two different maximum file sizes at the +same time is not at all an easy task. However, the maximum file size +does matter for @acronym{GPGME}, because some data types it uses in +its interfaces are affected by that. For example, the @code{off_t} +data type is used in the @code{gpgme_data_seek} function, to match its +@acronym{POSIX} counterpart. This affects the call-frame of the +function, and thus the ABI of the library. Furthermore, file +descriptors can be exchanged between GPGME and the application. + +For you as the user of the library, this means that your program must +be compiled in the same file size mode as the library. Luckily, there +is absolutely no valid reason for new programs to not enable largefile +support by default and just use that. The compatibility modes (small +file sizes or dual mode) can be considered an historic artefact, only +useful to allow for a transitional period. + +@acronym{GPGME} is compiled using largefile support by default. This +means that your application must do the same, at least as far as it is +relevant for using the @file{gpgme.h} header file. All types in this +header files refer to their largefile counterparts, if they are +different from any default types on the system. + +You can enable largefile support, if it is different from the default +on the system the application is compiled on, by using the Autoconf +macro @code{AC_SYS_LARGEFILE}. If you do this, then you don't need to +worry about anything else: It will just work. In this case you might +also want to use @code{AC_FUNC_FSEEKO} to take advantage of some new +interfaces, and @code{AC_TYPE_OFF_T} (just in case). + +If you do not use Autoconf, you can define the preprocessor symbol +@code{_FILE_OFFSET_BITS} to 64 @emph{before} including any header +files, for example by specifying the option +@code{-D_FILE_OFFSET_BITS=64} on the compiler command line. You will +also want to define the preprocessor symbol @code{LARGEFILE_SOURCE} to +1 in this case, to take advantage of some new interfaces. + +If you do not want to do either of the above, you probably know enough +about the issue to invent your own solution. Just keep in mind that +the @acronym{GPGME} header file expects that largefile support is +enabled, if it is available. In particular, we do not support dual +mode (@code{_LARGEFILE64_SOURCE}). + + +@node Using Automake +@section Using Automake +@cindex automake +@cindex autoconf + +It is much easier if you use GNU Automake instead of writing your own +Makefiles. If you do that you do not have to worry about finding and +invoking the @command{gpgme-config} script at all. @acronym{GPGME} +provides an extension to Automake that does all the work for you. + +@c A simple macro for optional variables. +@macro ovar{varname} +@r{[}@var{\varname\}@r{]} +@end macro +@defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@defmacx AM_PATH_GPGME_PTH (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@defmacx AM_PATH_GPGME_PTHREAD (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found}) +Check whether @acronym{GPGME} (at least version @var{minimum-version}, +if given) exists on the host system. If it is found, execute +@var{action-if-found}, otherwise do @var{action-if-not-found}, if +given. + +Additionally, the function defines @code{GPGME_CFLAGS} to the flags +needed for compilation of the program to find the @file{gpgme.h} +header file, and @code{GPGME_LIBS} to the linker flags needed to link +the program to the @acronym{GPGME} library. + +@code{AM_PATH_GPGME_PTH} checks for the version of @acronym{GPGME} +that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and +@code{GPGME_PTH_LIBS}. + +@code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME} +that can be used with the native pthread implementation, and defines +@code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}. +@end defmac + +You can use the defined Autoconf variables like this in your +@file{Makefile.am}: + +@example +AM_CPPFLAGS = $(GPGME_CFLAGS) +LDADD = $(GPGME_LIBS) +@end example + + +@node Using Libtool +@section Using Libtool +@cindex libtool + +The easiest way is to just use GNU Libtool. If you use libtool, and +link to @code{libgpgme.la}, @code{libgpgme-pth.la} or +@code{libgpgme-pthread.la} respectively, everything will be done +automatically by Libtool. + + +@node Library Version Check +@section Library Version Check +@cindex version check, of the library + +@deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}}) +The function @code{gpgme_check_version} has four purposes. It can be +used to retrieve the version number of the library. In addition it +can verify that the version number is higher than a certain required +version number. In either case, the function initializes some +sub-systems, and for this reason alone it must be invoked early in +your program, before you make use of the other functions in +@acronym{GPGME}. The last purpose is to run selftests. + +As a side effect for W32 based systems, the socket layer will get +initialized. + + +If @var{required_version} is @code{NULL}, the function returns a +pointer to a statically allocated string containing the version number +of the library. + +If @var{required_version} is not @code{NULL}, it should point to a +string containing a version number, and the function checks that the +version of the library is at least as high as the version number +provided. In this case, the function returns a pointer to a +statically allocated string containing the version number of the +library. If @var{REQUIRED_VERSION} is not a valid version number, or +if the version requirement is not met, the function returns +@code{NULL}. + +If you use a version of a library that is backwards compatible with +older releases, but contains additional interfaces which your program +uses, this function provides a run-time check if the necessary +features are provided by the installed version of the library. + +If a selftest fails, the function may still succeed. Selftest errors +are returned later when invoking @code{gpgme_new}, so that a detailed +error code can be returned (historically, @code{gpgme_check_version} +does not return a detailed error code). +@end deftypefun + + +After initializing @acronym{GPGME}, you should set the locale +information to the locale required for your output terminal. This +locale information is needed for example for the curses and Gtk +pinentry. Here is an example of a complete initialization: + +@example +#include <locale.h> +#include <gpgme.h> + +void +init_gpgme (void) +@{ + /* Initialize the locale environment. */ + setlocale (LC_ALL, ""); + gpgme_check_version (NULL); + gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL)); +#ifdef LC_MESSAGES + gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL)); +#endif +@} +@end example + +Note that you are highly recommended to initialize the locale settings +like this. @acronym{GPGME} can not do this for you because it would +not be thread safe. The conditional on LC_MESSAGES is only necessary +for portability to W32 systems. + + +@node Signal Handling +@section Signal Handling +@cindex signals +@cindex signal handling + +The @acronym{GPGME} library communicates with child processes (the +crypto engines). If a child process dies unexpectedly, for example +due to a bug, or system problem, a @code{SIGPIPE} signal will be +delivered to the application. The default action is to abort the +program. To protect against this, @code{gpgme_check_version} sets the +@code{SIGPIPE} signal action to @code{SIG_IGN}, which means that the +signal will be ignored. + +@acronym{GPGME} will only do that if the signal action for +@code{SIGPIPE} is @code{SIG_DEF} at the time +@code{gpgme_check_version} is called. If it is something different, +@code{GPGME} will take no action. + +This means that if your application does not install any signal +handler for @code{SIGPIPE}, you don't need to take any precautions. +If you do install a signal handler for @code{SIGPIPE}, you must be +prepared to handle any @code{SIGPIPE} events that occur due to +@acronym{GPGME} writing to a defunct pipe. Furthermore, if your +application is multi-threaded, and you install a signal action for +@code{SIGPIPE}, you must make sure you do this either before +@code{gpgme_check_version} is called or afterwards. + + +@node Multi Threading +@section Multi Threading +@cindex thread-safeness +@cindex multi-threading + +The @acronym{GPGME} library is not entirely thread-safe, but it can +still be used in a multi-threaded environment if some care is taken. +If the following requirements are met, there should be no race +conditions to worry about: + +@itemize @bullet +@item +@acronym{GPGME} supports the thread libraries pthread and GNU Pth. +The support for this has to be enabled at compile time. +@acronym{GPGME} will automatically detect the location in which the +thread libraries are installed and activate the support for them at +build time. + +Support for other thread libraries is very easy to add. Please +contact us if you have the need. + +@item +If you want to use @acronym{GPGME} with threads, you must link to the +right version of the library. The name of the right library is +@code{libgpgme-} followed by the name of the thread package you use. +For example, if you use GNU Pth, the right name is +@code{libgpgme-pth}. Use the Automake macros or +@command{gpgme-config} program for simplicity. + + +@item +The function @code{gpgme_check_version} must be called before any +other function in the library, because it initializes the thread +support subsystem in @acronym{GPGME}. To achieve this in +multi-threaded programs, you must synchronize the memory with respect +to other threads that also want to use @acronym{GPGME}. For this, it +is sufficient to call @code{gpgme_check_version} before creating the +other threads using @acronym{GPGME}@footnote{At least this is true for +POSIX threads, as @code{pthread_create} is a function that +synchronizes memory with respects to other threads. There are many +functions which have this property, a complete list can be found in +POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in the +definition of the term ``Memory Synchronization''. For other thread +packages other, more relaxed or more strict rules may apply.}. + +@item +Any @code{gpgme_data_t} and @code{gpgme_ctx_t} object must only be +accessed by one thread at a time. If multiple threads want to deal +with the same object, the caller has to make sure that operations on +that object are fully synchronized. + +@item +Only one thread at any time is allowed to call @code{gpgme_wait}. If +multiple threads call this function, the caller must make sure that +all invocations are fully synchronized. It is safe to start +asynchronous operations while a thread is running in gpgme_wait. + +@item +The function @code{gpgme_strerror} is not thread safe. You have to +use @code{gpgme_strerror_r} instead. +@end itemize + + +@node Protocols and Engines +@chapter Protocols and Engines +@cindex protocol +@cindex engine +@cindex crypto engine +@cindex backend +@cindex crypto backend + +@acronym{GPGME} supports several cryptographic protocols, however, it +does not implement them. Rather it uses backends (also called +engines) which implement the protocol. @acronym{GPGME} uses +inter-process communication to pass data back and forth between the +application and the backend, but the details of the communication +protocol and invocation of the backend is completely hidden by the +interface. All complexity is handled by @acronym{GPGME}. Where an +exchange of information between the application and the backend is +necessary, @acronym{GPGME} provides the necessary callback function +hooks and further interfaces. + +@deftp {Data type} {enum gpgme_protocol_t} +@tindex gpgme_protocol_t +The @code{gpgme_protocol_t} type specifies the set of possible protocol +values that are supported by @acronym{GPGME}. The following protocols +are supported: + +@table @code +@item GPGME_PROTOCOL_OpenPGP +This specifies the OpenPGP protocol. + +@item GPGME_PROTOCOL_CMS +This specifies the Cryptographic Message Syntax. + +@item GPGME_PROTOCOL_ASSUAN +Under development. Please ask on @email{gnupg-devel@@gnupg.org} for help. + +@item GPGME_PROTOCOL_G13 +Under development. Please ask on @email{gnupg-devel@@gnupg.org} for help. + +@item GPGME_PROTOCOL_UISERVER +Under development. Please ask on @email{gnupg-devel@@gnupg.org} for help. + +@item GPGME_PROTOCOL_UNKNOWN +Reserved for future extension. You may use this to indicate that the +used protocol is not known to the application. Currently, +@acronym{GPGME} does not accept this value in any operation, though, +except for @code{gpgme_get_protocol_name}. +@end table +@end deftp + + +@deftypefun {const char *} gpgme_get_protocol_name (@w{gpgme_protocol_t @var{protocol}}) +The function @code{gpgme_get_protocol_name} returns a statically +allocated string describing the protocol @var{protocol}, or +@code{NULL} if the protocol number is not valid. +@end deftypefun + +@menu +* Engine Version Check:: Verifying the engine version. +* Engine Information:: Obtaining more information about the engines. +* Engine Configuration:: Changing the engine configuration. +* OpenPGP:: Support for the OpenPGP protocol. +* Cryptographic Message Syntax:: Support for the CMS. +@end menu + + +@node Engine Version Check +@section Engine Version Check +@cindex version check, of the engines + +@deftypefun gpgme_error_t gpgme_engine_check_version (@w{gpgme_protocol_t @var{protocol}}) +The function @code{gpgme_engine_check_version} verifies that the +engine implementing the protocol @var{PROTOCOL} is installed in the +expected path and meets the version requirement of @acronym{GPGME}. + +This function returns the error code @code{GPG_ERR_NO_ERROR} if the +engine is available and @code{GPG_ERR_INV_ENGINE} if it is not. +@end deftypefun + + +@node Engine Information +@section Engine Information +@cindex engine, information about + +@deftp {Data type} {gpgme_engine_info_t} +@tindex gpgme_protocol_t +The @code{gpgme_engine_info_t} type specifies a pointer to a structure +describing a crypto engine. The structure contains the following +elements: + +@table @code +@item gpgme_engine_info_t next +This is a pointer to the next engine info structure in the linked +list, or @code{NULL} if this is the last element. + +@item gpgme_protocol_t protocol +This is the protocol for which the crypto engine is used. You can +convert this to a string with @code{gpgme_get_protocol_name} for +printing. + +@item const char *file_name +This is a string holding the file name of the executable of the crypto +engine. Currently, it is never @code{NULL}, but using @code{NULL} is +reserved for future use, so always check before you use it. + +@item const char *home_dir +This is a string holding the directory name of the crypto engine's +configuration directory. If it is @code{NULL}, then the default +directory is used. + +@item const char *version +This is a string containing the version number of the crypto engine. +It might be @code{NULL} if the version number can not be determined, +for example because the executable doesn't exist or is invalid. + +@item const char *req_version +This is a string containing the minimum required version number of the +crypto engine for @acronym{GPGME} to work correctly. This is the +version number that @code{gpgme_engine_check_version} verifies +against. Currently, it is never @code{NULL}, but using @code{NULL} is +reserved for future use, so always check before you use it. +@end table +@end deftp + +@deftypefun gpgme_error_t gpgme_get_engine_info (@w{gpgme_engine_info_t *@var{info}}) +The function @code{gpgme_get_engine_info} returns a linked list of +engine info structures in @var{info}. Each info structure describes +the defaults of one configured backend. + +The memory for the info structures is allocated the first time this +function is invoked, and must not be freed by the caller. + +This function returns the error code @code{GPG_ERR_NO_ERROR} if +successful, and a system error if the memory could not be allocated. +@end deftypefun + +Here is an example how you can provide more diagnostics if you receive +an error message which indicates that the crypto engine is invalid. + +@example +gpgme_ctx_t ctx; +gpgme_error_t err; + +[...] + +if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE) + @{ + gpgme_engine_info_t info; + err = gpgme_get_engine_info (&info); + if (!err) + @{ + while (info && info->protocol != gpgme_get_protocol (ctx)) + info = info->next; + if (!info) + fprintf (stderr, "GPGME compiled without support for protocol %s", + gpgme_get_protocol_name (info->protocol)); + else if (info->file_name && !info->version) + fprintf (stderr, "Engine %s not installed properly", + info->file_name); + else if (info->file_name && info->version && info->req_version) + fprintf (stderr, "Engine %s version %s installed, " + "but at least version %s required", info->file_name, + info->version, info->req_version); + else + fprintf (stderr, "Unknown problem with engine for protocol %s", + gpgme_get_protocol_name (info->protocol)); + @} + @} +@end example + + +@node Engine Configuration +@section Engine Configuration +@cindex engine, configuration of +@cindex configuration of crypto backend + +You can change the configuration of a backend engine, and thus change +the executable program and configuration directory to be used. You +can make these changes the default or set them for some contexts +individually. + +@deftypefun gpgme_error_t gpgme_set_engine_info (@w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}}) +The function @code{gpgme_set_engine_info} changes the default +configuration of the crypto engine implementing the protocol +@var{proto}. + +@var{file_name} is the file name of the executable program +implementing this protocol, and @var{home_dir} is the directory name +of the configuration directory for this crypto engine. If +@var{home_dir} is @code{NULL}, the engine's default will be used. + +The new defaults are not applied to already created GPGME contexts. + +This function returns the error code @code{GPG_ERR_NO_ERROR} if +successful, or an eror code on failure. +@end deftypefun + +The functions @code{gpgme_ctx_get_engine_info} and +@code{gpgme_ctx_set_engine_info} can be used to change the engine +configuration per context. @xref{Crypto Engine}. + + +@node OpenPGP +@section OpenPGP +@cindex OpenPGP +@cindex GnuPG +@cindex protocol, GnuPG +@cindex engine, GnuPG + +OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard. +This is the first protocol that was supported by @acronym{GPGME}. + +The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}. + + +@node Cryptographic Message Syntax +@section Cryptographic Message Syntax +@cindex CMS +@cindex cryptographic message syntax +@cindex GpgSM +@cindex protocol, CMS +@cindex engine, GpgSM +@cindex S/MIME +@cindex protocol, S/MIME + +@acronym{CMS} is implemented by GpgSM, the S/MIME implementation for +GnuPG. + +The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}. + + +@node Algorithms +@chapter Algorithms +@cindex algorithms + +The crypto backends support a variety of algorithms used in public key +cryptography.@footnote{Some engines also provide symmetric only +encryption; see the description of the encryption function on how to use +this.} The following sections list the identifiers used to denote such +an algorithm. + +@menu +* Public Key Algorithms:: A list of all public key algorithms. +* Hash Algorithms:: A list of all hash algorithms. +@end menu + + +@node Public Key Algorithms +@section Public Key Algorithms +@cindex algorithms, public key +@cindex public key algorithms + +Public key algorithms are used for encryption, decryption, signing and +verification of signatures. + +@deftp {Data type} {enum gpgme_pubkey_algo_t} +@tindex gpgme_pubkey_algo_t +The @code{gpgme_pubkey_algo_t} type specifies the set of all public key +algorithms that are supported by @acronym{GPGME}. Possible values +are: + +@table @code +@item GPGME_PK_RSA +This value indicates the RSA (Rivest, Shamir, Adleman) algorithm. + +@item GPGME_PK_RSA_E +Deprecated. This value indicates the RSA (Rivest, Shamir, Adleman) +algorithm for encryption and decryption only. + +@item GPGME_PK_RSA_S +Deprecated. This value indicates the RSA (Rivest, Shamir, Adleman) +algorithm for signing and verification only. + +@item GPGME_PK_DSA +This value indicates DSA, the Digital Signature Algorithm. + +@item GPGME_PK_ELG +This value indicates ElGamal. + +@item GPGME_PK_ELG_E +This value also indicates ElGamal and is used specifically in GnuPG. + +@item GPGME_PK_ELG_E +This value also indicates ElGamal and is used specifically in GnuPG. + +@item GPGME_PK_ECDSA +This value indicates ECDSA, the Elliptic Curve Digital Signature +Algorithm as defined by FIPS 186-2. + +@item GPGME_PK_ECDH +This value indicates ECDH, the Eliptic Curve Diffie-Hellmann encryption +algorithm as defined by the ECC in OpenPGP draft. + +@end table +@end deftp + +@deftypefun {const char *} gpgme_pubkey_algo_name (@w{gpgme_pubkey_algo_t @var{algo}}) +The function @code{gpgme_pubkey_algo_name} returns a pointer to a +statically allocated string containing a description of the public key +algorithm @var{algo}. This string can be used to output the name of +the public key algorithm to the user. + +If @var{algo} is not a valid public key algorithm, @code{NULL} is +returned. +@end deftypefun + + +@node Hash Algorithms +@section Hash Algorithms +@cindex algorithms, hash +@cindex algorithms, message digest +@cindex hash algorithms +@cindex message digest algorithms + +Hash (message digest) algorithms are used to compress a long message +to make it suitable for public key cryptography. + +@deftp {Data type} {enum gpgme_hash_algo_t} +@tindex gpgme_hash_algo_t +The @code{gpgme_hash_algo_t} type specifies the set of all hash algorithms +that are supported by @acronym{GPGME}. Possible values are: + +@table @code +@item GPGME_MD_MD5 +@item GPGME_MD_SHA1 +@item GPGME_MD_RMD160 +@item GPGME_MD_MD2 +@item GPGME_MD_TIGER +@item GPGME_MD_HAVAL +@item GPGME_MD_SHA256 +@item GPGME_MD_SHA384 +@item GPGME_MD_SHA512 +@item GPGME_MD_MD4 +@item GPGME_MD_CRC32 +@item GPGME_MD_CRC32_RFC1510 +@item GPGME_MD_CRC24_RFC2440 +@end table +@end deftp + +@deftypefun {const char *} gpgme_hash_algo_name (@w{gpgme_hash_algo_t @var{algo}}) +The function @code{gpgme_hash_algo_name} returns a pointer to a +statically allocated string containing a description of the hash +algorithm @var{algo}. This string can be used to output the name of +the hash algorithm to the user. + +If @var{algo} is not a valid hash algorithm, @code{NULL} is returned. +@end deftypefun + + +@node Error Handling +@chapter Error Handling +@cindex error handling + +Many functions in @acronym{GPGME} can return an error if they fail. +For this reason, the application should always catch the error +condition and take appropriate measures, for example by releasing the +resources and passing the error up to the caller, or by displaying a +descriptive message to the user and cancelling the operation. + +Some error values do not indicate a system error or an error in the +operation, but the result of an operation that failed properly. For +example, if you try to decrypt a tempered message, the decryption will +fail. Another error value actually means that the end of a data +buffer or list has been reached. The following descriptions explain +for many error codes what they mean usually. Some error values have +specific meanings if returned by a certain functions. Such cases are +described in the documentation of those functions. + +@acronym{GPGME} uses the @code{libgpg-error} library. This allows to +share the error codes with other components of the GnuPG system, and +thus pass error values transparently from the crypto engine, or some +helper application of the crypto engine, to the user. This way no +information is lost. As a consequence, @acronym{GPGME} does not use +its own identifiers for error codes, but uses those provided by +@code{libgpg-error}. They usually start with @code{GPG_ERR_}. + +However, @acronym{GPGME} does provide aliases for the functions +defined in libgpg-error, which might be preferred for name space +consistency. + +@menu +* Error Values:: The error value and what it means. +* Error Sources:: A list of important error sources. +* Error Codes:: A list of important error codes. +* Error Strings:: How to get a descriptive string from a value. +@end menu + + +@node Error Values +@section Error Values +@cindex error values +@cindex error codes +@cindex error sources + +@deftp {Data type} {gpgme_err_code_t} +The @code{gpgme_err_code_t} type is an alias for the @code{libgpg-error} +type @code{gpg_err_code_t}. The error code indicates the type of an +error, or the reason why an operation failed. + +A list of important error codes can be found in the next section. +@end deftp + +@deftp {Data type} {gpgme_err_source_t} +The @code{gpgme_err_source_t} type is an alias for the +@code{libgpg-error} type @code{gpg_err_source_t}. The error source +has not a precisely defined meaning. Sometimes it is the place where +the error happened, sometimes it is the place where an error was +encoded into an error value. Usually the error source will give an +indication to where to look for the problem. This is not always true, +but it is attempted to achieve this goal. + +A list of important error sources can be found in the next section. +@end deftp + +@deftp {Data type} {gpgme_error_t} +The @code{gpgme_error_t} type is an alias for the @code{libgpg-error} +type @code{gpg_error_t}. An error value like this has always two +components, an error code and an error source. Both together form the +error value. + +Thus, the error value can not be directly compared against an error +code, but the accessor functions described below must be used. +However, it is guaranteed that only 0 is used to indicate success +(@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of +the error value are set to 0, too. + +Note that in @acronym{GPGME}, the error source is used purely for +diagnostical purposes. Only the error code should be checked to test +for a certain outcome of a function. The manual only documents the +error code part of an error value. The error source is left +unspecified and might be anything. +@end deftp + +@deftypefun {static inline gpgme_err_code_t} gpgme_err_code (@w{gpgme_error_t @var{err}}) +The static inline function @code{gpgme_err_code} returns the +@code{gpgme_err_code_t} component of the error value @var{err}. This +function must be used to extract the error code from an error value in +order to compare it with the @code{GPG_ERR_*} error code macros. +@end deftypefun + +@deftypefun {static inline gpgme_err_source_t} gpgme_err_source (@w{gpgme_error_t @var{err}}) +The static inline function @code{gpgme_err_source} returns the +@code{gpgme_err_source_t} component of the error value @var{err}. This +function must be used to extract the error source from an error value in +order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros. +@end deftypefun + +@deftypefun {static inline gpgme_error_t} gpgme_err_make (@w{gpgme_err_source_t @var{source}}, @w{gpgme_err_code_t @var{code}}) +The static inline function @code{gpgme_err_make} returns the error +value consisting of the error source @var{source} and the error code +@var{code}. + +This function can be used in callback functions to construct an error +value to return it to the library. +@end deftypefun + +@deftypefun {static inline gpgme_error_t} gpgme_error (@w{gpgme_err_code_t @var{code}}) +The static inline function @code{gpgme_error} returns the error value +consisting of the default error source and the error code @var{code}. + +For @acronym{GPGME} applications, the default error source is +@code{GPG_ERR_SOURCE_USER_1}. You can define +@code{GPGME_ERR_SOURCE_DEFAULT} before including @file{gpgme.h} to +change this default. + +This function can be used in callback functions to construct an error +value to return it to the library. +@end deftypefun + +The @code{libgpg-error} library provides error codes for all system +error numbers it knows about. If @var{err} is an unknown error +number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used. The +following functions can be used to construct error values from system +errnor numbers. + +@deftypefun {gpgme_error_t} gpgme_err_make_from_errno (@w{gpgme_err_source_t @var{source}}, @w{int @var{err}}) +The function @code{gpgme_err_make_from_errno} is like +@code{gpgme_err_make}, but it takes a system error like @code{errno} +instead of a @code{gpgme_err_code_t} error code. +@end deftypefun + +@deftypefun {gpgme_error_t} gpgme_error_from_errno (@w{int @var{err}}) +The function @code{gpgme_error_from_errno} is like @code{gpgme_error}, +but it takes a system error like @code{errno} instead of a +@code{gpgme_err_code_t} error code. +@end deftypefun + +Sometimes you might want to map system error numbers to error codes +directly, or map an error code representing a system error back to the +system error number. The following functions can be used to do that. + +@deftypefun {gpgme_err_code_t} gpgme_err_code_from_errno (@w{int @var{err}}) +The function @code{gpgme_err_code_from_errno} returns the error code +for the system error @var{err}. If @var{err} is not a known system +error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}. +@end deftypefun + +@deftypefun {int} gpgme_err_code_to_errno (@w{gpgme_err_code_t @var{err}}) +The function @code{gpgme_err_code_to_errno} returns the system error +for the error code @var{err}. If @var{err} is not an error code +representing a system error, or if this system error is not defined on +this system, the function returns @code{0}. +@end deftypefun + + +@node Error Sources +@section Error Sources +@cindex error codes, list of + +The library @code{libgpg-error} defines an error source for every +component of the GnuPG system. The error source part of an error +value is not well defined. As such it is mainly useful to improve the +diagnostic error message for the user. + +If the error code part of an error value is @code{0}, the whole error +value will be @code{0}. In this case the error source part is of +course @code{GPG_ERR_SOURCE_UNKNOWN}. + +The list of error sources that might occur in applications using +@acronym{GPGME} is: + +@table @code +@item GPG_ERR_SOURCE_UNKNOWN +The error source is not known. The value of this error source is +@code{0}. + +@item GPG_ERR_SOURCE_GPGME +The error source is @acronym{GPGME} itself. This is the default for +errors that occur in the @acronym{GPGME} library. + +@item GPG_ERR_SOURCE_GPG +The error source is GnuPG, which is the crypto engine used for the +OpenPGP protocol. + +@item GPG_ERR_SOURCE_GPGSM +The error source is GPGSM, which is the crypto engine used for the +CMS protocol. + +@item GPG_ERR_SOURCE_GCRYPT +The error source is @code{libgcrypt}, which is used by crypto engines +to perform cryptographic operations. + +@item GPG_ERR_SOURCE_GPGAGENT +The error source is @command{gpg-agent}, which is used by crypto +engines to perform operations with the secret key. + +@item GPG_ERR_SOURCE_PINENTRY +The error source is @command{pinentry}, which is used by +@command{gpg-agent} to query the passphrase to unlock a secret key. + +@item GPG_ERR_SOURCE_SCD +The error source is the SmartCard Daemon, which is used by +@command{gpg-agent} to delegate operations with the secret key to a +SmartCard. + +@item GPG_ERR_SOURCE_KEYBOX +The error source is @code{libkbx}, a library used by the crypto +engines to manage local keyrings. + +@item GPG_ERR_SOURCE_USER_1 +@item GPG_ERR_SOURCE_USER_2 +@item GPG_ERR_SOURCE_USER_3 +@item GPG_ERR_SOURCE_USER_4 +These error sources are not used by any GnuPG component and can be +used by other software. For example, applications using +@acronym{GPGME} can use them to mark error values coming from callback +handlers. Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors +created with @code{gpgme_error} and @code{gpgme_error_from_errno}, +unless you define @code{GPGME_ERR_SOURCE_DEFAULT} before including +@file{gpgme.h}. +@end table + + +@node Error Codes +@section Error Codes +@cindex error codes, list of + +The library @code{libgpg-error} defines many error values. Most of +them are not used by @code{GPGME} directly, but might be returned by +@acronym{GPGME} because it received them from the crypto engine. The +below list only includes such error codes that have a specific meaning +in @code{GPGME}, or which are so common that you should know about +them. + +@table @code +@item GPG_ERR_EOF +This value indicates the end of a list, buffer or file. + +@item GPG_ERR_NO_ERROR +This value indicates success. The value of this error code is +@code{0}. Also, it is guaranteed that an error value made from the +error code @code{0} will be @code{0} itself (as a whole). This means +that the error source information is lost for this error code, +however, as this error code indicates that no error occured, this is +generally not a problem. + +@item GPG_ERR_GENERAL +This value means that something went wrong, but either there is not +enough information about the problem to return a more useful error +value, or there is no separate error value for this type of problem. + +@item GPG_ERR_ENOMEM +This value means that an out-of-memory condition occurred. + +@item GPG_ERR_E... +System errors are mapped to GPG_ERR_FOO where FOO is the symbol for +the system error. + +@item GPG_ERR_INV_VALUE +This value means that some user provided data was out of range. This +can also refer to objects. For example, if an empty +@code{gpgme_data_t} object was expected, but one containing data was +provided, this error value is returned. + +@item GPG_ERR_UNUSABLE_PUBKEY +This value means that some recipients for a message were invalid. + +@item GPG_ERR_UNUSABLE_SECKEY +This value means that some signers were invalid. + +@item GPG_ERR_NO_DATA +This value means that a @code{gpgme_data_t} object which was expected +to have content was found empty. + +@item GPG_ERR_CONFLICT +This value means that a conflict of some sort occurred. + +@item GPG_ERR_NOT_IMPLEMENTED +This value indicates that the specific function (or operation) is not +implemented. This error should never happen. It can only occur if +you use certain values or configuration options which do not work, +but for which we think that they should work at some later time. + +@item GPG_ERR_DECRYPT_FAILED +This value indicates that a decryption operation was unsuccessful. + +@item GPG_ERR_BAD_PASSPHRASE +This value means that the user did not provide a correct passphrase +when requested. + +@item GPG_ERR_CANCELED +This value means that the operation was canceled. + +@item GPG_ERR_INV_ENGINE +This value means that the engine that implements the desired protocol +is currently not available. This can either be because the sources +were configured to exclude support for this engine, or because the +engine is not installed properly. + +@item GPG_ERR_AMBIGUOUS_NAME +This value indicates that a user ID or other specifier did not specify +a unique key. + +@item GPG_ERR_WRONG_KEY_USAGE +This value indicates that a key is not used appropriately. + +@item GPG_ERR_CERT_REVOKED +This value indicates that a key signature was revoced. + +@item GPG_ERR_CERT_EXPIRED +This value indicates that a key signature expired. + +@item GPG_ERR_NO_CRL_KNOWN +This value indicates that no certificate revocation list is known for +the certificate. + +@item GPG_ERR_NO_POLICY_MATCH +This value indicates that a policy issue occured. + +@item GPG_ERR_NO_SECKEY +This value indicates that no secret key for the user ID is available. + +@item GPG_ERR_MISSING_CERT +This value indicates that a key could not be imported because the +issuer certificate is missing. + +@item GPG_ERR_BAD_CERT_CHAIN +This value indicates that a key could not be imported because its +certificate chain is not good, for example it could be too long. + +@item GPG_ERR_UNSUPPORTED_ALGORITHM +This value means a verification failed because the cryptographic +algorithm is not supported by the crypto backend. + +@item GPG_ERR_BAD_SIGNATURE +This value means a verification failed because the signature is bad. + +@item GPG_ERR_NO_PUBKEY +This value means a verification failed because the public key is not +available. + +@item GPG_ERR_USER_1 +@item GPG_ERR_USER_2 +@item ... +@item GPG_ERR_USER_16 +These error codes are not used by any GnuPG component and can be +freely used by other software. Applications using @acronym{GPGME} +might use them to mark specific errors returned by callback handlers +if no suitable error codes (including the system errors) for +these errors exist already. +@end table + + +@node Error Strings +@section Error Strings +@cindex error values, printing of +@cindex error codes, printing of +@cindex error sources, printing of +@cindex error strings + +@deftypefun {const char *} gpgme_strerror (@w{gpgme_error_t @var{err}}) +The function @code{gpgme_strerror} returns a pointer to a statically +allocated string containing a description of the error code contained +in the error value @var{err}. This string can be used to output a +diagnostic message to the user. + +This function is not thread safe. Use @code{gpgme_strerror_r} in +multi-threaded programs. +@end deftypefun + + +@deftypefun {int} gpgme_strerror_r (@w{gpgme_error_t @var{err}}, @w{char *@var{buf}}, @w{size_t @var{buflen}}) +The function @code{gpgme_strerror_r} returns the error string for +@var{err} in the user-supplied buffer @var{buf} of size @var{buflen}. +This function is, in contrast to @code{gpgme_strerror}, thread-safe if +a thread-safe @code{strerror_r} function is provided by the system. +If the function succeeds, 0 is returned and @var{buf} contains the +string describing the error. If the buffer was not large enough, +ERANGE is returned and @var{buf} contains as much of the beginning of +the error string as fits into the buffer. +@end deftypefun + + +@deftypefun {const char *} gpgme_strsource (@w{gpgme_error_t @var{err}}) +The function @code{gpgme_strerror} returns a pointer to a statically +allocated string containing a description of the error source +contained in the error value @var{err}. This string can be used to +output a diagnostic message to the user. +@end deftypefun + +The following example illustrates the use of @code{gpgme_strerror}: + +@example +gpgme_ctx_t ctx; +gpgme_error_t err = gpgme_new (&ctx); +if (err) + @{ + fprintf (stderr, "%s: creating GpgME context failed: %s: %s\n", + argv[0], gpgme_strsource (err), gpgme_strerror (err)); + exit (1); + @} +@end example + + +@node Exchanging Data +@chapter Exchanging Data +@cindex data, exchanging + +A lot of data has to be exchanged between the user and the crypto +engine, like plaintext messages, ciphertext, signatures and +information about the keys. The technical details about exchanging +the data information are completely abstracted by @acronym{GPGME}. +The user provides and receives the data via @code{gpgme_data_t} objects, +regardless of the communication protocol between @acronym{GPGME} and +the crypto engine in use. + +@deftp {Data type} {gpgme_data_t} +The @code{gpgme_data_t} type is a handle for a container for generic +data, which is used by @acronym{GPGME} to exchange data with the user. +@end deftp + +@code{gpgme_data_t} objects do not provide notifications on events. +It is assumed that read and write operations are blocking until data +is available. If this is undesirable, the application must ensure +that all GPGME data operations always have data available, for example +by using memory buffers or files rather than pipes or sockets. This +might be relevant, for example, if the external event loop mechanism +is used. + +@menu +* Creating Data Buffers:: Creating new data buffers. +* Destroying Data Buffers:: Releasing data buffers. +* Manipulating Data Buffers:: Operations on data buffers. +@end menu + + +@node Creating Data Buffers +@section Creating Data Buffers +@cindex data buffer, creation + +Data objects can be based on memory, files, or callback functions +provided by the user. Not all operations are supported by all +objects. + + +@menu +* Memory Based Data Buffers:: Creating memory based data buffers. +* File Based Data Buffers:: Creating file based data buffers. +* Callback Based Data Buffers:: Creating callback based data buffers. +@end menu + + +@node Memory Based Data Buffers +@subsection Memory Based Data Buffers + +Memory based data objects store all data in allocated memory. This is +convenient, but only practical for an amount of data that is a +fraction of the available physical memory. The data has to be copied +from its source and to its destination, which can often be avoided by +using one of the other data object + +@deftypefun gpgme_error_t gpgme_data_new (@w{gpgme_data_t *@var{dh}}) +The function @code{gpgme_data_new} creates a new @code{gpgme_data_t} +object and returns a handle for it in @var{dh}. The data object is +memory based and initially empty. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +data object was successfully created, @code{GPG_ERR_INV_VALUE} if +@var{dh} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not +enough memory is available. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_data_new_from_mem (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{size}}, @w{int @var{copy}}) +The function @code{gpgme_data_new_from_mem} creates a new +@code{gpgme_data_t} object and fills it with @var{size} bytes starting +from @var{buffer}. + +If @var{copy} is not zero, a private copy of the data is made. If +@var{copy} is zero, the data is taken from the specified buffer as +needed, and the user has to ensure that the buffer remains valid for +the whole life span of the data object. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +data object was successfully created, @code{GPG_ERR_INV_VALUE} if +@var{dh} or @var{buffer} is not a valid pointer, and +@code{GPG_ERR_ENOMEM} if not enough memory is available. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_data_new_from_file (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}}) +The function @code{gpgme_data_new_from_file} creates a new +@code{gpgme_data_t} object and fills it with the content of the file +@var{filename}. + +If @var{copy} is not zero, the whole file is read in at initialization +time and the file is not used anymore after that. This is the only +mode supported currently. Later, a value of zero for @var{copy} might +cause all reads to be delayed until the data is needed, but this is +not yet implemented. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +data object was successfully created, @code{GPG_ERR_INV_VALUE} if +@var{dh} or @var{filename} is not a valid pointer, +@code{GPG_ERR_NOT_IMPLEMENTED} if @var{code} is zero, and +@code{GPG_ERR_ENOMEM} if not enough memory is available. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_data_new_from_filepart (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{FILE *@var{fp}}, @w{off_t @var{offset}}, @w{size_t @var{length}}) +The function @code{gpgme_data_new_from_filepart} creates a new +@code{gpgme_data_t} object and fills it with a part of the file specified +by @var{filename} or @var{fp}. + +Exactly one of @var{filename} and @var{fp} must be non-zero, the other +must be zero. The argument that is not zero specifies the file from +which @var{length} bytes are read into the data object, starting from +@var{offset}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +data object was successfully created, @code{GPG_ERR_INV_VALUE} if +@var{dh} and exactly one of @var{filename} and @var{fp} is not a valid +pointer, and @code{GPG_ERR_ENOMEM} if not enough memory is available. +@end deftypefun + + +@node File Based Data Buffers +@subsection File Based Data Buffers + +File based data objects operate directly on file descriptors or +streams. Only a small amount of data is stored in core at any time, +so the size of the data objects is not limited by @acronym{GPGME}. + +@deftypefun gpgme_error_t gpgme_data_new_from_fd (@w{gpgme_data_t *@var{dh}}, @w{int @var{fd}}) +The function @code{gpgme_data_new_from_fd} creates a new +@code{gpgme_data_t} object and uses the file descriptor @var{fd} to read +from (if used as an input data object) and write to (if used as an +output data object). + +When using the data object as an input buffer, the function might read +a bit more from the file descriptor than is actually needed by the +crypto engine in the desired operation because of internal buffering. + +Note that GPGME assumes that the file descriptor is set to blocking +mode. Errors during I/O operations, except for EINTR, are usually +fatal for crypto operations. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +data object was successfully created, and @code{GPG_ERR_ENOMEM} if not +enough memory is available. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_data_new_from_stream (@w{gpgme_data_t *@var{dh}}, @w{FILE *@var{stream}}) +The function @code{gpgme_data_new_from_stream} creates a new +@code{gpgme_data_t} object and uses the I/O stream @var{stream} to read +from (if used as an input data object) and write to (if used as an +output data object). + +When using the data object as an input buffer, the function might read +a bit more from the stream than is actually needed by the crypto +engine in the desired operation because of internal buffering. + +Note that GPGME assumes that the stream is in blocking mode. Errors +during I/O operations, except for EINTR, are usually fatal for crypto +operations. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +data object was successfully created, and @code{GPG_ERR_ENOMEM} if not +enough memory is available. +@end deftypefun + + +@node Callback Based Data Buffers +@subsection Callback Based Data Buffers + +If neither memory nor file based data objects are a good fit for your +application, you can implement the functions a data object provides +yourself and create a data object from these callback functions. + +@deftp {Data type} {ssize_t (*gpgme_data_read_cb_t) (@w{void *@var{handle}}, @w{void @var{*buffer}}, @w{size_t @var{size}})} +@tindex gpgme_data_read_cb_t +The @code{gpgme_data_read_cb_t} type is the type of functions which +@acronym{GPGME} calls if it wants to read data from a user-implemented +data object. The function should read up to @var{size} bytes from the +current read position into the space starting at @var{buffer}. The +@var{handle} is provided by the user at data object creation time. + +Note that GPGME assumes that the read blocks until data is available. +Errors during I/O operations, except for EINTR, are usually fatal for +crypto operations. + +The function should return the number of bytes read, 0 on EOF, and -1 +on error. If an error occurs, @var{errno} should be set to describe +the type of the error. +@end deftp + +@deftp {Data type} {ssize_t (*gpgme_data_write_cb_t) (@w{void *@var{handle}}, @w{const void @var{*buffer}}, @w{size_t @var{size}})} +@tindex gpgme_data_write_cb_t +The @code{gpgme_data_write_cb_t} type is the type of functions which +@acronym{GPGME} calls if it wants to write data to a user-implemented +data object. The function should write up to @var{size} bytes to the +current write position from the space starting at @var{buffer}. The +@var{handle} is provided by the user at data object creation time. + +Note that GPGME assumes that the write blocks until data is available. +Errors during I/O operations, except for EINTR, are usually fatal for +crypto operations. + +The function should return the number of bytes written, and -1 on +error. If an error occurs, @var{errno} should be set to describe the +type of the error. +@end deftp + +@deftp {Data type} {off_t (*gpgme_data_seek_cb_t) (@w{void *@var{handle}}, @w{off_t @var{offset}}, @w{int @var{whence}})} +@tindex gpgme_data_seek_cb_t +The @code{gpgme_data_seek_cb_t} type is the type of functions which +@acronym{GPGME} calls if it wants to change the current read/write +position in a user-implemented data object, just like the @code{lseek} +function. + +The function should return the new read/write position, and -1 on +error. If an error occurs, @var{errno} should be set to describe the +type of the error. +@end deftp + +@deftp {Data type} {void (*gpgme_data_release_cb_t) (@w{void *@var{handle}})} +@tindex gpgme_data_release_cb_t +The @code{gpgme_data_release_cb_t} type is the type of functions which +@acronym{GPGME} calls if it wants to destroy a user-implemented data +object. The @var{handle} is provided by the user at data object +creation time. +@end deftp + +@deftp {Data type} {struct gpgme_data_cbs} +This structure is used to store the data callback interface functions +described above. It has the following members: + +@table @code +@item gpgme_data_read_cb_t read +This is the function called by @acronym{GPGME} to read data from the +data object. It is only required for input data object. + +@item gpgme_data_write_cb_t write +This is the function called by @acronym{GPGME} to write data to the +data object. It is only required for output data object. + +@item gpgme_data_seek_cb_t seek +This is the function called by @acronym{GPGME} to change the current +read/write pointer in the data object (if available). It is optional. + +@item gpgme_data_release_cb_t release +This is the function called by @acronym{GPGME} to release a data +object. It is optional. +@end table +@end deftp + +@deftypefun gpgme_error_t gpgme_data_new_from_cbs (@w{gpgme_data_t *@var{dh}}, @w{gpgme_data_cbs_t @var{cbs}}, @w{void *@var{handle}}) +The function @code{gpgme_data_new_from_cbs} creates a new +@code{gpgme_data_t} object and uses the user-provided callback functions +to operate on the data object. + +The handle @var{handle} is passed as first argument to the callback +functions. This can be used to identify this data object. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +data object was successfully created, and @code{GPG_ERR_ENOMEM} if not +enough memory is available. +@end deftypefun + +The following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of @acronym{GPGME}. + +@deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}}) +The function @code{gpgme_data_new_with_read_cb} creates a new +@code{gpgme_data_t} object and uses the callback function @var{readfunc} +to retrieve the data on demand. As the callback function can supply +the data in any way it wants, this is the most flexible data type +@acronym{GPGME} provides. However, it can not be used to write data. + +The callback function receives @var{hook_value} as its first argument +whenever it is invoked. It should return up to @var{count} bytes in +@var{buffer}, and return the number of bytes actually read in +@var{nread}. It may return @code{0} in @var{nread} if no data is +currently available. To indicate @code{EOF} the function should +return with an error code of @code{-1} and set @var{nread} to +@code{0}. The callback function may support to reset its internal +read pointer if it is invoked with @var{buffer} and @var{nread} being +@code{NULL} and @var{count} being @code{0}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +data object was successfully created, @code{GPG_ERR_INV_VALUE} if +@var{dh} or @var{readfunc} is not a valid pointer, and +@code{GPG_ERR_ENOMEM} if not enough memory is available. +@end deftypefun + + +@node Destroying Data Buffers +@section Destroying Data Buffers +@cindex data buffer, destruction + +@deftypefun void gpgme_data_release (@w{gpgme_data_t @var{dh}}) +The function @code{gpgme_data_release} destroys the data object with +the handle @var{dh}. It releases all associated resources that were +not provided by the user in the first place. +@end deftypefun + +@deftypefun {char *} gpgme_data_release_and_get_mem (@w{gpgme_data_t @var{dh}}, @w{size_t *@var{length}}) +The function @code{gpgme_data_release_and_get_mem} is like +@code{gpgme_data_release}, except that it returns the data buffer and +its length that was provided by the object. + +The user has to release the buffer with @code{gpgme_free}. In case +the user provided the data buffer in non-copy mode, a copy will be +made for this purpose. + +In case an error returns, or there is no suitable data buffer that can +be returned to the user, the function will return @code{NULL}. In any +case, the data object @var{dh} is destroyed. +@end deftypefun + + +@deftypefun void gpgme_free (@w{void *@var{buffer}}) +The function @code{gpgme_free} releases the memory returned by +@code{gpgme_data_release_and_get_mem}. It should be used instead of +the system libraries @code{free} function in case different allocators +are used in a single program. +@end deftypefun + + +@node Manipulating Data Buffers +@section Manipulating Data Buffers +@cindex data buffer, manipulation + +Data buffers contain data and meta-data. The following operations can +be used to manipulate both. + + +@menu +* Data Buffer I/O Operations:: I/O operations on data buffers. +* Data Buffer Meta-Data:: Meta-data manipulation of data buffers. +@end menu + + +@node Data Buffer I/O Operations +@subsection Data Buffer I/O Operations +@cindex data buffer, I/O operations +@cindex data buffer, read +@cindex data buffer, write +@cindex data buffer, seek + +@deftypefun ssize_t gpgme_data_read (@w{gpgme_data_t @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}}) +The function @code{gpgme_data_read} reads up to @var{length} bytes +from the data object with the handle @var{dh} into the space starting +at @var{buffer}. + +If no error occurs, the actual amount read is returned. If the end of +the data object is reached, the function returns 0. + +In all other cases, the function returns -1 and sets @var{errno}. +@end deftypefun + +@deftypefun ssize_t gpgme_data_write (@w{gpgme_data_t @var{dh}}, @w{const void *@var{buffer}}, @w{size_t @var{size}}) +The function @code{gpgme_data_write} writes up to @var{size} bytes +starting from @var{buffer} into the data object with the handle +@var{dh} at the current write position. + +The function returns the number of bytes actually written, or -1 if an +error occurs. If an error occurs, @var{errno} is set. +@end deftypefun + +@deftypefun off_t gpgme_data_seek (@w{gpgme_data_t @var{dh}}, @w{off_t @var{offset}}, @w{int @var{whence}}) +The function @code{gpgme_data_seek} changes the current read/write +position. + +The @var{whence} argument specifies how the @var{offset} should be +interpreted. It must be one of the following symbolic constants: + +@table @code +@item SEEK_SET +Specifies that @var{offset} is a count of characters from the +beginning of the data object. + +@item SEEK_CUR +Specifies that @var{offset} is a count of characters from the current +file position. This count may be positive or negative. + +@item SEEK_END +Specifies that @var{offset} is a count of characters from the end of +the data object. A negative count specifies a position within the +current extent of the data object; a positive count specifies a +position past the current end. If you set the position past the +current end, and actually write data, you will extend the data object +with zeros up to that position. +@end table + +If successful, the function returns the resulting file position, +measured in bytes from the beginning of the data object. You can use +this feature together with @code{SEEK_CUR} to read the current +read/write position. + +If the function fails, -1 is returned and @var{errno} is set. +@end deftypefun + +The following function is deprecated and should not be used. It will +be removed in a future version of @acronym{GPGME}. + +@deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}}) +The function @code{gpgme_data_rewind} is equivalent to: + +@example + return (gpgme_data_seek (dh, 0, SEEK_SET) == -1) + ? gpgme_error_from_errno (errno) : 0; +@end example +@end deftypefun + + + + +@node Data Buffer Meta-Data +@subsection Data Buffer Meta-Data +@cindex data buffer, meta-data +@cindex data buffer, file name +@cindex data buffer, encoding + +@deftypefun {char *} gpgme_data_get_file_name (@w{gpgme_data_t @var{dh}}) +The function @code{gpgme_data_get_file_name} returns a pointer to a +string containing the file name associated with the data object. The +file name will be stored in the output when encrypting or signing the +data and will be returned to the user when decrypting or verifying the +output data. + +If no error occurs, the string containing the file name is returned. +Otherwise, @code{NULL} will be returned. +@end deftypefun + + +@deftypefun gpgme_error_t gpgme_data_set_file_name (@w{gpgme_data_t @var{dh}}, @w{const char *@var{file_name}}) +The function @code{gpgme_data_set_file_name} sets the file name +associated with the data object. The file name will be stored in the +output when encrypting or signing the data and will be returned to the +user when decrypting or verifying the output data. + +The function returns the error code @code{GPG_ERR_INV_VALUE} if +@var{dh} is not a valid pointer and @code{GPG_ERR_ENOMEM} if not +enough memory is available. +@end deftypefun + + +@deftp {Data type} {enum gpgme_data_encoding_t} +@tindex gpgme_data_encoding_t +The @code{gpgme_data_encoding_t} type specifies the encoding of a +@code{gpgme_data_t} object. For input data objects, the encoding is +useful to give the backend a hint on the type of data. For output +data objects, the encoding can specify the output data format on +certain operations. Please note that not all backends support all +encodings on all operations. The following data types are available: + +@table @code +@item GPGME_DATA_ENCODING_NONE +This specifies that the encoding is not known. This is the default +for a new data object. The backend will try its best to detect the +encoding automatically. + +@item GPGME_DATA_ENCODING_BINARY +This specifies that the data is encoding in binary form; i.e. there is +no special encoding. + +@item GPGME_DATA_ENCODING_BASE64 +This specifies that the data is encoded using the Base-64 encoding +scheme as used by @acronym{MIME} and other protocols. + +@item GPGME_DATA_ENCODING_ARMOR +This specifies that the data is encoded in an armored form as used by +OpenPGP and PEM. + +@item GPGME_DATA_ENCODING_URL +The data is a list of linefeed delimited URLs. This is only useful with +@code{gpgme_op_import}. + +@item GPGME_DATA_ENCODING_URL0 +The data is a list of binary zero delimited URLs. This is only useful +with @code{gpgme_op_import}. + +@item GPGME_DATA_ENCODING_URLESC +The data is a list of linefeed delimited URLs with all control and space +characters percent escaped. This mode is is not yet implemented. + +@end table +@end deftp + +@deftypefun gpgme_data_encoding_t gpgme_data_get_encoding (@w{gpgme_data_t @var{dh}}) +The function @code{gpgme_data_get_encoding} returns the encoding of +the data object with the handle @var{dh}. If @var{dh} is not a valid +pointer (e.g. @code{NULL}) @code{GPGME_DATA_ENCODING_NONE} is +returned. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_data_set_encoding (@w{gpgme_data_t @var{dh}, gpgme_data_encoding_t @var{enc}}) +The function @code{gpgme_data_set_encoding} changes the encoding of +the data object with the handle @var{dh} to @var{enc}. +@end deftypefun + + +@c +@c Chapter Contexts +@c +@node Contexts +@chapter Contexts +@cindex context + +All cryptographic operations in @acronym{GPGME} are performed within a +context, which contains the internal state of the operation as well as +configuration parameters. By using several contexts you can run +several cryptographic operations in parallel, with different +configuration. + +@deftp {Data type} {gpgme_ctx_t} +The @code{gpgme_ctx_t} type is a handle for a @acronym{GPGME} context, +which is used to hold the configuration, status and result of +cryptographic operations. +@end deftp + +@menu +* Creating Contexts:: Creating new @acronym{GPGME} contexts. +* Destroying Contexts:: Releasing @acronym{GPGME} contexts. +* Result Management:: Managing the result of crypto operations. +* Context Attributes:: Setting properties of a context. +* Key Management:: Managing keys with @acronym{GPGME}. +* Trust Item Management:: Managing trust items with @acronym{GPGME}. +* Crypto Operations:: Using a context for cryptography. +* Run Control:: Controlling how operations are run. +@end menu + + +@node Creating Contexts +@section Creating Contexts +@cindex context, creation + +@deftypefun gpgme_error_t gpgme_new (@w{gpgme_ctx_t *@var{ctx}}) +The function @code{gpgme_new} creates a new @code{gpgme_ctx_t} object +and returns a handle for it in @var{ctx}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +context was successfully created, @code{GPG_ERR_INV_VALUE} if +@var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not +enough memory is available. Also, it returns +@code{GPG_ERR_NOT_OPERATIONAL} if @code{gpgme_check_version} was not +called to initialize GPGME, and @code{GPG_ERR_SELFTEST_FAILED} if a +selftest failed. Currently, the only selftest is for Windows MingW32 +targets to see if @code{-mms-bitfields} was used (as required). +@end deftypefun + + +@node Destroying Contexts +@section Destroying Contexts +@cindex context, destruction + +@deftypefun void gpgme_release (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_release} destroys the context with the handle +@var{ctx} and releases all associated resources. +@end deftypefun + + +@node Result Management +@section Result Management +@cindex context, result of operation + +The detailed result of an operation is returned in operation-specific +structures such as @code{gpgme_decrypt_result_t}. The corresponding +retrieval functions such as @code{gpgme_op_decrypt_result} provide +static access to the results after an operation completes. The +following interfaces make it possible to detach a result structure +from its associated context and give it a lifetime beyond that of the +current operation or context. + +@deftypefun void gpgme_result_ref (@w{void *@var{result}}) +The function @code{gpgme_result_ref} acquires an additional reference +for the result @var{result}, which may be of any type +@code{gpgme_*_result_t}. As long as the user holds a reference, the +result structure is guaranteed to be valid and unmodified. +@end deftypefun + +@deftypefun void gpgme_result_unref (@w{void *@var{result}}) +The function @code{gpgme_result_unref} releases a reference for the +result @var{result}. If this was the last reference, the result +structure will be destroyed and all resources associated to it will be +released. +@end deftypefun + +Note that a context may hold its own references to result structures, +typically until the context is destroyed or the next operation is +started. In fact, these references are accessed through the +@code{gpgme_op_*_result} functions. + + +@node Context Attributes +@section Context Attributes +@cindex context, attributes + +@menu +* Protocol Selection:: Selecting the protocol used by a context. +* Crypto Engine:: Configuring the crypto engine. +* ASCII Armor:: Requesting @acronym{ASCII} armored output. +* Text Mode:: Choosing canonical text mode. +* Included Certificates:: Including a number of certificates. +* Key Listing Mode:: Selecting key listing mode. +* Passphrase Callback:: Getting the passphrase from the user. +* Progress Meter Callback:: Being informed about the progress. +* Locale:: Setting the locale of a context. +@end menu + + +@node Protocol Selection +@subsection Protocol Selection +@cindex context, selecting protocol +@cindex protocol, selecting + +@deftypefun gpgme_error_t gpgme_set_protocol (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}}) +The function @code{gpgme_set_protocol} sets the protocol used within +the context @var{ctx} to @var{proto}. All crypto operations will be +performed by the crypto engine configured for that protocol. +@xref{Protocols and Engines}. + +Setting the protocol with @code{gpgme_set_protocol} does not check if +the crypto engine for that protocol is available and installed +correctly. @xref{Engine Version Check}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +protocol could be set successfully, and @code{GPG_ERR_INV_VALUE} if +@var{protocol} is not a valid protocol. +@end deftypefun + +@deftypefun gpgme_protocol_t gpgme_get_protocol (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_get_protocol} retrieves the protocol currently +use with the context @var{ctx}. +@end deftypefun + + +@node Crypto Engine +@subsection Crypto Engine +@cindex context, configuring engine +@cindex engine, configuration per context + +The following functions can be used to set and retrieve the +configuration of the crypto engines of a specific context. The +default can also be retrieved without any particular context. +@xref{Engine Information}. The default can also be changed globally. +@xref{Engine Configuration}. + +@deftypefun gpgme_engine_info_t gpgme_ctx_get_engine_info (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_ctx_get_engine_info} returns a linked list of +engine info structures. Each info structure describes the +configuration of one configured backend, as used by the context +@var{ctx}. + +The result is valid until the next invocation of +@code{gpgme_ctx_set_engine_info} for this particular context. + +This function can not fail. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_ctx_set_engine_info (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}}) +The function @code{gpgme_ctx_set_engine_info} changes the +configuration of the crypto engine implementing the protocol +@var{proto} for the context @var{ctx}. + +@var{file_name} is the file name of the executable program +implementing this protocol, and @var{home_dir} is the directory name +of the configuration directory for this crypto engine. If +@var{home_dir} is @code{NULL}, the engine's default will be used. + +Currently this function must be used before starting the first crypto +operation. It is unspecified if and when the changes will take effect +if the function is called after starting the first operation on the +context @var{ctx}. + +This function returns the error code @code{GPG_ERR_NO_ERROR} if +successful, or an eror code on failure. +@end deftypefun + + +@c FIXME: Unfortunately, using @acronym here breaks texi2dvi. +@node ASCII Armor +@subsection @acronym{ASCII} Armor +@cindex context, armor mode +@cindex @acronym{ASCII} armor +@cindex armor mode + +@deftypefun void gpgme_set_armor (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}}) +The function @code{gpgme_set_armor} specifies if the output should be +@acronym{ASCII} armored. By default, output is not @acronym{ASCII} +armored. + +@acronym{ASCII} armored output is disabled if @var{yes} is zero, and +enabled otherwise. +@end deftypefun + +@deftypefun int gpgme_get_armor (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_get_armor} returns 1 if the output is +@acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is +not a valid pointer. +@end deftypefun + + +@node Text Mode +@subsection Text Mode +@cindex context, text mode +@cindex text mode +@cindex canonical text mode + +@deftypefun void gpgme_set_textmode (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}}) +The function @code{gpgme_set_textmode} specifies if canonical text mode +should be used. By default, text mode is not used. + +Text mode is for example used for the RFC2015 signatures; note that +the updated RFC 3156 mandates that the mail user agent does some +preparations so that text mode is not needed anymore. + +This option is only relevant to the OpenPGP crypto engine, and ignored +by all other engines. + +Canonical text mode is disabled if @var{yes} is zero, and enabled +otherwise. +@end deftypefun + +@deftypefun int gpgme_get_textmode (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_get_textmode} returns 1 if canonical text +mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a +valid pointer. +@end deftypefun + + +@node Included Certificates +@subsection Included Certificates +@cindex certificates, included + +@deftypefun void gpgme_set_include_certs (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{nr_of_certs}}) +The function @code{gpgme_set_include_certs} specifies how many +certificates should be included in an S/MIME signed message. By +default, only the sender's certificate is included. The possible +values of @var{nr_of_certs} are: + +@table @code +@item GPGME_INCLUDE_CERTS_DEFAULT +Fall back to the default of the crypto backend. This is the default +for GPGME. +@item -2 +Include all certificates except the root certificate. +@item -1 +Include all certificates. +@item 0 +Include no certificates. +@item 1 +Include the sender's certificate only. +@item n +Include the first n certificates of the certificates path, starting +from the sender's certificate. The number @code{n} must be positive. +@end table + +Values of @var{nr_of_certs} smaller than -2 are undefined. + +This option is only relevant to the CMS crypto engine, and ignored by +all other engines. +@end deftypefun + +@deftypefun int gpgme_get_include_certs (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_get_include_certs} returns the number of +certificates to include into an S/MIME signed message. +@end deftypefun + + +@node Key Listing Mode +@subsection Key Listing Mode +@cindex key listing mode +@cindex key listing, mode of + +@deftypefun gpgme_error_t gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}}) +The function @code{gpgme_set_keylist_mode} changes the default +behaviour of the key listing functions. The value in @var{mode} is a +bitwise-or combination of one or multiple of the following bit values: + +@table @code +@item GPGME_KEYLIST_MODE_LOCAL +The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local +keyring should be searched for keys in the keylisting operation. This +is the default. + +@item GPGME_KEYLIST_MODE_EXTERN +The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external +source should be searched for keys in the keylisting operation. The +type of external source is dependant on the crypto engine used and +whether it is combined with @code{GPGME_KEYLIST_MODE_LOCAL}. For +example, it can be a remote keyserver or LDAP certificate server. + +@item GPGME_KEYLIST_MODE_SIGS +The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key +signatures should be included in the listed keys. + +@item GPGME_KEYLIST_MODE_SIG_NOTATIONS +The @code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} symbol specifies that the +signature notations on key signatures should be included in the listed +keys. This only works if @code{GPGME_KEYLIST_MODE_SIGS} is also +enabled. + +@item GPGME_KEYLIST_MODE_EPHEMERAL +The @code{GPGME_KEYLIST_MODE_EPHEMERAL} symbol specifies that keys +flagged as ephemeral are included in the listing. + +@item GPGME_KEYLIST_MODE_VALIDATE +The @code{GPGME_KEYLIST_MODE_VALIDATE} symbol specifies that the +backend should do key or certificate validation and not just get the +validity information from an internal cache. This might be an +expensive operation and is in general not useful. Currently only +implemented for the S/MIME backend and ignored for other backends. + +@end table + +At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and +@code{GPGME_KEYLIST_MODE_EXTERN} must be specified. For future binary +compatibility, you should get the current mode with +@code{gpgme_get_keylist_mode} and modify it by setting or clearing the +appropriate bits, and then using that calculated value in the +@code{gpgme_set_keylisting_mode} operation. This will leave all other +bits in the mode value intact (in particular those that are not used +in the current version of the library). + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +mode could be set correctly, and @code{GPG_ERR_INV_VALUE} if @var{ctx} +is not a valid pointer or @var{mode} is not a valid mode. +@end deftypefun + + +@deftypefun gpgme_keylist_mode_t gpgme_get_keylist_mode (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_get_keylist_mode} returns the current key +listing mode of the context @var{ctx}. This value can then be +modified and used in a subsequent @code{gpgme_set_keylist_mode} +operation to only affect the desired bits (and leave all others +intact). + +The function returns 0 if @var{ctx} is not a valid pointer, and the +current mode otherwise. Note that 0 is not a valid mode value. +@end deftypefun + + +@node Passphrase Callback +@subsection Passphrase Callback +@cindex callback, passphrase +@cindex passphrase callback + +@deftp {Data type} {gpgme_error_t (*gpgme_passphrase_cb_t)(void *@var{hook}, const char *@var{uid_hint}, const char *@var{passphrase_info}, @w{int @var{prev_was_bad}}, @w{int @var{fd}})} +@tindex gpgme_passphrase_cb_t +The @code{gpgme_passphrase_cb_t} type is the type of functions usable as +passphrase callback function. + +The argument @var{uid_hint} might contain a string that gives an +indication for which user ID the passphrase is required. If this is +not available, or not applicable (in the case of symmetric encryption, +for example), @var{uid_hint} will be @code{NULL}. + +The argument @var{passphrase_info}, if not @code{NULL}, will give +further information about the context in which the passphrase is +required. This information is engine and operation specific. + +If this is the repeated attempt to get the passphrase, because +previous attempts failed, then @var{prev_was_bad} is 1, otherwise it +will be 0. + +The user must write the passphrase, followed by a newline character, +to the file descriptor @var{fd}. If the user returns 0 indicating +success, the user must at least write a newline character before +returning from the callback. + +If an error occurs, return the corresponding @code{gpgme_error_t} +value. You can use the error code @code{GPG_ERR_CANCELED} to abort +the operation. Otherwise, return @code{0}. +@end deftp + +@deftypefun void gpgme_set_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t @var{passfunc}}, @w{void *@var{hook_value}}) +The function @code{gpgme_set_passphrase_cb} sets the function that is +used when a passphrase needs to be provided by the user to +@var{passfunc}. The function @var{passfunc} needs to implemented by +the user, and whenever it is called, it is called with its first +argument being @var{hook_value}. By default, no passphrase callback +function is set. + +Not all crypto engines require this callback to retrieve the +passphrase. It is better if the engine retrieves the passphrase from +a trusted agent (a daemon process), rather than having each user to +implement their own passphrase query. Some engines do not even +support an external passphrase callback at all, in this case the error +code @code{GPG_ERR_NOT_SUPPORTED} is returned. + +The user can disable the use of a passphrase callback function by +calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being +@code{NULL}. +@end deftypefun + +@deftypefun void gpgme_get_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t *@var{passfunc}}, @w{void **@var{hook_value}}) +The function @code{gpgme_get_passphrase_cb} returns the function that +is used when a passphrase needs to be provided by the user in +@var{*passfunc}, and the first argument for this function in +@var{*hook_value}. If no passphrase callback is set, or @var{ctx} is +not a valid pointer, @code{NULL} is returned in both variables. + +@var{passfunc} or @var{hook_value} can be @code{NULL}. In this case, +the corresponding value will not be returned. +@end deftypefun + + +@node Progress Meter Callback +@subsection Progress Meter Callback +@cindex callback, progress meter +@cindex progress meter callback + +@deftp {Data type} {void (*gpgme_progress_cb_t)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})} +@tindex gpgme_progress_cb_t +The @code{gpgme_progress_cb_t} type is the type of functions usable as +progress callback function. + +The arguments are specific to the crypto engine. More information +about the progress information returned from the GnuPG engine can be +found in the GnuPG source code in the file @file{doc/DETAILS} in the +section PROGRESS. +@end deftp + +@deftypefun void gpgme_set_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t @var{progfunc}}, @w{void *@var{hook_value}}) +The function @code{gpgme_set_progress_cb} sets the function that is +used when progress information about a cryptographic operation is +available. The function @var{progfunc} needs to implemented by the +user, and whenever it is called, it is called with its first argument +being @var{hook_value}. By default, no progress callback function +is set. + +Setting a callback function allows an interactive program to display +progress information about a long operation to the user. + +The user can disable the use of a progress callback function by +calling @code{gpgme_set_progress_cb} with @var{progfunc} being +@code{NULL}. +@end deftypefun + +@deftypefun void gpgme_get_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t *@var{progfunc}}, @w{void **@var{hook_value}}) +The function @code{gpgme_get_progress_cb} returns the function that is +used to inform the user about the progress made in @var{*progfunc}, +and the first argument for this function in @var{*hook_value}. If no +progress callback is set, or @var{ctx} is not a valid pointer, +@code{NULL} is returned in both variables. + +@var{progfunc} or @var{hook_value} can be @code{NULL}. In this case, +the corresponding value will not be returned. +@end deftypefun + + +@node Locale +@subsection Locale +@cindex locale, default +@cindex locale, of a context + +A locale setting can be associated with a context. This locale is +passed to the crypto engine, and used for applications like the PIN +entry, which is displayed to the user when entering a passphrase is +required. + +The default locale is used to initialize the locale setting of all +contexts created afterwards. + +@deftypefun gpgme_error_t gpgme_set_locale (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{category}}, @w{const char *@var{value}}) +The function @code{gpgme_set_locale} sets the locale of the context +@var{ctx}, or the default locale if @var{ctx} is a null pointer. + +The locale settings that should be changed are specified by +@var{category}. Supported categories are @code{LC_CTYPE}, +@code{LC_MESSAGES}, and @code{LC_ALL}, which is a wildcard you can use +if you want to change all the categories at once. + +The value to be used for the locale setting is @var{value}, which will +be copied to @acronym{GPGME}'s internal data structures. @var{value} +can be a null pointer, which disables setting the locale, and will +make PIN entry and other applications use their default setting, which +is usually not what you want. + +Note that the settings are only used if the application runs on a text +terminal, and that the settings should fit the configuration of the +output terminal. Normally, it is sufficient to initialize the default +value at startup. + +The function returns an error if not enough memory is available. +@end deftypefun + + +@node Key Management +@section Key Management +@cindex key management + +Some of the cryptographic operations require that recipients or +signers are specified. This is always done by specifying the +respective keys that should be used for the operation. The following +section describes how such keys can be selected and manipulated. + +@deftp {Data type} gpgme_sub_key_t +The @code{gpgme_sub_key_t} type is a pointer to a subkey structure. +Sub keys are one component of a @code{gpgme_key_t} object. In fact, +subkeys are those parts that contains the real information about the +individual cryptographic keys that belong to the same key object. One +@code{gpgme_key_t} can contain several subkeys. The first subkey in +the linked list is also called the primary key. + +The subkey structure has the following members: + +@table @code +@item gpgme_sub_key_t next +This is a pointer to the next subkey structure in the linked list, or +@code{NULL} if this is the last element. + +@item unsigned int revoked : 1 +This is true if the subkey is revoked. + +@item unsigned int expired : 1 +This is true if the subkey is expired. + +@item unsigned int disabled : 1 +This is true if the subkey is disabled. + +@item unsigned int invalid : 1 +This is true if the subkey is invalid. + +@item unsigned int can_encrypt : 1 +This is true if the subkey can be used for encryption. + +@item unsigned int can_sign : 1 +This is true if the subkey can be used to create data signatures. + +@item unsigned int can_certify : 1 +This is true if the subkey can be used to create key certificates. + +@item unsigned int can_authenticate : 1 +This is true if the subkey can be used for authentication. + +@item unsigned int is_qualified : 1 +This is true if the subkey can be used for qualified signatures +according to local government regulations. + +@item unsigned int secret : 1 +This is true if the subkey is a secret key. Note that it will be false +if the key is actually a stub key; i.e. a secret key operation is +currently not possible (offline-key). + +@item gpgme_pubkey_algo_t pubkey_algo +This is the public key algorithm supported by this subkey. + +@item unsigned int length +This is the length of the subkey (in bits). + +@item char *keyid +This is the key ID of the subkey in hexadecimal digits. + +@item char *fpr +This is the fingerprint of the subkey in hexadecimal digits, if +available. + +@item long int timestamp +This is the creation timestamp of the subkey. This is -1 if the +timestamp is invalid, and 0 if it is not available. + +@item long int expires +This is the expiration timestamp of the subkey, or 0 if the subkey +does not expire. +@end table +@end deftp + +@deftp {Data type} gpgme_key_sig_t +The @code{gpgme_key_sig_t} type is a pointer to a key signature structure. +Key signatures are one component of a @code{gpgme_key_t} object, and +validate user IDs on the key. + +The signatures on a key are only available if the key was retrieved +via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode +enabled, because it can be expensive to retrieve all signatures of a +key. + +The signature notations on a key signature are only available if the +key was retrieved via a listing operation with the +@code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} mode enabled, because it can +be expensive to retrieve all signature notations. + +The key signature structure has the following members: + +@table @code +@item gpgme_key_sig_t next +This is a pointer to the next key signature structure in the linked +list, or @code{NULL} if this is the last element. + +@item unsigned int revoked : 1 +This is true if the key signature is a revocation signature. + +@item unsigned int expired : 1 +This is true if the key signature is expired. + +@item unsigned int invalid : 1 +This is true if the key signature is invalid. + +@item unsigned int exportable : 1 +This is true if the key signature is exportable. + +@item gpgme_pubkey_algo_t pubkey_algo +This is the public key algorithm used to create the signature. + +@item char *keyid +This is the key ID of the key (in hexadecimal digits) used to create +the signature. + +@item long int timestamp +This is the creation timestamp of the key signature. This is -1 if +the timestamp is invalid, and 0 if it is not available. + +@item long int expires +This is the expiration timestamp of the key signature, or 0 if the key +signature does not expire. + +@item gpgme_error_t status +This is the status of the signature and has the same meaning as the +member of the same name in a @code{gpgme_signature_t} object. + +@item unsigned int sig_class +This specifies the signature class of the key signature. The meaning +is specific to the crypto engine. + +@item char *uid +This is the main user ID of the key used to create the signature. + +@item char *name +This is the name component of @code{uid}, if available. + +@item char *comment +This is the comment component of @code{uid}, if available. + +@item char *email +This is the email component of @code{uid}, if available. + +@item gpgme_sig_notation_t notations +This is a linked list with the notation data and policy URLs. +@end table +@end deftp + +@deftp {Data type} gpgme_user_id_t +A user ID is a component of a @code{gpgme_key_t} object. One key can +have many user IDs. The first one in the list is the main (or +primary) user ID. + +The user ID structure has the following members. + +@table @code +@item gpgme_user_id_t next +This is a pointer to the next user ID structure in the linked list, or +@code{NULL} if this is the last element. + +@item unsigned int revoked : 1 +This is true if the user ID is revoked. + +@item unsigned int invalid : 1 +This is true if the user ID is invalid. + +@item gpgme_validity_t validity +This specifies the validity of the user ID. + +@item char *uid +This is the user ID string. + +@item char *name +This is the name component of @code{uid}, if available. + +@item char *comment +This is the comment component of @code{uid}, if available. + +@item char *email +This is the email component of @code{uid}, if available. + +@item gpgme_key_sig_t signatures +This is a linked list with the signatures on this user ID. +@end table +@end deftp + +@deftp {Data type} gpgme_key_t +The @code{gpgme_key_t} type is a pointer to a key object. It has the +following members: + +@table @code +@item gpgme_keylist_mode_t keylist_mode +The keylist mode that was active when the key was retrieved. + +@item unsigned int revoked : 1 +This is true if the key is revoked. + +@item unsigned int expired : 1 +This is true if the key is expired. + +@item unsigned int disabled : 1 +This is true if the key is disabled. + +@item unsigned int invalid : 1 +This is true if the key is invalid. This might have several reasons, +for a example for the S/MIME backend, it will be set in during key +listsing if the key could not be validated due to a missing +certificates or unmatched policies. + +@item unsigned int can_encrypt : 1 +This is true if the key (ie one of its subkeys) can be used for +encryption. + +@item unsigned int can_sign : 1 +This is true if the key (ie one of its subkeys) can be used to create +data signatures. + +@item unsigned int can_certify : 1 +This is true if the key (ie one of its subkeys) can be used to create +key certificates. + +@item unsigned int can_authenticate : 1 +This is true if the key (ie one of its subkeys) can be used for +authentication. + +@item unsigned int is_qualified : 1 +This is true if the key can be used for qualified signatures according +to local government regulations. + +@item unsigned int secret : 1 +This is true if the key is a secret key. Note, that this will always be +true even if the corresponding subkey flag may be false (offline/stub +keys). + +@item gpgme_protocol_t protocol +This is the protocol supported by this key. + +@item char *issuer_serial +If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the +issuer serial. + +@item char *issuer_name +If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the +issuer name. + +@item char *chain_id +If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the +chain ID, which can be used to built the certificate chain. + +@item gpgme_validity_t owner_trust +If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the +owner trust. + +@item gpgme_sub_key_t subkeys +This is a linked list with the subkeys of the key. The first subkey +in the list is the primary key and usually available. + +@item gpgme_user_id_t uids +This is a linked list with the user IDs of the key. The first user ID +in the list is the main (or primary) user ID. +@end table +@end deftp + +@menu +* Listing Keys:: Browsing the list of available keys. +* Information About Keys:: Requesting detailed information about keys. +* Key Signatures:: Listing the signatures on a key. +* Manipulating Keys:: Operations on keys. +* Generating Keys:: Creating new key pairs. +* Exporting Keys:: Retrieving key data from the key ring. +* Importing Keys:: Adding keys to the key ring. +* Deleting Keys:: Removing keys from the key ring. +* Changing Passphrases:: Change the passphrase of a key. +* Advanced Key Editing:: Advanced key edit operation. +@end menu + + +@node Listing Keys +@subsection Listing Keys +@cindex listing keys +@cindex key listing +@cindex key listing, start +@cindex key ring, list +@cindex key ring, search + +@deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}}) +The function @code{gpgme_op_keylist_start} initiates a key listing +operation inside the context @var{ctx}. It sets everything up so that +subsequent invocations of @code{gpgme_op_keylist_next} return the keys +in the list. + +If @var{pattern} is @code{NULL}, all available keys are returned. +Otherwise, @var{pattern} contains an engine specific expression that +is used to limit the list to all keys matching the pattern. Note that +the total length of the pattern is restricted to an engine-specific +maximum (a couple of hundred characters are usually accepted). The +pattern should be used to restrict the search to a certain common name +or user, not to list many specific keys at once by listing their +fingerprints or key IDs. + +If @var{secret_only} is not @code{0}, the list is restricted to secret +keys only. + +The context will be busy until either all keys are received (and +@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or +@code{gpgme_op_keylist_end} is called to finish the operation. + +The function returns the error code @code{GPG_ERR_INV_VALUE} if +@var{ctx} is not a valid pointer, and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_keylist_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}}) +The function @code{gpgme_op_keylist_ext_start} initiates an extended +key listing operation inside the context @var{ctx}. It sets +everything up so that subsequent invocations of +@code{gpgme_op_keylist_next} return the keys in the list. + +If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys +are returned. Otherwise, @var{pattern} is a @code{NULL} terminated +array of strings that are used to limit the list to all keys matching +at least one of the patterns verbatim. Note that the total length of +all patterns is restricted to an engine-specific maximum (the exact +limit also depends on the number of patterns and amount of quoting +required, but a couple of hundred characters are usually accepted). +Patterns should be used to restrict the search to a certain common +name or user, not to list many specific keys at once by listing their +fingerprints or key IDs. + +If @var{secret_only} is not @code{0}, the list is restricted to secret +keys only. + +The value of @var{reserved} must be @code{0}. + +The context will be busy until either all keys are received (and +@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or +@code{gpgme_op_keylist_end} is called to finish the operation. + +The function returns the error code @code{GPG_ERR_INV_VALUE} if +@var{ctx} is not a valid pointer, and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}}) +The function @code{gpgme_op_keylist_next} returns the next key in the +list created by a previous @code{gpgme_op_keylist_start} operation in +the context @var{ctx}. The key will have one reference for the user. +@xref{Manipulating Keys}. + +This is the only way to get at @code{gpgme_key_t} objects in +@acronym{GPGME}. + +If the last key in the list has already been returned, +@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}. + +The function returns the error code @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{r_key} is not a valid pointer, and +@code{GPG_ERR_ENOMEM} if there is not enough memory for the operation. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_op_keylist_end} ends a pending key list +operation in the context @var{ctx}. + +After the operation completed successfully, the result of the key +listing operation can be retrieved with +@code{gpgme_op_keylist_result}. + +The function returns the error code @code{GPG_ERR_INV_VALUE} if +@var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some +time during the operation there was not enough memory available. +@end deftypefun + +The following example illustrates how all keys containing a certain +string (@code{g10code}) can be listed with their key ID and the name +and e-mail address of the main user ID: + +@example +gpgme_ctx_t ctx; +gpgme_key_t key; +gpgme_error_t err = gpgme_new (&ctx); + +if (!err) + @{ + err = gpgme_op_keylist_start (ctx, "g10code", 0); + while (!err) + @{ + err = gpgme_op_keylist_next (ctx, &key); + if (err) + break; + printf ("%s:", key->subkeys->keyid); + if (key->uids && key->uids->name) + printf (" %s", key->uids->name); + if (key->uids && key->uids->email) + printf (" <%s>", key->uids->email); + putchar ('\n'); + gpgme_key_release (key); + @} + gpgme_release (ctx); + @} +if (gpg_err_code (err) != GPG_ERR_EOF) + @{ + fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err)); + exit (1); + @} +@end example + +@deftp {Data type} {gpgme_keylist_result_t} +This is a pointer to a structure used to store the result of a +@code{gpgme_op_keylist_*} operation. After successfully ending a key +listing operation, you can retrieve the pointer to the result with +@code{gpgme_op_keylist_result}. The structure contains the following +member: + +@table @code +@item unsigned int truncated : 1 +This is true if the crypto backend had to truncate the result, and +less than the desired keys could be listed. +@end table +@end deftp + +@deftypefun gpgme_keylist_result_t gpgme_op_keylist_result (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_op_keylist_result} returns a +@code{gpgme_keylist_result_t} pointer to a structure holding the +result of a @code{gpgme_op_keylist_*} operation. The pointer is only +valid if the last operation on the context was a key listing +operation, and if this operation finished successfully. The returned +pointer is only valid until the next operation is started on the +context. +@end deftypefun + +In a simple program, for which a blocking operation is acceptable, the +following function can be used to retrieve a single key. + +@deftypefun gpgme_error_t gpgme_get_key (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{fpr}}, @w{gpgme_key_t *@var{r_key}}, @w{int @var{secret}}) +The function @code{gpgme_get_key} gets the key with the fingerprint +(or key ID) @var{fpr} from the crypto backend and return it in +@var{r_key}. If @var{secret} is true, get the secret key. The +currently active keylist mode is used to retrieve the key. The key +will have one reference for the user. + +If the key is not found in the keyring, @code{gpgme_get_key} returns +the error code @code{GPG_ERR_EOF} and *@var{r_key} will be set to +@code{NULL}. + +The function returns the error code @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{r_key} is not a valid pointer or @var{fpr} is not a +fingerprint or key ID, @code{GPG_ERR_AMBIGUOUS_NAME} if the key ID was +not a unique specifier for a key, and @code{GPG_ERR_ENOMEM} if at some +time during the operation there was not enough memory available. +@end deftypefun + + +@node Information About Keys +@subsection Information About Keys +@cindex key, information about +@cindex key, attributes +@cindex attributes, of a key + +Please see the beginning of this section for more information about +@code{gpgme_key_t} objects. + +@deftp {Data type} gpgme_validity_t +The @code{gpgme_validity_t} type is used to specify the validity of a user ID +in a key. The following validities are defined: + +@table @code +@item GPGME_VALIDITY_UNKNOWN +The user ID is of unknown validity. The string representation of this +validity is ``?''. + +@item GPGME_VALIDITY_UNDEFINED +The validity of the user ID is undefined. The string representation of this +validity is ``q''. + +@item GPGME_VALIDITY_NEVER +The user ID is never valid. The string representation of this +validity is ``n''. + +@item GPGME_VALIDITY_MARGINAL +The user ID is marginally valid. The string representation of this +validity is ``m''. + +@item GPGME_VALIDITY_FULL +The user ID is fully valid. The string representation of this +validity is ``f''. + +@item GPGME_VALIDITY_ULTIMATE +The user ID is ultimately valid. The string representation of this +validity is ``u''. +@end table +@end deftp + + +The following interfaces are deprecated and only provided for backward +compatibility. Don't use them. They will be removed in a future +version of @acronym{GPGME}. + +@deftp {Data type} gpgme_attr_t +The @code{gpgme_attr_t} type is used to specify a key or trust item +attribute. The following attributes are defined: + +@table @code +@item GPGME_ATTR_KEYID +This is the key ID of a sub key. It is representable as a string. + +For trust items, the trust item refers to the key with this ID. + +@item GPGME_ATTR_FPR +This is the fingerprint of a sub key. It is representable as a +string. + +@item GPGME_ATTR_ALGO +This is the crypto algorithm for which the sub key can be used. It +is representable as a string and as a number. The numbers correspond +to the @code{enum gcry_pk_algos} values in the gcrypt library. + +@item GPGME_ATTR_LEN +This is the key length of a sub key. It is representable as a +number. + +@item GPGME_ATTR_CREATED +This is the timestamp at creation time of a sub key. It is +representable as a number. + +@item GPGME_ATTR_EXPIRE +This is the expiration time of a sub key. It is representable as a +number. + +@item GPGME_ATTR_OTRUST +XXX FIXME (also for trust items) + +@item GPGME_ATTR_USERID +This is a user ID. There can be more than one user IDs in a +@var{gpgme_key_t} object. The first one (with index 0) is the primary +user ID. The user ID is representable as a number. + +For trust items, this is the user ID associated with this trust item. + +@item GPGME_ATTR_NAME +This is the name belonging to a user ID. It is representable as a string. + +@item GPGME_ATTR_EMAIL +This is the email address belonging to a user ID. It is representable +as a string. + +@item GPGME_ATTR_COMMENT +This is the comment belonging to a user ID. It is representable as a +string. + +@item GPGME_ATTR_VALIDITY +This is the validity belonging to a user ID. It is representable as a +string and as a number. See below for a list of available validities. + +For trust items, this is the validity that is associated with this +trust item. + +@item GPGME_ATTR_UID_REVOKED +This specifies if a user ID is revoked. It is representable as a +number, and is @code{1} if the user ID is revoked, and @code{0} +otherwise. + +@item GPGME_ATTR_UID_INVALID +This specifies if a user ID is invalid. It is representable as a +number, and is @code{1} if the user ID is invalid, and @code{0} +otherwise. + +@item GPGME_ATTR_LEVEL +This is the trust level of a trust item. + +@item GPGME_ATTR_TYPE +This returns information about the type of key. For the string function +this will eother be "PGP" or "X.509". The integer function returns 0 +for PGP and 1 for X.509. It is also used for the type of a trust item. + +@item GPGME_ATTR_IS_SECRET +This specifies if the key is a secret key. It is representable as a +number, and is @code{1} if the key is revoked, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_REVOKED +This specifies if a sub key is revoked. It is representable as a +number, and is @code{1} if the key is revoked, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_INVALID +This specifies if a sub key is invalid. It is representable as a +number, and is @code{1} if the key is invalid, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_EXPIRED +This specifies if a sub key is expired. It is representable as a +number, and is @code{1} if the key is expired, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_DISABLED +This specifies if a sub key is disabled. It is representable as a +number, and is @code{1} if the key is disabled, and @code{0} otherwise. + +@item GPGME_ATTR_KEY_CAPS +This is a description of the capabilities of a sub key. It is +representable as a string. The string contains the letter ``e'' if +the key can be used for encryption, ``s'' if the key can be used for +signatures, and ``c'' if the key can be used for certifications. + +@item GPGME_ATTR_CAN_ENCRYPT +This specifies if a sub key can be used for encryption. It is +representable as a number, and is @code{1} if the sub key can be used +for encryption, and @code{0} otherwise. + +@item GPGME_ATTR_CAN_SIGN +This specifies if a sub key can be used to create data signatures. It +is representable as a number, and is @code{1} if the sub key can be +used for signatures, and @code{0} otherwise. + +@item GPGME_ATTR_CAN_CERTIFY +This specifies if a sub key can be used to create key certificates. +It is representable as a number, and is @code{1} if the sub key can be +used for certifications, and @code{0} otherwise. + +@item GPGME_ATTR_SERIAL +The X.509 issuer serial attribute of the key. It is representable as +a string. + +@item GPGME_ATTR_ISSUE +The X.509 issuer name attribute of the key. It is representable as a +string. + +@item GPGME_ATTR_CHAINID +The X.509 chain ID can be used to build the certification chain. It +is representable as a string. +@end table +@end deftp + +@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_get_string_attr} returns the value of the +string-representable attribute @var{what} of key @var{key}. If the +attribute is an attribute of a sub key or an user ID, @var{idx} +specifies the sub key or user ID of which the attribute value is +returned. The argument @var{reserved} is reserved for later use and +should be @code{NULL}. + +The string returned is only valid as long as the key is valid. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + +@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_get_ulong_attr} returns the value of the +number-representable attribute @var{what} of key @var{key}. If the +attribute is an attribute of a sub key or an user ID, @var{idx} +specifies the sub key or user ID of which the attribute value is +returned. The argument @var{reserved} is reserved for later use and +should be @code{NULL}. + +The function returns @code{0} if the attribute can't be returned as a +number, @var{key} is not a valid pointer, @var{idx} out of range, or +@var{reserved} not @code{NULL}. +@end deftypefun + + +@node Key Signatures +@subsection Key Signatures +@cindex key, signatures +@cindex signatures, on a key + +The following interfaces are deprecated and only provided for backward +compatibility. Don't use them. They will be removed in a future +version of @acronym{GPGME}. + +The signatures on a key are only available if the key was retrieved +via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode +enabled, because it is expensive to retrieve all signatures of a key. + +So, before using the below interfaces to retrieve the signatures on a +key, you have to make sure that the key was listed with signatures +enabled. One convenient, but blocking, way to do this is to use the +function @code{gpgme_get_key}. + +@deftp {Data type} gpgme_attr_t +The @code{gpgme_attr_t} type is used to specify a key signature +attribute. The following attributes are defined: + +@table @code +@item GPGME_ATTR_KEYID +This is the key ID of the key which was used for the signature. It is +representable as a string. + +@item GPGME_ATTR_ALGO +This is the crypto algorithm used to create the signature. It is +representable as a string and as a number. The numbers correspond to +the @code{enum gcry_pk_algos} values in the gcrypt library. + +@item GPGME_ATTR_CREATED +This is the timestamp at creation time of the signature. It is +representable as a number. + +@item GPGME_ATTR_EXPIRE +This is the expiration time of the signature. It is representable as +a number. + +@item GPGME_ATTR_USERID +This is the user ID associated with the signing key. The user ID is +representable as a number. + +@item GPGME_ATTR_NAME +This is the name belonging to a user ID. It is representable as a string. + +@item GPGME_ATTR_EMAIL +This is the email address belonging to a user ID. It is representable +as a string. + +@item GPGME_ATTR_COMMENT +This is the comment belonging to a user ID. It is representable as a +string. + +@item GPGME_ATTR_KEY_REVOKED +This specifies if a key signature is a revocation signature. It is +representable as a number, and is @code{1} if the key is revoked, and +@code{0} otherwise. + +@c @item GPGME_ATTR_KEY_EXPIRED +@c This specifies if a key signature is expired. It is representable as +@c a number, and is @code{1} if the key is revoked, and @code{0} +@c otherwise. +@c +@item GPGME_ATTR_SIG_CLASS +This specifies the signature class of a key signature. It is +representable as a number. The meaning is specific to the crypto +engine. + +@item GPGME_ATTR_SIG_CLASS +This specifies the signature class of a key signature. It is +representable as a number. The meaning is specific to the crypto +engine. + +@item GPGME_ATTR_SIG_STATUS +This is the same value as returned by @code{gpgme_get_sig_status}. +@end table +@end deftp + +@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_sig_get_string_attr} returns the value of +the string-representable attribute @var{what} of the signature +@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The +argument @var{reserved} is reserved for later use and should be +@code{NULL}. + +The string returned is only valid as long as the key is valid. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx} +out of range, or @var{reserved} not @code{NULL}. +@end deftypefun + +@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_key_sig_get_ulong_attr} returns the value of +the number-representable attribute @var{what} of the signature +@var{idx} on the user ID @var{uid_idx} in the key @var{key}. The +argument @var{reserved} is reserved for later use and should be +@code{NULL}. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx} +out of range, or @var{reserved} not @code{NULL}. +@end deftypefun + + +@node Manipulating Keys +@subsection Manipulating Keys +@cindex key, manipulation + +@deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}}) +The function @code{gpgme_key_ref} acquires an additional reference for +the key @var{key}. +@end deftypefun + +@deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}}) +The function @code{gpgme_key_unref} releases a reference for the key +@var{key}. If this was the last reference, the key will be destroyed +and all resources associated to it will be released. +@end deftypefun + + +The following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of @acronym{GPGME}. + +@deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}}) +The function @code{gpgme_key_release} is equivalent to +@code{gpgme_key_unref}. +@end deftypefun + + +@node Generating Keys +@subsection Generating Keys +@cindex key, creation +@cindex key ring, add + +@deftypefun gpgme_error_t gpgme_op_genkey (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}}) +The function @code{gpgme_op_genkey} generates a new key pair in the +context @var{ctx}. The meaning of @var{public} and @var{secret} +depends on the crypto backend. + +GnuPG does not support @var{public} and @var{secret}, they should be +@code{NULL}. GnuPG will generate a key pair and add it to the +standard key ring. The fingerprint of the generated key is available +with @code{gpgme_op_genkey_result}. + +GpgSM requires @var{public} to be a writable data object. GpgSM will +generate a secret key (which will be stored by @command{gpg-agent}, +and return a certificate request in @var{public}, which then needs to +be signed by the certification authority and imported before it can be +used. GpgSM does not make the fingerprint available. + +The argument @var{parms} specifies parameters for the key in an XML +string. The details about the format of @var{parms} are specific to +the crypto engine used by @var{ctx}. Here is an example for GnuPG as +the crypto engine (all parameters of OpenPGP key generation are +documented in the GPG manual): + +@example +<GnupgKeyParms format="internal"> +Key-Type: default +Subkey-Type: default +Name-Real: Joe Tester +Name-Comment: with stupid passphrase +Name-Email: joe@@foo.bar +Expire-Date: 0 +Passphrase: abc +</GnupgKeyParms> +@end example + +Here is an example for GpgSM as the crypto engine (all parameters of +OpenPGP key generation are documented in the GPGSM manual): + +@example +<GnupgKeyParms format="internal"> +Key-Type: RSA +Key-Length: 1024 +Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester +Name-Email: joe@@foo.bar +</GnupgKeyParms> +@end example + +Strings should be given in UTF-8 encoding. The only format supported +for now is ``internal''. The content of the @code{GnupgKeyParms} +container is passed verbatim to the crypto backend. Control +statements are not allowed. + +After the operation completed successfully, the result can be +retrieved with @code{gpgme_op_genkey_result}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, @code{GPG_ERR_INV_VALUE} if +@var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if +@var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL} +if no key was created by the backend. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}}) +The function @code{gpgme_op_genkey_start} initiates a +@code{gpgme_op_genkey} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, @code{GPG_ERR_INV_VALUE} if +@var{parms} is not a valid XML string, and +@code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not +@code{NULL}. +@end deftypefun + +@deftp {Data type} {gpgme_genkey_result_t} +This is a pointer to a structure used to store the result of a +@code{gpgme_op_genkey} operation. After successfully generating a +key, you can retrieve the pointer to the result with +@code{gpgme_op_genkey_result}. The structure contains the following +members: + +@table @code +@item unsigned int primary : 1 +This is a flag that is set to 1 if a primary key was created and to 0 +if not. + +@item unsigned int sub : 1 +This is a flag that is set to 1 if a subkey was created and to 0 +if not. + +@item char *fpr +This is the fingerprint of the key that was created. If both a +primary and a sub key were generated, the fingerprint of the primary +key will be returned. If the crypto engine does not provide the +fingerprint, @code{fpr} will be a null pointer. +@end table +@end deftp + +@deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_op_genkey_result} returns a +@code{gpgme_genkey_result_t} pointer to a structure holding the result of +a @code{gpgme_op_genkey} operation. The pointer is only valid if the +last operation on the context was a @code{gpgme_op_genkey} or +@code{gpgme_op_genkey_start} operation, and if this operation finished +successfully. The returned pointer is only valid until the next +operation is started on the context. +@end deftypefun + + +@node Exporting Keys +@subsection Exporting Keys +@cindex key, export +@cindex key ring, export from + +Exporting keys means the same as running @command{gpg} with the command +@option{--export}. However, a mode flag can be used to change the way +the export works. The available mode flags are described below, they +may be or-ed together. + +@table @code + +@item GPGME_EXPORT_MODE_EXTERN +If this bit is set, the output is send directly to the default +keyserver. This is currently only allowed for OpenPGP keys. It is good +practise to not send more than a few dozens key to a keyserver at one +time. Using this flag requires that the @var{keydata} argument of the +export function is set to @code{NULL}. + +@item GPGME_EXPORT_MODE_MINIMAL +If this bit is set, the smallest possible key is exported. For OpenPGP +keys it removes all signatures except for the latest self-signatures. +For X.509 keys it has no effect. + + +@end table + + + +@deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}}) +The function @code{gpgme_op_export} extracts public keys and returns +them in the data buffer @var{keydata}. The output format of the key +data returned is determined by the @acronym{ASCII} armor attribute set +for the context @var{ctx}, or, if that is not set, by the encoding +specified for @var{keydata}. + +If @var{pattern} is @code{NULL}, all available keys are returned. +Otherwise, @var{pattern} contains an engine specific expression that +is used to limit the list to all keys matching the pattern. + +@var{mode} is usually 0; other values are described above. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation completed successfully, @code{GPG_ERR_INV_VALUE} if +@var{keydata} is not a valid empty data buffer, and passes through any +errors that are reported by the crypto engine support routines. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}}) +The function @code{gpgme_op_export_start} initiates a +@code{gpgme_op_export} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, and @code{GPG_ERR_INV_VALUE} +if @var{keydata} is not a valid empty data buffer. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_export_ext (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}}) +The function @code{gpgme_op_export} extracts public keys and returns +them in the data buffer @var{keydata}. The output format of the key +data returned is determined by the @acronym{ASCII} armor attribute set +for the context @var{ctx}, or, if that is not set, by the encoding +specified for @var{keydata}. + +If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys +are returned. Otherwise, @var{pattern} is a @code{NULL} terminated +array of strings that are used to limit the list to all keys matching +at least one of the patterns verbatim. + +@var{mode} is usually 0; other values are described above. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation completed successfully, @code{GPG_ERR_INV_VALUE} if +@var{keydata} is not a valid empty data buffer, and passes through any +errors that are reported by the crypto engine support routines. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_export_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}}) +The function @code{gpgme_op_export_ext_start} initiates a +@code{gpgme_op_export_ext} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, and @code{GPG_ERR_INV_VALUE} +if @var{keydata} is not a valid empty data buffer. +@end deftypefun + + +@deftypefun gpgme_error_t gpgme_op_export_keys (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t keys[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}}) +The function @code{gpgme_op_export_keys} extracts public keys and returns +them in the data buffer @var{keydata}. The output format of the key +data returned is determined by the @acronym{ASCII} armor attribute set +for the context @var{ctx}, or, if that is not set, by the encoding +specified for @var{keydata}. + +The keys to export are taken form the @code{NULL} terminated array +@var{keys}. Only keys of the the currently selected protocol of +@var{ctx} which do have a fingerprint set are considered for export. +Other keys specified by the @var{keys} are ignored. In particular +OpenPGP keys retrieved via an external key listing are not included. + +@var{mode} is usually 0; other values are described above. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation completed successfully, @code{GPG_ERR_INV_VALUE} if +@var{keydata} is not a valid empty data buffer, @code{GPG_ERR_NO_DATA} +if no useful keys are in @var{keys} and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_export_keys_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{keys}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}}) +The function @code{gpgme_op_export_keys_start} initiates a +@code{gpgme_op_export_ext} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, and @code{GPG_ERR_INV_VALUE} +if @var{keydata} is not a valid empty data buffer, @code{GPG_ERR_NO_DATA} +if no useful keys are in @var{keys} and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + + +@node Importing Keys +@subsection Importing Keys +@cindex key, import +@cindex key ring, import to + +Importing keys means the same as running @command{gpg} with the command +@option{--import}. + + +@deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}) +The function @code{gpgme_op_import} adds the keys in the data buffer +@var{keydata} to the key ring of the crypto engine used by @var{ctx}. +The format of @var{keydata} can be @acronym{ASCII} armored, for example, +but the details are specific to the crypto engine. + +After the operation completed successfully, the result can be +retrieved with @code{gpgme_op_import_result}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +import was completed successfully, @code{GPG_ERR_INV_VALUE} if +@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer, +and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_import_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}) +The function @code{gpgme_op_import_start} initiates a +@code{gpgme_op_import} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +import could be started successfully, @code{GPG_ERR_INV_VALUE} if +@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer, +and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_import_keys (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}}) +The function @code{gpgme_op_import_keys} adds the keys described by the +@code{NULL} terminated array @var{keys} to the key ring of the crypto +engine used by @var{ctx}. This function is the general interface to +move a key from one crypto engine to another as long as they are +compatible. In particular it is used to actually import and make keys +permanent which have been retrieved from an external source (i.e. using +@code{GPGME_KEYLIST_MODE_EXTERN}). @footnote{Thus it is a replacement +for the usual workaround of exporting and then importing a key to make +an X.509 key permanent.} + +Only keys of the the currently selected protocol of @var{ctx} are +considered for import. Other keys specified by the @var{keys} are +ignored. As of now all considered keys must have been retrieved using +the same method, that is the used key listing mode must be identical. + +After the operation completed successfully, the result can be +retrieved with @code{gpgme_op_import_result}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +import was completed successfully, @code{GPG_ERR_INV_VALUE} if +@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer, +@code{GPG_ERR_CONFLICT} if the key listing mode does not match, and +@code{GPG_ERR_NO_DATA} if no keys are considered for export. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_import_keys_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}}) +The function @code{gpgme_op_import_keys_start} initiates a +@code{gpgme_op_import_keys} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +import was completed successfully, @code{GPG_ERR_INV_VALUE} if +@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer, +@code{GPG_ERR_CONFLICT} if the key listing mode does not match, and +@code{GPG_ERR_NO_DATA} if no keys are considered for export. +@end deftypefun + +@deftp {Data type} {gpgme_import_status_t} +This is a pointer to a structure used to store a part of the result of +a @code{gpgme_op_import} operation. For each considered key one +status is added that contains information about the result of the +import. The structure contains the following members: + +@table @code +@item gpgme_import_status_t next +This is a pointer to the next status structure in the linked list, or +@code{NULL} if this is the last element. + +@item char *fpr +This is the fingerprint of the key that was considered. + +@item gpgme_error_t result +If the import was not successful, this is the error value that caused +the import to fail. Otherwise the error code is +@code{GPG_ERR_NO_ERROR}. + +@item unsigned int status +This is a bit-wise OR of the following flags that give more +information about what part of the key was imported. If the key was +already known, this might be 0. + +@table @code +@item GPGME_IMPORT_NEW +The key was new. + +@item GPGME_IMPORT_UID +The key contained new user IDs. + +@item GPGME_IMPORT_SIG +The key contained new signatures. + +@item GPGME_IMPORT_SUBKEY +The key contained new sub keys. + +@item GPGME_IMPORT_SECRET +The key contained a secret key. +@end table +@end table +@end deftp + +@deftp {Data type} {gpgme_import_result_t} +This is a pointer to a structure used to store the result of a +@code{gpgme_op_import} operation. After a successful import +operation, you can retrieve the pointer to the result with +@code{gpgme_op_import_result}. The structure contains the following +members: + +@table @code +@item int considered +The total number of considered keys. + +@item int no_user_id +The number of keys without user ID. + +@item int imported +The total number of imported keys. + +@item imported_rsa +The number of imported RSA keys. + +@item unchanged +The number of unchanged keys. + +@item new_user_ids +The number of new user IDs. + +@item new_sub_keys +The number of new sub keys. + +@item new_signatures +The number of new signatures. + +@item new_revocations +The number of new revocations. + +@item secret_read +The total number of secret keys read. + +@item secret_imported +The number of imported secret keys. + +@item secret_unchanged +The number of unchanged secret keys. + +@item not_imported +The number of keys not imported. + +@item gpgme_import_status_t imports +A list of gpgme_import_status_t objects which contain more information +about the keys for which an import was attempted. +@end table +@end deftp + +@deftypefun gpgme_import_result_t gpgme_op_import_result (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_op_import_result} returns a +@code{gpgme_import_result_t} pointer to a structure holding the result +of a @code{gpgme_op_import} operation. The pointer is only valid if +the last operation on the context was a @code{gpgme_op_import} or +@code{gpgme_op_import_start} operation, and if this operation finished +successfully. The returned pointer is only valid until the next +operation is started on the context. +@end deftypefun + +The following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of @acronym{GPGME}. + +@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}}) +The function @code{gpgme_op_import_ext} is equivalent to: + +@example + gpgme_error_t err = gpgme_op_import (ctx, keydata); + if (!err) + @{ + gpgme_import_result_t result = gpgme_op_import_result (ctx); + *nr = result->considered; + @} +@end example +@end deftypefun + + +@node Deleting Keys +@subsection Deleting Keys +@cindex key, delete +@cindex key ring, delete from + +@deftypefun gpgme_error_t gpgme_op_delete (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}, @w{int @var{allow_secret}}) +The function @code{gpgme_op_delete} deletes the key @var{key} from the +key ring of the crypto engine used by @var{ctx}. If +@var{allow_secret} is @code{0}, only public keys are deleted, +otherwise secret keys are deleted as well, if that is supported. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the key +was deleted successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} or +@var{key} is not a valid pointer, @code{GPG_ERR_NO_PUBKEY} if +@var{key} could not be found in the keyring, +@code{GPG_ERR_AMBIGUOUS_NAME} if the key was not specified +unambiguously, and @code{GPG_ERR_CONFLICT} if the secret key for +@var{key} is available, but @var{allow_secret} is zero. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_delete_start (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}, @w{int @var{allow_secret}}) +The function @code{gpgme_op_delete_start} initiates a +@code{gpgme_op_delete} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation was started successfully, and @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{key} is not a valid pointer. +@end deftypefun + + +@node Changing Passphrases +@subsection Changing Passphrases +@cindex passphrase, change + +@deftypefun gpgme_error_t gpgme_op_passwd @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{const gpgme_key_t @var{key}}, @ + @w{unsigned int @var{flags}}) + +The function @code{gpgme_op_passwd} changes the passphrase of the +private key associated with @var{key}. The only allowed value for +@var{flags} is @code{0}. The backend engine will usually popup a window +to ask for the old and the new passphrase. Thus this function is not +useful in a server application (where passphrases are not required +anyway). + +Note that old @code{gpg} engines (before version 2.0.15) do not support +this command and will silently ignore it. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_passwd_start @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{const gpgme_key_t @var{key}}, @ + @w{unsigned int @var{flags}}) + +The function @code{gpgme_op_passwd_start} initiates a +@code{gpgme_op_passwd} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns @code{0} if the operation was started successfully, +and an error code if one of the arguments is not valid or the oepration +could not be started. +@end deftypefun + + +@node Advanced Key Editing +@subsection Advanced Key Editing +@cindex key, edit + +@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) (@w{void *@var{handle}}, @w{gpgme_status_code_t @var{status}}, @w{const char *@var{args}}, @w{int @var{fd}})} +@tindex gpgme_edit_cb_t +The @code{gpgme_edit_cb_t} type is the type of functions which +@acronym{GPGME} calls if it a key edit operation is on-going. The +status code @var{status} and the argument line @var{args} are passed +through by @acronym{GPGME} from the crypto engine. The file +descriptor @var{fd} is -1 for normal status messages. If @var{status} +indicates a command rather than a status message, the response to the +command should be written to @var{fd}. The @var{handle} is provided +by the user at start of operation. + +The function should return @code{GPG_ERR_NO_ERROR} or an error value. +@end deftp + +@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +The function @code{gpgme_op_edit} processes the key @var{KEY} +interactively, using the edit callback function @var{FNC} with the +handle @var{HANDLE}. The callback is invoked for every status and +command request from the crypto engine. The output of the crypto +engine is written to the data object @var{out}. + +Note that the protocol between the callback function and the crypto +engine is specific to the crypto engine and no further support in +implementing this protocol correctly is provided by @acronym{GPGME}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{key} is not a valid pointer, and any error returned +by the crypto engine or the edit callback handler. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +The function @code{gpgme_op_edit_start} initiates a +@code{gpgme_op_edit} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation was started successfully, and @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{key} is not a valid pointer. +@end deftypefun + + +@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +The function @code{gpgme_op_card_edit} is analogous to +@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}}) +The function @code{gpgme_op_card_edit_start} initiates a +@code{gpgme_op_card_edit} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation was started successfully, and @code{GPG_ERR_INV_VALUE} if +@var{ctx} or @var{key} is not a valid pointer. +@end deftypefun + + +@node Trust Item Management +@section Trust Item Management +@cindex trust item + +@strong{Caution:} The trust items interface is experimental. + +@deftp {Data type} gpgme_trust_item_t +The @code{gpgme_trust_item_t} type is a pointer to a trust item object. +It has the following members: + +@table @code +@item char *keyid +This is a string describing the key to which this trust items belongs. + +@item int type +This is the type of the trust item. A value of 1 refers to a key, a +value of 2 refers to a user ID. + +@item int level +This is the trust level. + +@item char *owner_trust +The owner trust if @code{type} is 1. + +@item char *validity +The calculated validity. + +@item char *name +The user name if @code{type} is 2. +@end table +@end deftp + +@menu +* Listing Trust Items:: Browsing the list of available trust items. +* Information About Trust Items:: Requesting information about trust items. +* Manipulating Trust Items:: Operations on trust items. +@end menu + + +@node Listing Trust Items +@subsection Listing Trust Items +@cindex trust item list + +@deftypefun gpgme_error_t gpgme_op_trustlist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}}) +The function @code{gpgme_op_trustlist_start} initiates a trust item +listing operation inside the context @var{ctx}. It sets everything up +so that subsequent invocations of @code{gpgme_op_trustlist_next} return +the trust items in the list. + +The string @var{pattern} contains an engine specific expression that +is used to limit the list to all trust items matching the pattern. It +can not be the empty string. + +The argument @var{max_level} is currently ignored. + +The context will be busy until either all trust items are received +(and @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}), or +@code{gpgme_op_trustlist_end} is called to finish the operation. + +The function returns the error code @code{GPG_ERR_INV_VALUE} if +@var{ctx} is not a valid pointer, and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_trustlist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_trust_item_t *@var{r_item}}) +The function @code{gpgme_op_trustlist_next} returns the next trust +item in the list created by a previous @code{gpgme_op_trustlist_start} +operation in the context @var{ctx}. The trust item can be destroyed +with @code{gpgme_trust_item_release}. @xref{Manipulating Trust Items}. + +This is the only way to get at @code{gpgme_trust_item_t} objects in +@acronym{GPGME}. + +If the last trust item in the list has already been returned, +@code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}. + +The function returns the error code @code{GPG_ERR_INV_VALUE} if @var{ctx} or +@var{r_item} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if +there is not enough memory for the operation. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_op_trustlist_end} ends a pending trust list +operation in the context @var{ctx}. + +The function returns the error code @code{GPG_ERR_INV_VALUE} if +@var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some +time during the operation there was not enough memory available. +@end deftypefun + + +@node Information About Trust Items +@subsection Information About Trust Items +@cindex trust item, information about +@cindex trust item, attributes +@cindex attributes, of a trust item + +The following interfaces are deprecated and only provided for backward +compatibility. Don't use them. They will be removed in a future +version of @acronym{GPGME}. + +Trust items have attributes which can be queried using the interfaces +below. The attribute identifiers are shared with those for key +attributes. @xref{Information About Keys}. + +@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_trust_item_get_string_attr} returns the value +of the string-representable attribute @var{what} of trust item +@var{item}. The arguments @var{idx} and @var{reserved} are reserved +for later use and should be @code{0} and @code{NULL} respectively. + +The string returned is only valid as long as the key is valid. + +The function returns @code{0} if an attribute can't be returned as a +string, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + +@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) +The function @code{gpgme_trust_item_get_int_attr} returns the value of +the number-representable attribute @var{what} of trust item +@var{item}. If the attribute occurs more than once in the trust item, +the index is specified by @var{idx}. However, currently no such +attribute exists, so @var{idx} should be @code{0}. The argument +@var{reserved} is reserved for later use and should be @code{NULL}. + +The function returns @code{0} if the attribute can't be returned as a +number, @var{key} is not a valid pointer, @var{idx} out of range, +or @var{reserved} not @code{NULL}. +@end deftypefun + + +@node Manipulating Trust Items +@subsection Manipulating Trust Items +@cindex trust item, manipulation + +@deftypefun void gpgme_trust_item_ref (@w{gpgme_trust_item_t @var{item}}) +The function @code{gpgme_trust_item_ref} acquires an additional +reference for the trust item @var{item}. +@end deftypefun + +@deftypefun void gpgme_trust_item_unref (@w{gpgme_trust_item_t @var{item}}) +The function @code{gpgme_trust_item_unref} releases a reference for +the trust item @var{item}. If this was the last reference, the trust +item will be destroyed and all resources associated to it will be +released. +@end deftypefun + + +The following interface is deprecated and only provided for backward +compatibility. Don't use it. It will be removed in a future version +of @acronym{GPGME}. + +@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}}) +The function @code{gpgme_trust_item_release} is an alias for +@code{gpgme_trust_item_unref}. +@end deftypefun + + +@node Crypto Operations +@section Crypto Operations +@cindex cryptographic operation + +Sometimes, the result of a crypto operation returns a list of invalid +keys encountered in processing the request. The following structure +is used to hold information about such a key. + +@deftp {Data type} {gpgme_invalid_key_t} +This is a pointer to a structure used to store a part of the result of +a crypto operation which takes user IDs as one input parameter. The +structure contains the following members: + +@table @code +@item gpgme_invalid_key_t next +This is a pointer to the next invalid key structure in the linked +list, or @code{NULL} if this is the last element. + +@item char *fpr +The fingerprint or key ID of the invalid key encountered. + +@item gpgme_error_t reason +An error code describing the reason why the key was found invalid. +@end table +@end deftp + + +@menu +* Decrypt:: Decrypting a ciphertext. +* Verify:: Verifying a signature. +* Decrypt and Verify:: Decrypting a signed ciphertext. +* Sign:: Creating a signature. +* Encrypt:: Encrypting a plaintext. +@end menu + + +@node Decrypt +@subsection Decrypt +@cindex decryption +@cindex cryptographic operation, decryption + +@deftypefun gpgme_error_t gpgme_op_decrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}}) +The function @code{gpgme_op_decrypt} decrypts the ciphertext in the +data object @var{cipher} and stores it into the data object +@var{plain}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE} +if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer, +@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to +decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid +cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the +secret key could not be retrieved, and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_decrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}}) +The function @code{gpgme_op_decrypt_start} initiates a +@code{gpgme_op_decrypt} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, and @code{GPG_ERR_INV_VALUE} +if @var{cipher} or @var{plain} is not a valid pointer. +@end deftypefun + +@deftp {Data type} {gpgme_recipient_t} +This is a pointer to a structure used to store information about the +recipient of an encrypted text which is decrypted in a +@code{gpgme_op_decrypt} operation. This information (except for the +status field) is even available before the operation finished +successfully, for example in a passphrase callback. The structure +contains the following members: + +@table @code +@item gpgme_recipient_t next +This is a pointer to the next recipient structure in the linked list, +or @code{NULL} if this is the last element. + +@item gpgme_pubkey_algo_t +The public key algorithm used in the encryption. + +@item unsigned int wrong_key_usage : 1 +This is true if the key was not used according to its policy. + +@item char *keyid +This is the key ID of the key (in hexadecimal digits) used as +recipient. + +@item gpgme_error_t status +This is an error number with the error code GPG_ERR_NO_SECKEY if the +secret key for this recipient is not available, and 0 otherwise. +@end table +@end deftp + +@deftp {Data type} {gpgme_decrypt_result_t} +This is a pointer to a structure used to store the result of a +@code{gpgme_op_decrypt} operation. After successfully decrypting +data, you can retrieve the pointer to the result with +@code{gpgme_op_decrypt_result}. The structure contains the following +members: + +@table @code +@item char *unsupported_algorithm +If an unsupported algorithm was encountered, this string describes the +algorithm that is not supported. + +@item unsigned int wrong_key_usage : 1 +This is true if the key was not used according to its policy. + +@item gpgme_recipient_t recipients +This is a linked list of recipients to which this message was encrypted. + +@item char *file_name +This is the filename of the original plaintext message file if it is +known, otherwise this is a null pointer. +@end table +@end deftp + +@deftypefun gpgme_decrypt_result_t gpgme_op_decrypt_result (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_op_decrypt_result} returns a +@code{gpgme_decrypt_result_t} pointer to a structure holding the +result of a @code{gpgme_op_decrypt} operation. The pointer is only +valid if the last operation on the context was a +@code{gpgme_op_decrypt} or @code{gpgme_op_decrypt_start} operation. +If the operation failed this might be a @code{NULL} pointer. The +returned pointer is only valid until the next operation is started on +the context. +@end deftypefun + + +@node Verify +@subsection Verify +@cindex verification +@cindex signature, verification +@cindex cryptographic operation, verification +@cindex cryptographic operation, signature check +@cindex signature notation data +@cindex notation data + +@deftypefun gpgme_error_t gpgme_op_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}}) +The function @code{gpgme_op_verify} verifies that the signature in the +data object @var{sig} is a valid signature. If @var{sig} is a +detached signature, then the signed text should be provided in +@var{signed_text} and @var{plain} should be a null pointer. +Otherwise, if @var{sig} is a normal (or cleartext) signature, +@var{signed_text} should be a null pointer and @var{plain} should be a +writable data object that will contain the plaintext after successful +verification. + +The results of the individual signature verifications can be retrieved +with @code{gpgme_op_verify_result}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be completed successfully, @code{GPG_ERR_INV_VALUE} if +@var{ctx}, @var{sig} or @var{plain} is not a valid pointer, +@code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data to +verify, and passes through any errors that are reported by the crypto +engine support routines. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_verify_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}}) +The function @code{gpgme_op_verify_start} initiates a +@code{gpgme_op_verify} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, @code{GPG_ERR_INV_VALUE} if +@var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and +@code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain +any data to verify. +@end deftypefun + +@deftp {Data type} {gpgme_sig_notation_t} +This is a pointer to a structure used to store a part of the result of +a @code{gpgme_op_verify} operation. The structure contains the +following members: + +@table @code +@item gpgme_sig_notation_t next +This is a pointer to the next new signature notation structure in the +linked list, or @code{NULL} if this is the last element. + +@item char *name +The name of the notation field. If this is @code{NULL}, then the +member @code{value} will contain a policy URL. + +@item int name_len +The length of the @code{name} field. For strings the length is +counted without the trailing binary zero. + +@item char *value +The value of the notation field. If @code{name} is @code{NULL}, then +this is a policy URL. + +@item int value_len +The length of the @code{value} field. For strings the length is +counted without the trailing binary zero. + +@item gpgme_sig_notation_flags_t flags +The accumulated flags field. This field contains the flags associated +with the notation data in an accumulated form which can be used as an +argument to the function @code{gpgme_sig_notation_add}. The value +@code{flags} is a bitwise-or combination of one or multiple of the +following bit values: + +@table @code +@item GPGME_SIG_NOTATION_HUMAN_READABLE +The @code{GPGME_SIG_NOTATION_HUMAN_READABLE} symbol specifies that the +notation data is in human readable form + +@item GPGME_SIG_NOTATION_CRITICAL +The @code{GPGME_SIG_NOTATION_CRITICAL} symbol specifies that the +notation data is critical. + +@end table + +@item unsigned int human_readable : 1 +This is true if the @code{GPGME_SIG_NOTATION_HUMAN_READABLE} flag is +set and false otherwise. This flag is only valid for notation data, +not for policy URLs. + +@item unsigned int critical : 1 +This is true if the @code{GPGME_SIG_NOTATION_CRITICAL} flag is set and +false otherwise. This flag is valid for notation data and policy URLs. + +@end table +@end deftp + +@deftp {Data type} {gpgme_signature_t} +This is a pointer to a structure used to store a part of the result of +a @code{gpgme_op_verify} operation. The structure contains the +following members: + +@table @code +@item gpgme_signature_t next +This is a pointer to the next new signature structure in the linked +list, or @code{NULL} if this is the last element. + +@item gpgme_sigsum_t summary +This is a bit vector giving a summary of the signature status. It +provides an easy interface to a defined semantic of the signature +status. Checking just one bit is sufficient to see whether a +signature is valid without any restrictions. + +The defined bits are: + @table @code + @item GPGME_SIGSUM_VALID + The signature is fully valid. + + @item GPGME_SIGSUM_GREEN + The signature is good but one might want to display some extra + information. Check the other bits. + + @item GPGME_SIGSUM_RED + The signature is bad. It might be useful to check other bits and + display more information, i.e. a revoked certificate might not render a + signature invalid when the message was received prior to the cause for + the revocation. + + @item GPGME_SIGSUM_KEY_REVOKED + The key or at least one certificate has been revoked. + + @item GPGME_SIGSUM_KEY_EXPIRED + The key or one of the certificates has expired. It is probably a good + idea to display the date of the expiration. + + @item GPGME_SIGSUM_SIG_EXPIRED + The signature has expired. + + @item GPGME_SIGSUM_KEY_MISSING + Can't verify due to a missing key or certificate. + + @item GPGME_SIGSUM_CRL_MISSING + The CRL (or an equivalent mechanism) is not available. + + @item GPGME_SIGSUM_CRL_TOO_OLD + Available CRL is too old. + + @item GPGME_SIGSUM_BAD_POLICY + A policy requirement was not met. + + @item GPGME_SIGSUM_SYS_ERROR + A system error occured. + @end table + +@item char *fpr +This is the fingerprint or key ID of the signature. + +@item gpgme_error_t status +This is the status of the signature. In particular, the following +status codes are of interest: + + @table @code + @item GPG_ERR_NO_ERROR + This status indicates that the signature is valid. For the combined + result this status means that all signatures are valid. + + @item GPG_ERR_SIG_EXPIRED + This status indicates that the signature is valid but expired. For + the combined result this status means that all signatures are valid + and expired. + + @item GPG_ERR_KEY_EXPIRED + This status indicates that the signature is valid but the key used to + verify the signature has expired. For the combined result this status + means that all signatures are valid and all keys are expired. + + @item GPG_ERR_CERT_REVOKED + This status indicates that the signature is valid but the key used + to verify the signature has been revoked. For the combined result + this status means that all signatures are valid and all keys are + revoked. + + @item GPG_ERR_BAD_SIGNATURE + This status indicates that the signature is invalid. For the combined + result this status means that all signatures are invalid. + + @item GPG_ERR_NO_PUBKEY + This status indicates that the signature could not be verified due to + a missing key. For the combined result this status means that all + signatures could not be checked due to missing keys. + + @item GPG_ERR_GENERAL + This status indicates that there was some other error which prevented + the signature verification. + @end table + +@item gpgme_sig_notation_t notations +This is a linked list with the notation data and policy URLs. + +@item unsigned long timestamp +The creation timestamp of this signature. + +@item unsigned long exp_timestamp +The expiration timestamp of this signature, or 0 if the signature does +not expire. + +@item unsigned int wrong_key_usage : 1 +This is true if the key was not used according to its policy. + +@item unsigned int pka_trust : 2 +This is set to the trust information gained by means of the PKA system. +Values are: + @table @code + @item 0 + No PKA information available or verification not possible. + @item 1 + PKA verification failed. + @item 2 + PKA verification succeeded. + @item 3 + Reserved for future use. + @end table +Depending on the configuration of the engine, this metric may also be +reflected by the validity of the signature. + +@item unsigned int chain_model : 1 +This is true if the validity of the signature has been checked using the +chain model. In the chain model the time the signature has been created +must be within the validity period of the certificate and the time the +certificate itself has been created must be within the validity period +of the issuing certificate. In contrast the default validation model +checks the validity of signature as well at the entire certificate chain +at the current time. + + +@item gpgme_validity_t validity +The validity of the signature. + +@item gpgme_error_t validity_reason +If a signature is not valid, this provides a reason why. + +@item gpgme_pubkey_algo_t +The public key algorithm used to create this signature. + +@item gpgme_hash_algo_t +The hash algorithm used to create this signature. +@end table +@end deftp + +@deftp {Data type} {gpgme_verify_result_t} +This is a pointer to a structure used to store the result of a +@code{gpgme_op_verify} operation. After verifying a signature, you +can retrieve the pointer to the result with +@code{gpgme_op_verify_result}. If the operation failed this might be +a @code{NULL} pointer. The structure contains the following member: + +@table @code +@item gpgme_signature_t signatures +A linked list with information about all signatures for which a +verification was attempted. + +@item char *file_name +This is the filename of the original plaintext message file if it is +known, otherwise this is a null pointer. +@end table +@end deftp + +@deftypefun gpgme_verify_result_t gpgme_op_verify_result (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_op_verify_result} returns a +@code{gpgme_verify_result_t} pointer to a structure holding the result +of a @code{gpgme_op_verify} operation. The pointer is only valid if +the last operation on the context was a @code{gpgme_op_verify}, +@code{gpgme_op_verify_start}, @code{gpgme_op_decrypt_verify} or +@code{gpgme_op_decrypt_verify_start} operation, and if this operation +finished successfully (for @code{gpgme_op_decrypt_verify} and +@code{gpgme_op_decrypt_verify_start}, the error code +@code{GPG_ERR_NO_DATA} counts as successful in this context). The +returned pointer is only valid until the next operation is started on +the context. +@end deftypefun + + +The following interfaces are deprecated and only provided for backward +compatibility. Don't use them. They will be removed in a future +version of @acronym{GPGME}. + +@deftp {Data type} {enum gpgme_sig_stat_t} +@tindex gpgme_sig_stat_t +The @code{gpgme_sig_stat_t} type holds the result of a signature check, or +the combined result of all signatures. The following results are +possible: + +@table @code +@item GPGME_SIG_STAT_NONE +This status should not occur in normal operation. + +@item GPGME_SIG_STAT_GOOD +This status indicates that the signature is valid. For the combined +result this status means that all signatures are valid. + +@item GPGME_SIG_STAT_GOOD_EXP +This status indicates that the signature is valid but expired. For +the combined result this status means that all signatures are valid +and expired. + +@item GPGME_SIG_STAT_GOOD_EXPKEY +This status indicates that the signature is valid but the key used to +verify the signature has expired. For the combined result this status +means that all signatures are valid and all keys are expired. + +@item GPGME_SIG_STAT_BAD +This status indicates that the signature is invalid. For the combined +result this status means that all signatures are invalid. + +@item GPGME_SIG_STAT_NOKEY +This status indicates that the signature could not be verified due to +a missing key. For the combined result this status means that all +signatures could not be checked due to missing keys. + +@item GPGME_SIG_STAT_NOSIG +This status indicates that the signature data provided was not a real +signature. + +@item GPGME_SIG_STAT_ERROR +This status indicates that there was some other error which prevented +the signature verification. + +@item GPGME_SIG_STAT_DIFF +For the combined result this status means that at least two signatures +have a different status. You can get each key's status with +@code{gpgme_get_sig_status}. +@end table +@end deftp + +@deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}}) +The function @code{gpgme_get_sig_status} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return NULL; + + if (r_stat) + @{ + switch (gpg_err_code (sig->status)) + @{ + case GPG_ERR_NO_ERROR: + *r_stat = GPGME_SIG_STAT_GOOD; + break; + + case GPG_ERR_BAD_SIGNATURE: + *r_stat = GPGME_SIG_STAT_BAD; + break; + + case GPG_ERR_NO_PUBKEY: + *r_stat = GPGME_SIG_STAT_NOKEY; + break; + + case GPG_ERR_NO_DATA: + *r_stat = GPGME_SIG_STAT_NOSIG; + break; + + case GPG_ERR_SIG_EXPIRED: + *r_stat = GPGME_SIG_STAT_GOOD_EXP; + break; + + case GPG_ERR_KEY_EXPIRED: + *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY; + break; + + default: + *r_stat = GPGME_SIG_STAT_ERROR; + break; + @} + @} + if (r_created) + *r_created = sig->timestamp; + return sig->fpr; +@end example +@end deftypefun + +@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}}) +The function @code{gpgme_get_sig_string_attr} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return NULL; + + switch (what) + @{ + case GPGME_ATTR_FPR: + return sig->fpr; + + case GPGME_ATTR_ERRTOK: + if (whatidx == 1) + return sig->wrong_key_usage ? "Wrong_Key_Usage" : ""; + else + return ""; + default: + break; + @} + + return NULL; +@end example +@end deftypefun + +@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}}) +The function @code{gpgme_get_sig_ulong_attr} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return 0; + + switch (what) + @{ + case GPGME_ATTR_CREATED: + return sig->timestamp; + + case GPGME_ATTR_EXPIRE: + return sig->exp_timestamp; + + case GPGME_ATTR_VALIDITY: + return (unsigned long) sig->validity; + + case GPGME_ATTR_SIG_STATUS: + switch (sig->status) + @{ + case GPG_ERR_NO_ERROR: + return GPGME_SIG_STAT_GOOD; + + case GPG_ERR_BAD_SIGNATURE: + return GPGME_SIG_STAT_BAD; + + case GPG_ERR_NO_PUBKEY: + return GPGME_SIG_STAT_NOKEY; + + case GPG_ERR_NO_DATA: + return GPGME_SIG_STAT_NOSIG; + + case GPG_ERR_SIG_EXPIRED: + return GPGME_SIG_STAT_GOOD_EXP; + + case GPG_ERR_KEY_EXPIRED: + return GPGME_SIG_STAT_GOOD_EXPKEY; + + default: + return GPGME_SIG_STAT_ERROR; + @} + + case GPGME_ATTR_SIG_SUMMARY: + return sig->summary; + + default: + break; + @} + return 0; +@end example +@end deftypefun + +@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}}) +The function @code{gpgme_get_sig_key} is equivalent to: + +@example + gpgme_verify_result_t result; + gpgme_signature_t sig; + + result = gpgme_op_verify_result (ctx); + sig = result->signatures; + + while (sig && idx) + @{ + sig = sig->next; + idx--; + @} + if (!sig || idx) + return gpg_error (GPG_ERR_EOF); + + return gpgme_get_key (ctx, sig->fpr, r_key, 0); +@end example +@end deftypefun + + +@node Decrypt and Verify +@subsection Decrypt and Verify +@cindex decryption and verification +@cindex verification and decryption +@cindex signature check +@cindex cryptographic operation, decryption and verification + +@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}}) +The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in +the data object @var{cipher} and stores it into the data object +@var{plain}. If @var{cipher} contains signatures, they will be +verified. + +After the operation completed, @code{gpgme_op_decrypt_result} and +@code{gpgme_op_verify_result} can be used to retrieve more information +about the signatures. + +If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher} +does not contain any data to decrypt. However, it might still be +signed. The information about detected signatures is available with +@code{gpgme_op_verify_result} in this case. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE} +if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer, +@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to +decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid +cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the +secret key could not be retrieved, and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}}) +The function @code{gpgme_op_decrypt_verify_start} initiates a +@code{gpgme_op_decrypt_verify} operation. It can be completed by +calling @code{gpgme_wait} on the context. @xref{Waiting For +Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, @code{GPG_ERR_INV_VALUE} if +@var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid +pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain +any data to decrypt. +@end deftypefun + + +@node Sign +@subsection Sign +@cindex signature, creation +@cindex sign +@cindex cryptographic operation, signing + +A signature can contain signatures by one or more keys. The set of +keys used to create a signatures is contained in a context, and is +applied to all following signing operations in this context (until the +set is changed). + +@menu +* Selecting Signers:: How to choose the keys to sign with. +* Creating a Signature:: How to create a signature. +* Signature Notation Data:: How to add notation data to a signature. +@end menu + + +@node Selecting Signers +@subsubsection Selecting Signers +@cindex signature, selecting signers +@cindex signers, selecting + +@deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_signers_clear} releases a reference for each +key on the signers list and removes the list of signers from the +context @var{ctx}. + +Every context starts with an empty list. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}) +The function @code{gpgme_signers_add} adds the key @var{key} to the +list of signers in the context @var{ctx}. + +Calling this function acquires an additional reference for the key. +@end deftypefun + +@deftypefun gpgme_key_t gpgme_signers_enum (@w{const gpgme_ctx_t @var{ctx}}, @w{int @var{seq}}) +The function @code{gpgme_signers_enum} returns the @var{seq}th key in +the list of signers in the context @var{ctx}. An additional reference +is acquired for the user. + +If @var{seq} is out of range, @code{NULL} is returned. +@end deftypefun + + +@node Creating a Signature +@subsubsection Creating a Signature + +@deftp {Data type} {enum gpgme_sig_mode_t} +@tindex gpgme_sig_mode_t +The @code{gpgme_sig_mode_t} type is used to specify the desired type of a +signature. The following modes are available: + +@table @code +@item GPGME_SIG_MODE_NORMAL +A normal signature is made, the output includes the plaintext and the +signature. + +@item GPGME_SIG_MODE_DETACH +A detached signature is made. + +@item GPGME_SIG_MODE_CLEAR +A clear text signature is made. The @acronym{ASCII} armor and text +mode settings of the context are ignored. +@end table +@end deftp + +@deftypefun gpgme_error_t gpgme_op_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}}) +The function @code{gpgme_op_sign} creates a signature for the text in +the data object @var{plain} and returns it in the data object +@var{sig}. The type of the signature created is determined by the +@acronym{ASCII} armor (or, if that is not set, by the encoding +specified for @var{sig}), the text mode attributes set for the context +@var{ctx} and the requested signature mode @var{mode}. + +After the operation completed successfully, the result can be +retrieved with @code{gpgme_op_sign_result}. + +If an S/MIME signed message is created using the CMS crypto engine, +the number of certificates to include in the message can be specified +with @code{gpgme_set_include_certs}. @xref{Included Certificates}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +signature could be created successfully, @code{GPG_ERR_INV_VALUE} if +@var{ctx}, @var{plain} or @var{sig} is not a valid pointer, +@code{GPG_ERR_NO_DATA} if the signature could not be created, +@code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the secret key +could not be retrieved, @code{GPG_ERR_UNUSABLE_SECKEY} if there are +invalid signers, and passes through any errors that are reported by the +crypto engine support routines. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}}) +The function @code{gpgme_op_sign_start} initiates a +@code{gpgme_op_sign} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the operation could be +started successfully, and @code{GPG_ERR_INV_VALUE} if @var{ctx}, +@var{plain} or @var{sig} is not a valid pointer. +@end deftypefun + +@deftp {Data type} {gpgme_new_signature_t} +This is a pointer to a structure used to store a part of the result of +a @code{gpgme_op_sign} operation. The structure contains the +following members: + +@table @code +@item gpgme_new_signature_t next +This is a pointer to the next new signature structure in the linked +list, or @code{NULL} if this is the last element. + +@item gpgme_sig_mode_t type +The type of this signature. + +@item gpgme_pubkey_algo_t +The public key algorithm used to create this signature. + +@item gpgme_hash_algo_t +The hash algorithm used to create this signature. + +@item unsigned int sig_class +The signature class of this signature. + +@item long int timestamp +The creation timestamp of this signature. + +@item char *fpr +The fingerprint of the key which was used to create this signature. +@end table +@end deftp + +@deftp {Data type} {gpgme_sign_result_t} +This is a pointer to a structure used to store the result of a +@code{gpgme_op_sign} operation. After successfully generating a +signature, you can retrieve the pointer to the result with +@code{gpgme_op_sign_result}. The structure contains the following +members: + +@table @code +@item gpgme_invalid_key_t invalid_signers +A linked list with information about all invalid keys for which a +signature could not be created. + +@item gpgme_new_signature_t signatures +A linked list with information about all signatures created. +@end table +@end deftp + +@deftypefun gpgme_sign_result_t gpgme_op_sign_result (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_op_sign_result} returns a +@code{gpgme_sign_result_t} pointer to a structure holding the result +of a @code{gpgme_op_sign} operation. The pointer is only valid if the +last operation on the context was a @code{gpgme_op_sign}, +@code{gpgme_op_sign_start}, @code{gpgme_op_encrypt_sign} or +@code{gpgme_op_encrypt_sign_start} operation. If that operation +failed, the function might return a @code{NULL} pointer. The returned +pointer is only valid until the next operation is started on the +context. +@end deftypefun + + +@node Signature Notation Data +@subsubsection Signature Notation Data +@cindex notation data +@cindex signature notation data +@cindex policy URL + +Using the following functions, you can attach arbitrary notation data +to a signature. This information is then available to the user when +the signature is verified. + +@deftypefun void gpgme_sig_notation_clear (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_sig_notation_clear} removes the notation data +from the context @var{ctx}. Subsequent signing operations from this +context will not include any notation data. + +Every context starts with an empty notation data list. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_sig_notation_add (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{name}}, @w{const char *@var{value}}, @w{gpgme_sig_notation_flags_t @var{flags}}) +The function @code{gpgme_sig_notation_add} adds the notation data with +the name @var{name} and the value @var{value} to the context +@var{ctx}. + +Subsequent signing operations will include this notation data, as well +as any other notation data that was added since the creation of the +context or the last @code{gpgme_sig_notation_clear} operation. + +The arguments @var{name} and @var{value} must be @code{NUL}-terminated +strings in human-readable form. The flag +@code{GPGME_SIG_NOTATION_HUMAN_READABLE} is implied +(non-human-readable notation data is currently not supported). The +strings must be in UTF-8 encoding. + +If @var{name} is @code{NULL}, then @var{value} should be a policy URL. + +The function @code{gpgme_sig_notation_add} returns the error code +@code{GPG_ERR_NO_ERROR} if the notation data could be added +successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} is not a valid +pointer, or if @var{name}, @var{value} and @var{flags} are an invalid +combination. The function also passes through any errors that are +reported by the crypto engine support routines. +@end deftypefun + +@deftypefun gpgme_sig_notation_t gpgme_sig_notation_get (@w{const gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_sig_notation_get} returns the linked list of +notation data structures that are contained in the context @var{ctx}. + +If @var{ctx} is not a valid pointer, or there is no notation data +added for this context, @code{NULL} is returned. +@end deftypefun + + +@node Encrypt +@subsection Encrypt +@cindex encryption +@cindex cryptographic operation, encryption + +One plaintext can be encrypted for several recipients at the same +time. The list of recipients is created independently of any context, +and then passed to the encryption operation. + +@menu +* Encrypting a Plaintext:: How to encrypt a plaintext. +@end menu + + +@node Encrypting a Plaintext +@subsubsection Encrypting a Plaintext + +@deftypefun gpgme_error_t gpgme_op_encrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}}) +The function @code{gpgme_op_encrypt} encrypts the plaintext in the +data object @var{plain} for the recipients @var{recp} and stores the +ciphertext in the data object @var{cipher}. The type of the +ciphertext created is determined by the @acronym{ASCII} armor (or, if +that is not set, by the encoding specified for @var{cipher}) and the +text mode attributes set for the context @var{ctx}. + +@var{key} must be a @code{NULL}-terminated array of keys. The user +must keep references for all keys during the whole duration of the +call (but see @code{gpgme_op_encrypt_start} for the requirements with +the asynchronous variant). + +The value in @var{flags} is a bitwise-or combination of one or +multiple of the following bit values: + +@table @code +@item GPGME_ENCRYPT_ALWAYS_TRUST +The @code{GPGME_ENCRYPT_ALWAYS_TRUST} symbol specifies that all the +recipients in @var{recp} should be trusted, even if the keys do not +have a high enough validity in the keyring. This flag should be used +with care; in general it is not a good idea to use any untrusted keys. + +@item GPGME_ENCRYPT_NO_ENCRYPT_TO +The @code{GPGME_ENCRYPT_NO_ENCRYPT_TO} symbol specifies that no +default or hidden default recipients as configured in the crypto +backend should be included. This can be useful for managing different +user profiles. +@end table + +If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in +@var{recp} are invalid, but not all. In this case the plaintext might +be encrypted for all valid recipients and returned in @var{cipher} (if +this happens depends on the crypto engine). More information about +the invalid recipients is available with +@code{gpgme_op_encrypt_result}. + +If @var{recp} is @code{NULL}, symmetric rather than public key +encryption is performed. Symmetrically encrypted cipher text can be +deciphered with @code{gpgme_op_decrypt}. Note that in this case the +crypto backend needs to retrieve a passphrase from the user. +Symmetric encryption is currently only supported for the OpenPGP +crypto backend. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +ciphertext could be created successfully, @code{GPG_ERR_INV_VALUE} if +@var{ctx}, @var{recp}, @var{plain} or @var{cipher} is not a valid +pointer, @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{recp} contains some +invalid recipients, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase +for the symmetric key could not be retrieved, and passes through any +errors that are reported by the crypto engine support routines. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_encrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}}) +The function @code{gpgme_op_encrypt_start} initiates a +@code{gpgme_op_encrypt} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +References to the keys only need to be held for the duration of this +call. The user can release its references to the keys after this +function returns, even if the operation is not yet finished. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, @code{GPG_ERR_INV_VALUE} if +@var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid +pointer, and @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{rset} does not +contain any valid recipients. +@end deftypefun + +@deftp {Data type} {gpgme_encrypt_result_t} +This is a pointer to a structure used to store the result of a +@code{gpgme_op_encrypt} operation. After successfully encrypting +data, you can retrieve the pointer to the result with +@code{gpgme_op_encrypt_result}. The structure contains the following +members: + +@table @code +@item gpgme_invalid_key_t invalid_recipients +A linked list with information about all invalid keys for which +the data could not be encrypted. +@end table +@end deftp + +@deftypefun gpgme_encrypt_result_t gpgme_op_encrypt_result (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_op_encrypt_result} returns a +@code{gpgme_encrypt_result_t} pointer to a structure holding the +result of a @code{gpgme_op_encrypt} operation. The pointer is only +valid if the last operation on the context was a +@code{gpgme_op_encrypt}, @code{gpgme_op_encrypt_start}, +@code{gpgme_op_sign} or @code{gpgme_op_sign_start} operation. If this +operation failed, this might be a @code{NULL} pointer. The returned +pointer is only valid until the next operation is started on the +context. +@end deftypefun + + +@deftypefun gpgme_error_t gpgme_op_encrypt_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}}) +The function @code{gpgme_op_encrypt_sign} does a combined encrypt and +sign operation. It is used like @code{gpgme_op_encrypt}, but the +ciphertext also contains signatures for the signers listed in +@var{ctx}. + +The combined encrypt and sign operation is currently only available +for the OpenPGP crypto engine. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}}) +The function @code{gpgme_op_encrypt_sign_start} initiates a +@code{gpgme_op_encrypt_sign} operation. It can be completed by +calling @code{gpgme_wait} on the context. @xref{Waiting For +Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, and @code{GPG_ERR_INV_VALUE} +if @var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid +pointer. +@end deftypefun + + +@node Run Control +@section Run Control +@cindex run control +@cindex cryptographic operation, running + +@acronym{GPGME} supports running operations synchronously and +asynchronously. You can use asynchronous operation to set up a +context up to initiating the desired operation, but delay performing +it to a later point. + +Furthermore, you can use an external event loop to control exactly +when @acronym{GPGME} runs. This ensures that @acronym{GPGME} only +runs when necessary and also prevents it from blocking for a long +time. + +@menu +* Waiting For Completion:: Waiting until an operation is completed. +* Using External Event Loops:: Advanced control over what happens when. +* Cancellation:: How to end pending operations prematurely. +@end menu + + +@node Waiting For Completion +@subsection Waiting For Completion +@cindex cryptographic operation, wait for +@cindex wait for completion + +@deftypefun gpgme_ctx_t gpgme_wait (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_error_t *@var{status}}, @w{int @var{hang}}) +The function @code{gpgme_wait} continues the pending operation within +the context @var{ctx}. In particular, it ensures the data exchange +between @acronym{GPGME} and the crypto backend and watches over the +run time status of the backend process. + +If @var{hang} is true, the function does not return until the +operation is completed or cancelled. Otherwise the function will not +block for a long time. + +The error status of the finished operation is returned in @var{status} +if @code{gpgme_wait} does not return @code{NULL}. + +The @var{ctx} argument can be @code{NULL}. In that case, +@code{gpgme_wait} waits for any context to complete its operation. + +@code{gpgme_wait} can be used only in conjunction with any context +that has a pending operation initiated with one of the +@code{gpgme_op_*_start} functions except @code{gpgme_op_keylist_start} +and @code{gpgme_op_trustlist_start} (for which you should use the +corresponding @code{gpgme_op_*_next} functions). If @var{ctx} is +@code{NULL}, all of such contexts are waited upon and possibly +returned. Synchronous operations running in parallel, as well as key +and trust item list operations, do not affect @code{gpgme_wait}. + +In a multi-threaded environment, only one thread should ever call +@code{gpgme_wait} at any time, irregardless if @var{ctx} is specified +or not. This means that all calls to this function should be fully +synchronized by locking primitives. It is safe to start asynchronous +operations while a thread is running in @code{gpgme_wait}. + +The function returns the @var{ctx} of the context which has finished +the operation. If @var{hang} is false, and the timeout expires, +@code{NULL} is returned and @code{*status} will be set to 0. If an +error occurs, @code{NULL} is returned and the error is returned in +@code{*status}. +@end deftypefun + + +@node Using External Event Loops +@subsection Using External Event Loops +@cindex event loop, external + +@acronym{GPGME} hides the complexity of the communication between the +library and the crypto engine. The price of this convenience is that +the calling thread can block arbitrary long waiting for the data +returned by the crypto engine. In single-threaded programs, in +particular if they are interactive, this is an unwanted side-effect. +OTOH, if @code{gpgme_wait} is used without the @var{hang} option being +enabled, it might be called unnecessarily often, wasting CPU time that +could be used otherwise. + +The I/O callback interface described in this section lets the user +take control over what happens when. @acronym{GPGME} will provide the +user with the file descriptors that should be monitored, and the +callback functions that should be invoked when a file descriptor is +ready for reading or writing. It is then the user's responsibility to +decide when to check the file descriptors and when to invoke the +callback functions. Usually this is done in an event loop, that also +checks for events in other parts of the program. If the callback +functions are only called when the file descriptors are ready, +@acronym{GPGME} will never block. This gives the user more control +over the program flow, and allows to perform other tasks when +@acronym{GPGME} would block otherwise. + +By using this advanced mechanism, @acronym{GPGME} can be integrated +smoothly into GUI toolkits like GTK+ even for single-threaded +programs. + +@menu +* I/O Callback Interface:: How I/O callbacks are registered. +* Registering I/O Callbacks:: How to use I/O callbacks for a context. +* I/O Callback Example:: An example how to use I/O callbacks. +* I/O Callback Example GTK+:: How to use @acronym{GPGME} with GTK+. +* I/O Callback Example GDK:: How to use @acronym{GPGME} with GDK. +* I/O Callback Example Qt:: How to use @acronym{GPGME} with Qt. +@end menu + + +@node I/O Callback Interface +@subsubsection I/O Callback Interface + +@deftp {Data type} {gpgme_error_t (*gpgme_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}})} +@tindex gpgme_io_cb_t +The @code{gpgme_io_cb_t} type is the type of functions which +@acronym{GPGME} wants to register as I/O callback handlers using the +@code{gpgme_register_io_cb_t} functions provided by the user. + +@var{data} and @var{fd} are provided by @acronym{GPGME} when the I/O +callback handler is registered, and should be passed through to the +handler when it is invoked by the user because it noticed activity on +the file descriptor @var{fd}. + +The callback handler always returns @code{0}, but you should consider +the return value to be reserved for later use. +@end deftp + +@deftp {Data type} {gpgme_error_t (*gpgme_register_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}}, @w{int @var{dir}}, @w{gpgme_io_cb_t @var{fnc}}, @w{void *@var{fnc_data}}, @w{void **@var{tag}})} +@tindex gpgme_register_io_cb_t +The @code{gpgme_register_io_cb_t} type is the type of functions which can +be called by @acronym{GPGME} to register an I/O callback function +@var{fnc} for the file descriptor @var{fd} with the user. +@var{fnc_data} should be passed as the first argument to @var{fnc} +when the handler is invoked (the second argument should be @var{fd}). +If @var{dir} is 0, @var{fnc} should be called by the user when +@var{fd} is ready for writing. If @var{dir} is 1, @var{fnc} should be +called when @var{fd} is ready for reading. + +@var{data} was provided by the user when registering the +@code{gpgme_register_io_cb_t} function with @acronym{GPGME} and will always +be passed as the first argument when registering a callback function. +For example, the user can use this to determine the event loop to +which the file descriptor should be added. + +@acronym{GPGME} will call this function when a crypto operation is +initiated in a context for which the user has registered I/O callback +handler functions with @code{gpgme_set_io_cbs}. It can also call this +function when it is in an I/O callback handler for a file descriptor +associated to this context. + +The user should return a unique handle in @var{tag} identifying this +I/O callback registration, which will be passed to the +@code{gpgme_register_io_cb_t} function without interpretation when the file +descriptor should not be monitored anymore. +@end deftp + +@deftp {Data type} {void (*gpgme_remove_io_cb_t) (@w{void *@var{tag}})} +The @code{gpgme_remove_io_cb_t} type is the type of functions which can be +called by @acronym{GPGME} to remove an I/O callback handler that was +registered before. @var{tag} is the handle that was returned by the +@code{gpgme_register_io_cb_t} for this I/O callback. + +@acronym{GPGME} can call this function when a crypto operation is in +an I/O callback. It will also call this function when the context is +destroyed while an operation is pending. +@end deftp + +@deftp {Data type} {enum gpgme_event_io_t} +@tindex gpgme_event_io_t +The @code{gpgme_event_io_t} type specifies the type of an event that is +reported to the user by @acronym{GPGME} as a consequence of an I/O +operation. The following events are defined: + +@table @code +@item GPGME_EVENT_START +The operation is fully initialized now, and you can start to run the +registered I/O callback handlers now. Note that registered I/O +callback handlers must not be run before this event is signalled. +@var{type_data} is @code{NULL} and reserved for later use. + +@item GPGME_EVENT_DONE +The operation is finished, the last I/O callback for this operation +was removed. The accompanying @var{type_data} points to a +@code{gpgme_error_t} variable that contains the status of the operation +that finished. This event is signalled after the last I/O callback +has been removed. + +@item GPGME_EVENT_NEXT_KEY +In a @code{gpgme_op_keylist_start} operation, the next key was +received from the crypto engine. The accompanying @var{type_data} is +a @code{gpgme_key_t} variable that contains the key with one reference +for the user. + +@item GPGME_EVENT_NEXT_TRUSTITEM +In a @code{gpgme_op_trustlist_start} operation, the next trust item +was received from the crypto engine. The accompanying @var{type_data} +is a @code{gpgme_trust_item_t} variable that contains the trust item with +one reference for the user. +@end table +@end deftp + +@deftp {Data type} {void (*gpgme_event_io_cb_t) (@w{void *@var{data}}, @w{gpgme_event_io_t @var{type}}, @w{void *@var{type_data}})} +The @code{gpgme_event_io_cb_t} type is the type of functions which can be +called by @acronym{GPGME} to signal an event for an operation running +in a context which has I/O callback functions registered by the user. + +@var{data} was provided by the user when registering the +@code{gpgme_event_io_cb_t} function with @acronym{GPGME} and will always be +passed as the first argument when registering a callback function. +For example, the user can use this to determine the context in which +this event has occured. + +@var{type} will specify the type of event that has occured. +@var{type_data} specifies the event further, as described in the above +list of possible @code{gpgme_event_io_t} types. + +@acronym{GPGME} can call this function in an I/O callback handler. +@end deftp + + +@node Registering I/O Callbacks +@subsubsection Registering I/O Callbacks + +@deftp {Data type} {struct gpgme_io_cb_ts} +@tindex gpgme_event_io_t +This structure is used to store the I/O callback interface functions +described in the previous section. It has the following members: + +@table @code +@item gpgme_register_io_cb_t add +This is the function called by @acronym{GPGME} to register an I/O +callback handler. It must be specified. + +@item void *add_data +This is passed as the first argument to the @code{add} function when +it is called by @acronym{GPGME}. For example, it can be used to +determine the event loop to which the file descriptor should be added. + +@item gpgme_remove_io_cb_t remove +This is the function called by @acronym{GPGME} to remove an I/O +callback handler. It must be specified. + +@item gpgme_event_io_cb_t event +This is the function called by @acronym{GPGME} to signal an event for +an operation. It must be specified, because at least the start event +must be processed. + +@item void *event_data +This is passed as the first argument to the @code{event} function when +it is called by @acronym{GPGME}. For example, it can be used to +determine the context in which the event has occured. +@end table +@end deftp + +@deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}}) +The function @code{gpgme_set_io_cbs} enables the I/O callback +interface for the context @var{ctx}. The I/O callback functions are +specified by @var{io_cbs}. + +If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface +is disabled for the context, and normal operation is restored. +@end deftypefun + +@deftypefun void gpgme_get_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}}) +The function @code{gpgme_get_io_cbs} returns the I/O callback +functions set with @code{gpgme_set_io_cbs} in @var{io_cbs}. +@end deftypefun + + +@node I/O Callback Example +@subsubsection I/O Callback Example + +To actually use an external event loop, you have to implement the I/O +callback functions that are used by @acronym{GPGME} to register and +unregister file descriptors. Furthermore, you have to actually +monitor these file descriptors for activity and call the appropriate +I/O callbacks. + +The following example illustrates how to do that. The example uses +locking to show in which way the callbacks and the event loop can +run concurrently. For the event loop, we use a fixed array. For a +real-world implementation, you should use a dynamically sized +structure because the number of file descriptors needed for a crypto +operation in @acronym{GPGME} is not predictable. + +@example +#include <assert.h> +#include <errno.h> +#include <stdlib.h> +#include <pthread.h> +#include <sys/types.h> +#include <gpgme.h> + +/* The following structure holds the result of a crypto operation. */ +struct op_result +@{ + int done; + gpgme_error_t err; +@}; + +/* The following structure holds the data associated with one I/O +callback. */ +struct one_fd +@{ + int fd; + int dir; + gpgme_io_cb_t fnc; + void *fnc_data; + void *loop; +@}; + +struct event_loop +@{ + pthread_mutex_t lock; +#define MAX_FDS 32 + /* Unused slots are marked with FD being -1. */ + struct one_fd fds[MAX_FDS]; +@}; +@end example + +The following functions implement the I/O callback interface. + +@example +gpgme_error_t +add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data, + void **r_tag) +@{ + struct event_loop *loop = data; + struct one_fd *fds = loop->fds; + int i; + + pthread_mutex_lock (&loop->lock); + for (i = 0; i < MAX_FDS; i++) + @{ + if (fds[i].fd == -1) + @{ + fds[i].fd = fd; + fds[i].dir = dir; + fds[i].fnc = fnc; + fds[i].fnc_data = fnc_data; + fds[i].loop = loop; + break; + @} + @} + pthread_mutex_unlock (&loop->lock); + if (i == MAX_FDS) + return gpg_error (GPG_ERR_GENERAL); + *r_tag = &fds[i]; + return 0; +@} + +void +remove_io_cb (void *tag) +@{ + struct one_fd *fd = tag; + struct event_loop *loop = fd->loop; + + pthread_mutex_lock (&loop->lock); + fd->fd = -1; + pthread_mutex_unlock (&loop->lock); +@} + +void +event_io_cb (void *data, gpgme_event_io_t type, void *type_data) +@{ + struct op_result *result = data; + + /* We don't support list operations here. */ + if (type == GPGME_EVENT_DONE) + @{ + result->done = 1; + result->err = *type_data; + @} +@} +@end example + +The final missing piece is the event loop, which will be presented +next. We only support waiting for the success of a single operation. + +@example +int +do_select (struct event_loop *loop) +@{ + fd_set rfds; + fd_set wfds; + int i, n; + int any = 0; + struct one_fd *fdlist = loop->fds; + + pthread_mutex_lock (&loop->lock); + FD_ZERO (&rfds); + FD_ZERO (&wfds); + for (i = 0; i < MAX_FDS; i++) + if (fdlist[i].fd != -1) + FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds); + pthread_mutex_unlock (&loop->unlock); + + do + @{ + n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0); + @} + while (n < 0 && errno == EINTR); + + if (n < 0) + return n; /* Error or timeout. */ + + pthread_mutex_lock (&loop->lock); + for (i = 0; i < MAX_FDS && n; i++) + @{ + if (fdlist[i].fd != -1) + @{ + if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds)) + @{ + assert (n); + n--; + any = 1; + /* The I/O callback handler can register/remove callbacks, + so we have to unlock the file descriptor list. */ + pthread_mutex_unlock (&loop->lock); + (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd); + pthread_mutex_lock (&loop->lock); + @} + @} + @} + pthread_mutex_unlock (&loop->lock); + return any; +@} + +void +wait_for_op (struct event_loop *loop, struct op_result *result) +@{ + int ret; + + do + @{ + ret = do_select (loop); + @} + while (ret >= 0 && !result->done); +@} +@end example + +The main function shows how to put it all together. + +@example +int +main (int argc, char *argv[]) +@{ + struct event_loop loop; + struct op_result result; + gpgme_ctx_t ctx; + gpgme_error_t err; + gpgme_data_t sig, text; + int i; + struct gpgme_io_cb_ts io_cbs = + @{ + add_io_cb, + &loop, + remove_io_cb, + event_io_cb, + &result + @}; + + init_gpgme (void); + + /* Initialize the loop structure. */ + pthread_mutex_init (&loop.lock, NULL); + for (i = 0; i < MAX_FDS; i++) + loop->fds[i].fd = -1; + + /* Initialize the result structure. */ + result.done = 0; + + err = gpgme_data_new_from_file (&sig, "signature", 1); + if (!err) + err = gpgme_data_new_from_file (&text, "text", 1); + if (!err) + err = gpgme_new (&ctx); + if (!err) + @{ + gpgme_set_io_cbs (ctx, &io_cbs); + err = gpgme_op_verify_start (ctx, sig, text, NULL); + @} + if (err) + @{ + fprintf (stderr, "gpgme error: %s: %s\n", + gpgme_strsource (err), gpgme_strerror (err)); + exit (1); + @} + + wait_for_op (&loop, &result); + if (!result.done) + @{ + fprintf (stderr, "select error\n"); + exit (1); + @} + if (!result.err) + @{ + fprintf (stderr, "verification failed: %s: %s\n", + gpgme_strsource (result.err), gpgme_strerror (result.err)); + exit (1); + @} + /* Evaluate verify result. */ + @dots{} + return 0; +@} +@end example + + +@node I/O Callback Example GTK+ +@subsubsection I/O Callback Example GTK+ +@cindex GTK+, using @acronym{GPGME} with + +The I/O callback interface can be used to integrate @acronym{GPGME} +with the GTK+ event loop. The following code snippets shows how this +can be done using the appropriate register and remove I/O callback +functions. In this example, the private data of the register I/O +callback function is unused. The event notifications is missing +because it does not require any GTK+ specific setup. + +@example +#include <gtk/gtk.h> + +struct my_gpgme_io_cb +@{ + gpgme_io_cb_t fnc; + void *fnc_data; + guint input_handler_id +@}; + +void +my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) +@{ + struct my_gpgme_io_cb *iocb = data; + (*(iocb->fnc)) (iocb->data, source); +@} + +void +my_gpgme_remove_io_cb (void *data) +@{ + struct my_gpgme_io_cb *iocb = data; + gtk_input_remove (data->input_handler_id); +@} + +void +my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc, + void *fnc_data, void **tag) +@{ + struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); + iocb->fnc = fnc; + iocb->data = fnc_data; + iocb->input_handler_id = gtk_input_add_full (fd, dir + ? GDK_INPUT_READ + : GDK_INPUT_WRITE, + my_gpgme_io_callback, + 0, iocb, NULL); + *tag = iocb; + return 0; +@} +@end example + + +@node I/O Callback Example GDK +@subsubsection I/O Callback Example GDK +@cindex GDK, using @acronym{GPGME} with + +The I/O callback interface can also be used to integrate +@acronym{GPGME} with the GDK event loop. The following code snippets +shows how this can be done using the appropriate register and remove +I/O callback functions. In this example, the private data of the +register I/O callback function is unused. The event notifications is +missing because it does not require any GDK specific setup. + +It is very similar to the GTK+ example in the previous section. + +@example +#include <gdk/gdk.h> + +struct my_gpgme_io_cb +@{ + gpgme_io_cb_t fnc; + void *fnc_data; + gint tag; +@}; + +void +my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) +@{ + struct my_gpgme_io_cb *iocb = data; + (*(iocb->fnc)) (iocb->data, source); +@} + +void +my_gpgme_remove_io_cb (void *data) +@{ + struct my_gpgme_io_cb *iocb = data; + gdk_input_remove (data->tag); +@} + +void +my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc, + void *fnc_data, void **tag) +@{ + struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); + iocb->fnc = fnc; + iocb->data = fnc_data; + iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE, + my_gpgme_io_callback, iocb, NULL); + *tag = iocb; + return 0; +@} +@end example + + +@node I/O Callback Example Qt +@subsubsection I/O Callback Example Qt +@cindex Qt, using @acronym{GPGME} with + +The I/O callback interface can also be used to integrate +@acronym{GPGME} with the Qt event loop. The following code snippets +show how this can be done using the appropriate register and remove +I/O callback functions. In this example, the private data of the +register I/O callback function is unused. The event notifications is +missing because it does not require any Qt specific setup. + +@example +#include <qsocketnotifier.h> +#include <qapplication.h> + +struct IOCB @{ + IOCB( GpgmeIOCb f, void * d, QSocketNotifier * n ) + : func( f ), data( d ), notifier( n ) @{@} + GpgmeIOCb func; + void * data; + QSocketNotifier * notifier; +@} + +class MyApp : public QApplication @{ + + // ... + + static void registerGpgmeIOCallback( void * data, int fd, int dir, + GpgmeIOCb func, void * func_data, + void ** tag ) @{ + QSocketNotifier * n = + new QSocketNotifier( fd, dir ? QSocketNotifier::Read + : QSocketNotifier::Write ); + connect( n, SIGNAL(activated(int)), + qApp, SLOT(slotGpgmeIOCallback(int)) ); + qApp->mIOCBs.push_back( IOCB( func, func_data, n ) ); + *tag = (void*)n; + @} + + static void removeGpgmeIOCallback( void * tag ) @{ + if ( !tag ) return; + QSocketNotifier * n = static_cast<QSocketNotifier*>( tag ); + for ( QValueList<IOCB>::iterator it = qApp->mIOCBs.begin() ; + it != qApp->mIOCBs.end() ; ++it ) + if ( it->notifier == n ) @{ + delete it->notifier; + qApp->mIOCBs.erase( it ); + return; + @} + @} + +public slots: + void slotGpgmeIOCallback( int fd ) @{ + for ( QValueList<IOCB>::const_iterator it = mIOCBs.begin() ; + it != mIOCBs.end() ; ++it ) + if ( it->notifier && it->notifier->socket() == fd ) + (*(it->func)) ( it->func_data, fd ); + @} + + // ... + +private: + QValueList<IOCB> mIOCBs; + // ... +@}; +@end example + + +@node Cancellation +@subsection Cancellation +@cindex cryptographic operation, aborting +@cindex cryptographic operation, cancelling +@cindex aborting operations +@cindex cancelling operations + +Sometimes you do not want to wait for an operation to finish. +@acronym{GPGME} provides two different functions to achieve that. The +function @code{gpgme_cancel} takes effect immediately. When it +returns, the operation is effectively canceled. However, it has some +limitations and can not be used with synchronous operations. In +contrast, the function @code{gpgme_cancel_async} can be used with any +context and from any thread, but it is not guaranteed to take effect +immediately. Instead, cancellation occurs at the next possible time +(typically the next time I/O occurs in the target context). + +@deftypefun gpgme_ctx_t gpgme_cancel (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_cancel} attempts to cancel a pending +operation in the context @var{ctx}. This only works if you use the +global event loop or your own event loop. + +If you use the global event loop, you must not call @code{gpgme_wait} +or @code{gpgme_wait} during cancellation. After successful +cancellation, you can call @code{gpgme_wait} (optionally waiting on +@var{ctx}), and the context @var{ctx} will appear as if it had +finished with the error code @code{GPG_ERR_CANCEL}. + +If you use your an external event loop, you must ensure that no I/O +callbacks are invoked for this context (for example by halting the +event loop). On successful cancellation, all registered I/O callbacks +for this context will be unregistered, and a @code{GPGME_EVENT_DONE} +event with the error code @code{GPG_ERR_CANCEL} will be signaled. + +The function returns an error code if the cancellation failed (in this +case the state of @var{ctx} is not modified). +@end deftypefun + + +@deftypefun gpgme_ctx_t gpgme_cancel_async (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_cancel} attempts to cancel a pending +operation in the context @var{ctx}. This can be called by any thread +at any time after starting an operation on the context, but will not +take effect immediately. The actual cancellation happens at the next +time GPGME processes I/O in that context. + +The function returns an error code if the cancellation failed (in this +case the state of @var{ctx} is not modified). +@end deftypefun + +@c ********************************************************** +@c ******************* Appendices ************************* +@c ********************************************************** + +@include uiserver.texi + +@include lesser.texi + +@include gpl.texi + +@node Function and Data Index +@unnumbered Function and Data Index + +@printindex fn + +@node Concept Index +@unnumbered Concept Index + +@printindex cp + + +@bye diff --git a/doc/gpl.texi b/doc/gpl.texi new file mode 100644 index 0000000..1b29a81 --- /dev/null +++ b/doc/gpl.texi @@ -0,0 +1,724 @@ +@node Copying +@unnumbered GNU General Public License +@center Version 3, 29 June 2007 + +@c This file is intended to be included in another file. + +@display +Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. +@end display + +@section Preamble + +The GNU General Public License is a free, copyleft license for +software and other kinds of works. + +The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom +to share and change all versions of a program--to make sure it remains +free software for all its users. We, the Free Software Foundation, +use the GNU General Public License for most of our software; it +applies also to any other work released this way by its authors. You +can apply it to your programs, too. + +When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + +To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you +have certain responsibilities if you distribute copies of the +software, or if you modify it: responsibilities to respect the freedom +of others. + +For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, +receive or can get the source code. And you must show them these +terms so they know their rights. + +Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + +For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + +Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the +manufacturer can do so. This is fundamentally incompatible with the +aim of protecting users' freedom to change the software. The +systematic pattern of such abuse occurs in the area of products for +individuals to use, which is precisely where it is most unacceptable. +Therefore, we have designed this version of the GPL to prohibit the +practice for those products. If such problems arise substantially in +other domains, we stand ready to extend this provision to those +domains in future versions of the GPL, as needed to protect the +freedom of users. + +Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish +to avoid the special danger that patents applied to a free program +could make it effectively proprietary. To prevent this, the GPL +assures that patents cannot be used to render the program non-free. + +The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@section TERMS AND CONDITIONS +@end iftex +@ifinfo +@center TERMS AND CONDITIONS +@end ifinfo + +@enumerate 0 +@item Definitions. + +``This License'' refers to version 3 of the GNU General Public License. + +``Copyright'' also means copyright-like laws that apply to other kinds +of works, such as semiconductor masks. + +``The Program'' refers to any copyrightable work licensed under this +License. Each licensee is addressed as ``you''. ``Licensees'' and +``recipients'' may be individuals or organizations. + +To ``modify'' a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of +an exact copy. The resulting work is called a ``modified version'' of +the earlier work or a work ``based on'' the earlier work. + +A ``covered work'' means either the unmodified Program or a work based +on the Program. + +To ``propagate'' a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + +To ``convey'' a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user +through a computer network, with no transfer of a copy, is not +conveying. + +An interactive user interface displays ``Appropriate Legal Notices'' to +the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + +@item Source Code. + +The ``source code'' for a work means the preferred form of the work for +making modifications to it. ``Object code'' means any non-source form +of a work. + +A ``Standard Interface'' means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + +The ``System Libraries'' of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +``Major Component'', in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + +The ``Corresponding Source'' for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + +The Corresponding Source need not include anything that users can +regenerate automatically from other parts of the Corresponding Source. + +The Corresponding Source for a work in source code form is that same +work. + +@item Basic Permissions. + +All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + +You may make, run and propagate covered works that you do not convey, +without conditions so long as your license otherwise remains in force. +You may convey covered works to others for the sole purpose of having +them make modifications exclusively for you, or provide you with +facilities for running those works, provided that you comply with the +terms of this License in conveying all material for which you do not +control copyright. Those thus making or running the covered works for +you must do so exclusively on your behalf, under your direction and +control, on terms that prohibit them from making any copies of your +copyrighted material outside their relationship with you. + +Conveying under any other circumstances is permitted solely under the +conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + +@item Protecting Users' Legal Rights From Anti-Circumvention Law. + +No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + +When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such +circumvention is effected by exercising rights under this License with +respect to the covered work, and you disclaim any intention to limit +operation or modification of the work as a means of enforcing, against +the work's users, your or third parties' legal rights to forbid +circumvention of technological measures. + +@item Conveying Verbatim Copies. + +You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + +You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + +@item Conveying Modified Source Versions. + +You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these +conditions: + +@enumerate a +@item +The work must carry prominent notices stating that you modified it, +and giving a relevant date. + +@item +The work must carry prominent notices stating that it is released +under this License and any conditions added under section 7. This +requirement modifies the requirement in section 4 to ``keep intact all +notices''. + +@item +You must license the entire work, as a whole, under this License to +anyone who comes into possession of a copy. This License will +therefore apply, along with any applicable section 7 additional terms, +to the whole of the work, and all its parts, regardless of how they +are packaged. This License gives no permission to license the work in +any other way, but it does not invalidate such permission if you have +separately received it. + +@item +If the work has interactive user interfaces, each must display +Appropriate Legal Notices; however, if the Program has interactive +interfaces that do not display Appropriate Legal Notices, your work +need not make them do so. +@end enumerate + +A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +``aggregate'' if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + +@item Conveying Non-Source Forms. + +You may convey a covered work in object code form under the terms of +sections 4 and 5, provided that you also convey the machine-readable +Corresponding Source under the terms of this License, in one of these +ways: + +@enumerate a +@item +Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by the +Corresponding Source fixed on a durable physical medium customarily +used for software interchange. + +@item +Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by a written +offer, valid for at least three years and valid for as long as you +offer spare parts or customer support for that product model, to give +anyone who possesses the object code either (1) a copy of the +Corresponding Source for all the software in the product that is +covered by this License, on a durable physical medium customarily used +for software interchange, for a price no more than your reasonable +cost of physically performing this conveying of source, or (2) access +to copy the Corresponding Source from a network server at no charge. + +@item +Convey individual copies of the object code with a copy of the written +offer to provide the Corresponding Source. This alternative is +allowed only occasionally and noncommercially, and only if you +received the object code with such an offer, in accord with subsection +6b. + +@item +Convey the object code by offering access from a designated place +(gratis or for a charge), and offer equivalent access to the +Corresponding Source in the same way through the same place at no +further charge. You need not require recipients to copy the +Corresponding Source along with the object code. If the place to copy +the object code is a network server, the Corresponding Source may be +on a different server (operated by you or a third party) that supports +equivalent copying facilities, provided you maintain clear directions +next to the object code saying where to find the Corresponding Source. +Regardless of what server hosts the Corresponding Source, you remain +obligated to ensure that it is available for as long as needed to +satisfy these requirements. + +@item +Convey the object code using peer-to-peer transmission, provided you +inform other peers where the object code and Corresponding Source of +the work are being offered to the general public at no charge under +subsection 6d. + +@end enumerate + +A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + +A ``User Product'' is either (1) a ``consumer product'', which means any +tangible personal property which is normally used for personal, +family, or household purposes, or (2) anything designed or sold for +incorporation into a dwelling. In determining whether a product is a +consumer product, doubtful cases shall be resolved in favor of +coverage. For a particular product received by a particular user, +``normally used'' refers to a typical or common use of that class of +product, regardless of the status of the particular user or of the way +in which the particular user actually uses, or expects or is expected +to use, the product. A product is a consumer product regardless of +whether the product has substantial commercial, industrial or +non-consumer uses, unless such uses represent the only significant +mode of use of the product. + +``Installation Information'' for a User Product means any methods, +procedures, authorization keys, or other information required to +install and execute modified versions of a covered work in that User +Product from a modified version of its Corresponding Source. The +information must suffice to ensure that the continued functioning of +the modified object code is in no case prevented or interfered with +solely because modification has been made. + +If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + +The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or +updates for a work that has been modified or installed by the +recipient, or for the User Product in which it has been modified or +installed. Access to a network may be denied when the modification +itself materially and adversely affects the operation of the network +or violates the rules and protocols for communication across the +network. + +Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + +@item Additional Terms. + +``Additional permissions'' are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + +When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + +Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders +of that material) supplement the terms of this License with terms: + +@enumerate a +@item +Disclaiming warranty or limiting liability differently from the terms +of sections 15 and 16 of this License; or + +@item +Requiring preservation of specified reasonable legal notices or author +attributions in that material or in the Appropriate Legal Notices +displayed by works containing it; or + +@item +Prohibiting misrepresentation of the origin of that material, or +requiring that modified versions of such material be marked in +reasonable ways as different from the original version; or + +@item +Limiting the use for publicity purposes of names of licensors or +authors of the material; or + +@item +Declining to grant rights under trademark law for use of some trade +names, trademarks, or service marks; or + +@item +Requiring indemnification of licensors and authors of that material by +anyone who conveys the material (or modified versions of it) with +contractual assumptions of liability to the recipient, for any +liability that these contractual assumptions directly impose on those +licensors and authors. +@end enumerate + +All other non-permissive additional terms are considered ``further +restrictions'' within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + +If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + +Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; the +above requirements apply either way. + +@item Termination. + +You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + +@item Acceptance Not Required for Having Copies. + +You are not required to accept this License in order to receive or run +a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + +@item Automatic Licensing of Downstream Recipients. + +Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + +An ``entity transaction'' is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + +You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + +@item Patents. + +A ``contributor'' is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's ``contributor version''. + +A contributor's ``essential patent claims'' are all patent claims owned +or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, ``control'' includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + +Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + +In the following three paragraphs, a ``patent license'' is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To ``grant'' such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + +If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. ``Knowingly relying'' means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + +If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + +A patent license is ``discriminatory'' if it does not include within the +scope of its coverage, prohibits the exercise of, or is conditioned on +the non-exercise of one or more of the rights that are specifically +granted under this License. You may not convey a covered work if you +are a party to an arrangement with a third party that is in the +business of distributing software, under which you make payment to the +third party based on the extent of your activity of conveying the +work, and under which the third party grants, to any of the parties +who would receive the covered work from you, a discriminatory patent +license (a) in connection with copies of the covered work conveyed by +you (or copies made from those copies), or (b) primarily for and in +connection with specific products or compilations that contain the +covered work, unless you entered into that arrangement, or that patent +license was granted, prior to 28 March 2007. + +Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + +@item No Surrender of Others' Freedom. + +If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey +a covered work so as to satisfy simultaneously your obligations under +this License and any other pertinent obligations, then as a +consequence you may not convey it at all. For example, if you agree +to terms that obligate you to collect a royalty for further conveying +from those to whom you convey the Program, the only way you could +satisfy both those terms and this License would be to refrain entirely +from conveying the Program. + +@item Use with the GNU Affero General Public License. + +Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + +@item Revised Versions of this License. + +The Free Software Foundation may publish revised and/or new versions +of the GNU General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies that a certain numbered version of the GNU General Public +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that numbered version or +of any later version published by the Free Software Foundation. If +the Program does not specify a version number of the GNU General +Public License, you may choose any version ever published by the Free +Software Foundation. + +If the Program specifies that a proxy can decide which future versions +of the GNU General Public License can be used, that proxy's public +statement of acceptance of a version permanently authorizes you to +choose that version for the Program. + +Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + +@item Disclaimer of Warranty. + +THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT +WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND +PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE +DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR +CORRECTION. + +@item Limitation of Liability. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR +CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT +NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR +LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM +TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER +PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +@item Interpretation of Sections 15 and 16. + +If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo +@section How to Apply These Terms to Your New Programs + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + +To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) @var{year} @var{name of author} + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or (at +your option) any later version. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see @url{http://www.gnu.org/licenses/}. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + +@smallexample +@var{program} Copyright (C) @var{year} @var{name of author} +This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. +This is free software, and you are welcome to redistribute it under certain conditions; type @samp{show c} for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an ``about box''. + +You should also get your employer (if you work as a programmer) or school, +if any, to sign a ``copyright disclaimer'' for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +@url{http://www.gnu.org/licenses/}. + +The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use +the GNU Lesser General Public License instead of this License. But +first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. + +@end enumerate diff --git a/doc/lesser.texi b/doc/lesser.texi new file mode 100644 index 0000000..f23f0fd --- /dev/null +++ b/doc/lesser.texi @@ -0,0 +1,565 @@ +@node Library Copying +@unnumbered GNU Lesser General Public License + +@cindex LGPL, Lesser General Public License +@center Version 2.1, February 1999 + +@display +Copyright @copyright{} 1991, 1999 Free Software Foundation, Inc. +59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. + +[This is the first released version of the Lesser GPL. It also counts +as the successor of the GNU Library Public License, version 2, hence the +version number 2.1.] +@end display + +@section Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software---to make sure the software is free for all its users. + + This license, the Lesser General Public License, applies to some +specially designated software---typically libraries---of the Free +Software Foundation and other authors who decide to use it. You can use +it too, but we suggest you first think carefully about whether this +license or the ordinary General Public License is the better strategy to +use in any particular case, based on the explanations below. + + When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of it +in new free programs; and that you are informed that you can do these +things. + + To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + + For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know +that what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and +is quite different from the ordinary General Public License. We use +this license for certain libraries in order to permit linking those +libraries into non-free programs. + + When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + We call this license the @dfn{Lesser} General Public License because it +does @emph{Less} to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it becomes +a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of +free software. For example, permission to use the GNU C Library in +non-free programs enables many more people to use the whole GNU +operating system, as well as its variant, the GNU/Linux operating +system. + + Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run +that program using a modified version of the Library. + + The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +``work based on the library'' and a ``work that uses the library''. The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + +@iftex +@section TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center GNU LESSER GENERAL PUBLIC LICENSE +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 +@item +This License Agreement applies to any software library or other program +which contains a notice placed by the copyright holder or other +authorized party saying it may be distributed under the terms of this +Lesser General Public License (also called ``this License''). Each +licensee is addressed as ``you''. + + A ``library'' means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. + + The ``Library'', below, refers to any such software library or work +which has been distributed under these terms. A ``work based on the +Library'' means either the Library or any derivative work under +copyright law: that is to say, a work containing the Library or a +portion of it, either verbatim or with modifications and/or translated +straightforwardly into another language. (Hereinafter, translation is +included without limitation in the term ``modification''.) + + ``Source code'' for a work means the preferred form of the work for +making modifications to it. For a library, complete source code means +all the source code for all modules it contains, plus any associated +interface definition files, plus the scripts used to control compilation +and installation of the library. + + Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running a program using the Library is not restricted, and output from +such a program is covered only if its contents constitute a work based +on the Library (independent of the use of the Library in a tool for +writing it). Whether that is true depends on what the Library does +and what the program that uses the Library does. + +@item +You may copy and distribute verbatim copies of the Library's +complete source code as you receive it, in any medium, provided that +you conspicuously and appropriately publish on each copy an +appropriate copyright notice and disclaimer of warranty; keep intact +all the notices that refer to this License and to the absence of any +warranty; and distribute a copy of this License along with the +Library. + + You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee. + +@item +You may modify your copy or copies of the Library or any portion +of it, thus forming a work based on the Library, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +The modified work must itself be a software library. + +@item +You must cause the files modified to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause the whole of the work to be licensed at no +charge to all third parties under the terms of this License. + +@item +If a facility in the modified Library refers to a function or a +table of data to be supplied by an application program that uses +the facility, other than as an argument passed when the facility +is invoked, then you must make a good faith effort to ensure that, +in the event an application does not supply such function or +table, the facility still operates, and performs whatever part of +its purpose remains meaningful. + +(For example, a function in a library to compute square roots has +a purpose that is entirely well-defined independent of the +application. Therefore, Subsection 2d requires that any +application-supplied function or table used by this function must +be optional: if the application does not supply it, the square +root function must still compute square roots.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Library, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. + +In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so +that they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + + Once this change is made in a given copy, it is irreversible for +that copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of +the Library into a program that is not a library. + +@item +You may copy and distribute the Library (or a portion or +derivative of it, under Section 2) in object code or executable form +under the terms of Sections 1 and 2 above provided that you accompany +it with the complete corresponding machine-readable source code, which +must be distributed under the terms of Sections 1 and 2 above on a +medium customarily used for software interchange. + + If distribution of object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the +source code from the same place satisfies the requirement to +distribute the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +A program that contains no derivative of any portion of the +Library, but is designed to work with the Library by being compiled or +linked with it, is called a ``work that uses the Library''. Such a +work, in isolation, is not a derivative work of the Library, and +therefore falls outside the scope of this License. + + However, linking a ``work that uses the Library'' with the Library +creates an executable that is a derivative of the Library (because it +contains portions of the Library), rather than a ``work that uses the +library''. The executable is therefore covered by this License. +Section 6 states terms for distribution of such executables. + + When a ``work that uses the Library'' uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be +linked without the Library, or if the work is itself a library. The +threshold for this to be true is not precisely defined by law. + + If such an object file uses only numerical parameters, data +structure layouts and accessors, and small macros and small inline +functions (ten lines or less in length), then the use of the object +file is unrestricted, regardless of whether it is legally a derivative +work. (Executables containing this object code plus portions of the +Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, +whether or not they are linked directly with the Library itself. + +@item +As an exception to the Sections above, you may also combine or +link a ``work that uses the Library'' with the Library to produce a +work containing portions of the Library, and distribute that work +under terms of your choice, provided that the terms permit +modification of the work for the customer's own use and reverse +engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: + +@enumerate a +@item +Accompany the work with the complete corresponding +machine-readable source code for the Library including whatever +changes were used in the work (which must be distributed under +Sections 1 and 2 above); and, if the work is an executable linked +with the Library, with the complete machine-readable ``work that +uses the Library'', as object code and/or source code, so that the +user can modify the Library and then relink to produce a modified +executable containing the modified Library. (It is understood +that the user who changes the contents of definitions files in the +Library will not necessarily be able to recompile the application +to use the modified definitions.) + +@item +Use a suitable shared library mechanism for linking with the Library. A +suitable mechanism is one that (1) uses at run time a copy of the +library already present on the user's computer system, rather than +copying library functions into the executable, and (2) will operate +properly with a modified version of the library, if the user installs +one, as long as the modified version is interface-compatible with the +version that the work was made with. + +@item +Accompany the work with a written offer, valid for at +least three years, to give the same user the materials +specified in Subsection 6a, above, for a charge no more +than the cost of performing this distribution. + +@item +If distribution of the work is made by offering access to copy +from a designated place, offer equivalent access to copy the above +specified materials from the same place. + +@item +Verify that the user has already received a copy of these +materials or that you have already sent this user a copy. +@end enumerate + + For an executable, the required form of the ``work that uses the +Library'' must include any data and utility programs needed for +reproducing the executable from it. However, as a special exception, +the materials to be distributed need not include anything that is +normally distributed (in either source or binary form) with the major +components (compiler, kernel, and so on) of the operating system on +which the executable runs, unless that component itself accompanies the +executable. + + It may happen that this requirement contradicts the license +restrictions of other proprietary libraries that do not normally +accompany the operating system. Such a contradiction means you cannot +use both them and the Library together in an executable that you +distribute. + +@item +You may place library facilities that are a work based on the +Library side-by-side in a single library together with other library +facilities not covered by this License, and distribute such a combined +library, provided that the separate distribution of the work based on +the Library and of the other library facilities is otherwise +permitted, and provided that you do these two things: + +@enumerate a +@item +Accompany the combined library with a copy of the same work +based on the Library, uncombined with any other library +facilities. This must be distributed under the terms of the +Sections above. + +@item +Give prominent notice with the combined library of the fact +that part of it is a work based on the Library, and explaining +where to find the accompanying uncombined form of the same work. +@end enumerate + +@item +You may not copy, modify, sublicense, link with, or distribute +the Library except as expressly provided under this License. Any +attempt otherwise to copy, modify, sublicense, link with, or +distribute the Library is void, and will automatically terminate your +rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses +terminated so long as such parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Library or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Library (or any work based on the +Library), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Library or works based on it. + +@item +Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties with +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent +license would not permit royalty-free redistribution of the Library by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Library. + +If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply, +and the section as a whole is intended to apply in other circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Library is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Library under this License may add +an explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new +versions of the Lesser General Public License from time to time. +Such new versions will be similar in spirit to the present version, +but may differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and +``any later version'', you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a +license version number, you may choose any version ever published by +the Free Software Foundation. + +@item +If you wish to incorporate parts of the Library into other free +programs whose distribution conditions are incompatible with these, +write to the author to ask for permission. For software which is +copyrighted by the Free Software Foundation, write to the Free +Software Foundation; we sometimes make exceptions for this. Our +decision will be guided by the two goals of preserving the free status +of all derivatives of our free software and of promoting the sharing +and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@section How to Apply These Terms to Your New Libraries + + If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of the +ordinary General Public License). + + To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least the +``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the library's name and an idea of what it does.} +Copyright (C) @var{year} @var{name of author} + +This library is free software; you can redistribute it and/or modify it +under the terms of the GNU Lesser General Public License as published by +the Free Software Foundation; either version 2.1 of the License, or (at +your option) any later version. + +This library is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, +USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the library, if +necessary. Here is a sample; alter the names: + +@smallexample +Yoyodyne, Inc., hereby disclaims all copyright interest in the library +`Frob' (a library for tweaking knobs) written by James Random Hacker. + +@var{signature of Ty Coon}, 1 April 1990 +Ty Coon, President of Vice +@end smallexample + +That's all there is to it! diff --git a/doc/mdate-sh b/doc/mdate-sh new file mode 100755 index 0000000..83d2700 --- /dev/null +++ b/doc/mdate-sh @@ -0,0 +1,205 @@ +#!/bin/sh +# Get modification time of a file or directory and pretty-print it. + +scriptversion=2007-03-30.02 + +# Copyright (C) 1995, 1996, 1997, 2003, 2004, 2005, 2007 Free Software +# Foundation, Inc. +# written by Ulrich Drepper <drepper@gnu.ai.mit.edu>, June 1995 +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software Foundation, +# Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +# As a special exception to the GNU General Public License, if you +# distribute this file as part of a program that contains a +# configuration script generated by Autoconf, you may include it under +# the same distribution terms that you use for the rest of that program. + +# This file is maintained in Automake, please report +# bugs to <bug-automake@gnu.org> or send patches to +# <automake-patches@gnu.org>. + +case $1 in + '') + echo "$0: No file. Try \`$0 --help' for more information." 1>&2 + exit 1; + ;; + -h | --h*) + cat <<\EOF +Usage: mdate-sh [--help] [--version] FILE + +Pretty-print the modification time of FILE. + +Report bugs to <bug-automake@gnu.org>. +EOF + exit $? + ;; + -v | --v*) + echo "mdate-sh $scriptversion" + exit $? + ;; +esac + +# Prevent date giving response in another language. +LANG=C +export LANG +LC_ALL=C +export LC_ALL +LC_TIME=C +export LC_TIME + +# GNU ls changes its time format in response to the TIME_STYLE +# variable. Since we cannot assume `unset' works, revert this +# variable to its documented default. +if test "${TIME_STYLE+set}" = set; then + TIME_STYLE=posix-long-iso + export TIME_STYLE +fi + +save_arg1=$1 + +# Find out how to get the extended ls output of a file or directory. +if ls -L /dev/null 1>/dev/null 2>&1; then + ls_command='ls -L -l -d' +else + ls_command='ls -l -d' +fi +# Avoid user/group names that might have spaces, when possible. +if ls -n /dev/null 1>/dev/null 2>&1; then + ls_command="$ls_command -n" +fi + +# A `ls -l' line looks as follows on OS/2. +# drwxrwx--- 0 Aug 11 2001 foo +# This differs from Unix, which adds ownership information. +# drwxrwx--- 2 root root 4096 Aug 11 2001 foo +# +# To find the date, we split the line on spaces and iterate on words +# until we find a month. This cannot work with files whose owner is a +# user named `Jan', or `Feb', etc. However, it's unlikely that `/' +# will be owned by a user whose name is a month. So we first look at +# the extended ls output of the root directory to decide how many +# words should be skipped to get the date. + +# On HPUX /bin/sh, "set" interprets "-rw-r--r--" as options, so the "x" below. +set x`$ls_command /` + +# Find which argument is the month. +month= +command= +until test $month +do + shift + # Add another shift to the command. + command="$command shift;" + case $1 in + Jan) month=January; nummonth=1;; + Feb) month=February; nummonth=2;; + Mar) month=March; nummonth=3;; + Apr) month=April; nummonth=4;; + May) month=May; nummonth=5;; + Jun) month=June; nummonth=6;; + Jul) month=July; nummonth=7;; + Aug) month=August; nummonth=8;; + Sep) month=September; nummonth=9;; + Oct) month=October; nummonth=10;; + Nov) month=November; nummonth=11;; + Dec) month=December; nummonth=12;; + esac +done + +# Get the extended ls output of the file or directory. +set dummy x`eval "$ls_command \"\$save_arg1\""` + +# Remove all preceding arguments +eval $command + +# Because of the dummy argument above, month is in $2. +# +# On a POSIX system, we should have +# +# $# = 5 +# $1 = file size +# $2 = month +# $3 = day +# $4 = year or time +# $5 = filename +# +# On Darwin 7.7.0 and 7.6.0, we have +# +# $# = 4 +# $1 = day +# $2 = month +# $3 = year or time +# $4 = filename + +# Get the month. +case $2 in + Jan) month=January; nummonth=1;; + Feb) month=February; nummonth=2;; + Mar) month=March; nummonth=3;; + Apr) month=April; nummonth=4;; + May) month=May; nummonth=5;; + Jun) month=June; nummonth=6;; + Jul) month=July; nummonth=7;; + Aug) month=August; nummonth=8;; + Sep) month=September; nummonth=9;; + Oct) month=October; nummonth=10;; + Nov) month=November; nummonth=11;; + Dec) month=December; nummonth=12;; +esac + +case $3 in + ???*) day=$1;; + *) day=$3; shift;; +esac + +# Here we have to deal with the problem that the ls output gives either +# the time of day or the year. +case $3 in + *:*) set `date`; eval year=\$$# + case $2 in + Jan) nummonthtod=1;; + Feb) nummonthtod=2;; + Mar) nummonthtod=3;; + Apr) nummonthtod=4;; + May) nummonthtod=5;; + Jun) nummonthtod=6;; + Jul) nummonthtod=7;; + Aug) nummonthtod=8;; + Sep) nummonthtod=9;; + Oct) nummonthtod=10;; + Nov) nummonthtod=11;; + Dec) nummonthtod=12;; + esac + # For the first six month of the year the time notation can also + # be used for files modified in the last year. + if (expr $nummonth \> $nummonthtod) > /dev/null; + then + year=`expr $year - 1` + fi;; + *) year=$3;; +esac + +# The result. +echo $day $month $year + +# Local Variables: +# mode: shell-script +# sh-indentation: 2 +# eval: (add-hook 'write-file-hooks 'time-stamp) +# time-stamp-start: "scriptversion=" +# time-stamp-format: "%:y-%02m-%02d.%02H" +# time-stamp-end: "$" +# End: diff --git a/doc/module-overview.sk b/doc/module-overview.sk new file mode 100644 index 0000000..5b3af15 --- /dev/null +++ b/doc/module-overview.sk @@ -0,0 +1,640 @@ +##Sketch 1 2 +document() +layout('A4',1) +fp((0,0,0)) +ft(1) +Fn('Helvetica-Bold') +Fs(18) +dstyle('Text') +fp((0,1,0.498)) +ft(1) +lp((0,0,0)) +lw(0.283465) +lc(1) +lj(0) +ld(()) +la1() +la2() +dstyle('Application Box') +layer('Layer 1',1,1,0,0,(0,0,0)) +lw(1) +r(0,0,0,0,688.145,44.1554) +lw(1) +r(0,0,0,0,682.363,85.0359) +lp((0.392,0.584,0.929)) +lw(4.25197) +b() +bs(605.383,329.758,0) +bs(605.383,230.546,0) +lw(1) +r(0,0,0,0,807.414,53.6148) +lp((0.392,0.584,0.929)) +lw(4.25) +b() +bs(480.134,240.945,0) +bs(480.358,325.277,0) +lp((0.392,0.584,0.929)) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(474.803,432.284,0) +bs(475.334,360.243,0) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(354.331,432.284,0) +bs(352.806,361.417,0) +lp((0.392,0.584,0.929)) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(212.598,432.284,0) +bs(212.598,361.417,0) +fp((0.999,1,0.4)) +lw(0.283465) +r(70.5968,0,0,-56.6929,191.608,488.976,0.0603744,0.151107) +lw(1) +r(0,0,0,0,88.5492,390.805) +lp((0.392,0.584,0.929)) +lw(4.25197) +b() +bs(226.772,524.409,0) +bs(226.772,488.976,0) +lp((0.392,0.584,0.929)) +lw(4.25) +b() +bs(403.937,528.718,0) +bs(403.937,488.976,0) +lp((0.392,0.584,0.929)) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(240.945,432.284,0) +bs(240.574,394.994,0) +bs(595.276,396.85,0) +bs(595.276,361.417,0) +lp((0.392,0.584,0.929)) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(333.071,432.284,0) +bs(333.07,425.196,0) +bs(333.07,382.677,0) +bs(240.945,382.677,0) +bs(240.945,361.417,0) +G() +fp((0.999,1,0.4)) +lw(0.283465) +r(70.5589,0,0,-28.347,318.897,354.331,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica-Bold') +Fs(10) +txt('GPG',(1,0,0,0.905764,344.004,335.686)) +G_() +G() +fp((0.999,1,0.4)) +lw(0.283465) +r(70.5589,0,0,-28.3464,446.763,354.33,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('GpgConf',(0.552654,0,0,0.500564,481.802,340.184),1,1) +G_() +G() +fp((0.999,1,0.4)) +lw(0.283465) +r(70.5589,0,0,-28.347,191.338,354.331,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('GpgSM',(0.552654,0,0,0.500574,226.376,340.185),1,1) +G_() +lp((0.392,0.584,0.929)) +lw(4.25) +b() +bs(347.244,325.984,0) +bs(347.244,325.984,0) +bs(347.244,255.118,0) +bs(304.724,255.118,0) +bs(304.724,226.771,0) +lp((0.392,0.584,0.929)) +lw(4.25) +b() +bs(233.858,325.984,0) +bs(233.858,255.118,0) +bs(276.378,255.118,0) +bs(276.378,226.771,0) +fp((0,0,0)) +le() +lw(1) +Fn('Palatino-Roman') +txt('2008-07-17',(0.608301,0,0,0.608301,708.661,65.8308)) +lw(1) +r(0,0,0,0,750.427,153.265) +lp((0.392,0.584,0.929)) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(219.685,325.984,0) +bs(219.685,198.425,0) +bs(219.685,162.992,0) +G() +fp((1,1,1)) +lw(0.283465) +r(113.386,0,0,-42.5196,35.4333,162.992,0.0670228,0.151107) +fp((0,0,0)) +lw(0.283465) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(18) +txt('LDAP Server',(0.552654,0,0,0.552654,92.1261,148.819),1,1) +fp((0,0,0)) +lw(0.283465) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(18) +txt('(CRLs, Certificates)',(0.552654,0,0,0.552654,92.1261,134.646),1,1) +G_() +G() +fp((1,1,1)) +lw(0.283465) +r(113.386,0,0,-42.5196,35.4331,99.2125,0.0670228,0.151107) +fp((0,0,0)) +lw(0.283465) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(18) +txt('HTTP Server',(0.552654,0,0,0.552654,92.1259,85.0394),1,1) +fp((0,0,0)) +lw(0.283465) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(18) +txt('(CRLs)',(0.552654,0,0,0.552654,92.1259,70.8662),1,1) +G_() +G() +fp((0.999,1,0.4)) +lw(0.283465) +r(70.866,0,0,-31.2962,191.338,158.855,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('DirMngr',(0.552654,0,0,0.552654,224.02,142.978),1,1) +G_() +lw(2) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(219.15,126.18,0) +bs(219.685,77.9528,0) +bs(155.906,77.9528,0) +lp((0.392,0.584,0.929)) +lw(3) +b() +bs(233.858,127.559,0) +bs(233.858,99.2125,0) +bs(276.378,99.2125,0) +bs(276.378,85.0393,0) +lp((0.392,0.584,0.929)) +lw(3) +b() +bs(248.031,127.559,0) +bs(248.031,113.386,0) +bs(375.59,113.386,0) +bs(375.59,85.0393,0) +G() +fp((1,0.647,0.31)) +lw(0.283465) +r(99.2124,0,0,-28.3464,333.07,85.0393,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(18) +txt('Certificate Cache',(0.552654,0,0,0.552654,382.606,69.8548),1,1) +fp((1,0.647,0.31)) +lw(0.283465) +r(70.5589,0,0,-28.3464,248.031,85.0393,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('CRL Cache',(0.552654,0,0,0.552654,284.147,70.6936),1,1) +G_() +lw(1) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(503.149,240.945,0) +bs(503.149,283.464,0) +bs(588.189,283.465,0) +bs(588.189,325.984,0) +lw(1) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(503.149,283.464,0) +bs(503.149,283.464,0) +bs(361.417,283.464,0) +bs(361.417,325.984,0) +lw(1) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(361.417,283.464,0) +bs(205.512,283.465,0) +bs(205.512,325.984,0) +lw(1) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(574.015,85.0393,0) +bs(574.015,141.732,0) +bs(262.204,141.732,0) +lw(1) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(602.361,85.0393,0) +bs(602.361,170.079,0) +bs(439.37,170.079,0) +bs(439.37,311.811,0) +bs(460.629,311.811,0) +bs(460.629,325.984,0) +lw(1) +ld((5, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(389.763,240.945,0) +bs(389.763,269.291,0) +bs(290.551,269.291,0) +bs(290.551,340.157,0) +bs(262.204,340.157,0) +lw(1) +ld((5, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(389.763,269.291,0) +bs(559.843,269.291,0) +bs(559.843,333.071,0) +bs(574.016,333.071,0) +lw(1) +ld((5, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(488.976,85.0393,0) +bs(488.976,127.559,0) +bs(389.763,127.559,0) +bs(389.763,212.598,0) +lw(2) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(205.512,127.559,0) +bs(205.512,113.386,0) +bs(170.079,113.386,0) +bs(170.079,141.732,0) +bs(155.906,141.732,0) +lp((0.392,0.584,0.929)) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(622.961,356.76,0) +bs(622.961,518.503,0) +G() +fp((0.999,1,0.4)) +lw(0.283465) +r(70.5589,0,0,-28.3459,573.199,354.33,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('GpgAgent',(0.552654,0,0,0.500554,608.238,340.185),1,1) +G_() +lp((0.392,0.584,0.929)) +lw(4.25) +b() +bs(721.712,467.717,0) +bs(721.712,297.838,0) +G() +fp((0.999,1,0.4)) +lw(0.283465) +r(70.5589,0,0,-28.3464,686.278,297.637,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('SCdaemon',(0.552654,0,0,0.500564,721.316,283.492),1,1) +G_() +fp((1,0.647,0.31)) +lw(0.283465) +lj(1) +r(86.162,0,0,-117.493,679.192,566.929,0.181818,0.333333) +G() +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica-Bold') +Fs(18) +txt('Smartcard',(0.552654,0,0,0.552654,698.127,491.036)) +fp((0.999,1,0.4)) +lw(0.283465) +r(70.5589,0,0,-31.2962,686.279,557.593,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('Card Reader',(0.552654,0,0,0.552654,721.318,541.975),1,1) +G_() +G() +fp((0.999,1,0.4)) +lw(0.283465) +r(73.6353,0,0,-41.2944,587.066,565.703,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('PIN Entry',(0.57675,0,0,0.729211,623.632,545.097),1,1) +G_() +lp((0.392,0.584,0.929)) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(643.758,340.157,0) +bs(643.758,340.157,0) +bs(707.539,340.158,0) +bs(707.539,304.724,0) +lw(1) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(574.016,283.465,0) +bs(587.066,283.464,0) +bs(686.278,283.464,0) +G() +lp((0.392,0.584,0.929)) +lw(4.25197) +b() +bs(98.9053,325.985,0) +bs(98.9053,240.945,0) +G() +fp((0.999,1,0.4)) +lw(0.283465) +r(70.5589,0,0,-28.3464,63.7795,354.331,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('WatchGnuPG',(0.552654,0,0,0.552654,98.8185,338.713),1,1) +G_() +G() +fp((1,0.647,0.31)) +lw(0.283465) +r(70.5589,0,0,-28.1194,63.7795,240.718,0.0670228,0.168178) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('Log Socket',(0.552654,0,0,0.552654,98.8175,225.1),1,1) +G_() +G_() +G() +fp((1,0.647,0.31)) +lw(0.283465) +r(85.0392,0,0,-28.3464,446.457,240.945,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(18) +txt('Config Files',(0.552654,0,0,0.552654,485.621,226.772),1,1) +G_() +G() +fp((1,0.647,0.31)) +lw(0.283465) +r(85.0392,0,0,-28.3464,545.669,85.0394,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(18) +txt('Config Files',(0.552654,0,0,0.552654,584.834,70.8662),1,1) +G_() +G() +fp((1,0.647,0.31)) +lw(0.283465) +r(84.6546,0,0,-27.3609,347.245,239.959,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(18) +txt('Help Files',(0.552654,0,0,0.552654,388.252,224.705),1,1) +G_() +G() +fp((1,0.647,0.31)) +lw(0.283465) +r(84.6546,0,0,-27.3609,446.457,85.0394,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(18) +txt('Help Files',(0.552654,0,0,0.552654,487.464,69.7854),1,1) +G_() +G() +fp((1,0.647,0.31)) +lw(0.283465) +r(85.0392,0,0,-28.3464,248.032,240.945,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(18) +txt('Keybox Files',(0.552654,0,0,0.552654,289.59,226.322),1,1) +G_() +G() +fp((1,0.647,0.31)) +lw(0.283465) +r(70.866,0,0,-28.3464,574.016,240.945,0.0670228,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(18) +txt('Private Keys',(0.552654,0,0,0.552654,609.449,226.772),1,1) +G_() +G() +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(24) +txt('Scute',(0.552654,0,0,0.599958,224.978,465.775),1,1) +fp((0,0,0)) +le() +lw(1) +Fn('Times-Roman') +Fs(10) +txt('(pkcs#11)',(1,0,0,1.08559,206.081,445.011)) +G_() +G() +fp((0.999,1,0.4)) +lw(0.283465) +r(198.827,0,0,-56.6929,304.322,488.976,0.0603744,0.151107) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +Fn('Helvetica-Bold') +Fs(36) +txt('GPGME Library',(0.552654,0,0,0.552654,404.952,457.853),1,1) +G_() +G() +lw(1) +style('Application Box') +r(197.598,0,0,-42.5187,304.724,566.928,0.0152672,0.0677968) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +txt('GPGME aware Application',(0.98062,0,0,0.937018,334.892,540.985)) +G_() +G() +lw(1) +style('Application Box') +r(127.829,0,0,-41.7496,162.992,566.159,0.0152672,0.0677968) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +txt('Legacy Application',(174.688,540.01)) +G_() +G() +G() +lp((0.392,0.584,0.929)) +lw(4.25197) +b() +bs(749.296,162.296,0) +bs(705.89,162.296,0) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(705.89,100.083,0) +bs(744.472,100.083,0) +lp((0.392,0.584,0.929)) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(705.89,131.189,0) +bs(744.472,131.189,0) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('execute/access',(0.31891,0,0,0.280771,726.951,87.3768),1,1) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('closely linked',(0.31891,0,0,0.280771,724.715,149.589),1,1) +fp((0,0,0)) +le() +lw(1) +Fn('Helvetica') +Fs(14) +style('Text') +txt('Assuan protocol',(0.31891,0,0,0.280771,728.535,118.483),1,1) +G_() +lw(1) +r(56.6929,0,0,-92.126,701.575,170.079) +G_() +lp((0.392,0.584,0.929)) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(248.031,325.984,0) +bs(248.031,297.638,0) +bs(538.583,297.638,0) +bs(538.583,340.157,0) +bs(566.929,340.157,0) +lp((0.392,0.584,0.929)) +lw(3.25) +ld((1, 1)) +la2(([(-4.0, 3.0), (2.0, 0.0), (-4.0, -3.0), (-4.0, 3.0)], 1)) +b() +bs(375.591,325.984,0) +bs(375.591,304.724,0) +bs(531.496,304.724,0) +bs(531.496,347.244,0) +bs(566.929,347.244,0) +guidelayer('Guide Lines',1,0,0,1,(0,0,1)) +grid((0,0,7.08661,7.08661),1,(0,0,1),'Grid') diff --git a/doc/stamp-vti b/doc/stamp-vti new file mode 100644 index 0000000..3e9775f --- /dev/null +++ b/doc/stamp-vti @@ -0,0 +1,4 @@ +@set UPDATED 2 May 2012 +@set UPDATED-MONTH May 2012 +@set EDITION 1.3.2 +@set VERSION 1.3.2 diff --git a/doc/texinfo.tex b/doc/texinfo.tex new file mode 100644 index 0000000..d2b264d --- /dev/null +++ b/doc/texinfo.tex @@ -0,0 +1,8962 @@ +% texinfo.tex -- TeX macros to handle Texinfo files. +% +% Load plain if necessary, i.e., if running under initex. +\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi +% +\def\texinfoversion{2007-12-02.17} +% +% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, 2007, +% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, +% 2007 Free Software Foundation, Inc. +% +% This texinfo.tex file is free software: you can redistribute it and/or +% modify it under the terms of the GNU General Public License as +% published by the Free Software Foundation, either version 3 of the +% License, or (at your option) any later version. +% +% This texinfo.tex file is distributed in the hope that it will be +% useful, but WITHOUT ANY WARRANTY; without even the implied warranty +% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +% General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% As a special exception, when this file is read by TeX when processing +% a Texinfo source document, you may use the result without +% restriction. (This has been our intent since Texinfo was invented.) +% +% Please try the latest version of texinfo.tex before submitting bug +% reports; you can get the latest version from: +% http://www.gnu.org/software/texinfo/ (the Texinfo home page), or +% ftp://tug.org/tex/texinfo.tex +% (and all CTAN mirrors, see http://www.ctan.org). +% The texinfo.tex in any given distribution could well be out +% of date, so if that's what you're using, please check. +% +% Send bug reports to bug-texinfo@gnu.org. Please include including a +% complete document in each bug report with which we can reproduce the +% problem. Patches are, of course, greatly appreciated. +% +% To process a Texinfo manual with TeX, it's most reliable to use the +% texi2dvi shell script that comes with the distribution. For a simple +% manual foo.texi, however, you can get away with this: +% tex foo.texi +% texindex foo.?? +% tex foo.texi +% tex foo.texi +% dvips foo.dvi -o # or whatever; this makes foo.ps. +% The extra TeX runs get the cross-reference information correct. +% Sometimes one run after texindex suffices, and sometimes you need more +% than two; texi2dvi does it as many times as necessary. +% +% It is possible to adapt texinfo.tex for other languages, to some +% extent. You can get the existing language-specific files from the +% full Texinfo distribution. +% +% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. + + +\message{Loading texinfo [version \texinfoversion]:} + +% If in a .fmt file, print the version number +% and turn on active characters that we couldn't do earlier because +% they might have appeared in the input file name. +\everyjob{\message{[Texinfo version \texinfoversion]}% + \catcode`+=\active \catcode`\_=\active} + + +\chardef\other=12 + +% We never want plain's \outer definition of \+ in Texinfo. +% For @tex, we can use \tabalign. +\let\+ = \relax + +% Save some plain tex macros whose names we will redefine. +\let\ptexb=\b +\let\ptexbullet=\bullet +\let\ptexc=\c +\let\ptexcomma=\, +\let\ptexdot=\. +\let\ptexdots=\dots +\let\ptexend=\end +\let\ptexequiv=\equiv +\let\ptexexclam=\! +\let\ptexfootnote=\footnote +\let\ptexgtr=> +\let\ptexhat=^ +\let\ptexi=\i +\let\ptexindent=\indent +\let\ptexinsert=\insert +\let\ptexlbrace=\{ +\let\ptexless=< +\let\ptexnewwrite\newwrite +\let\ptexnoindent=\noindent +\let\ptexplus=+ +\let\ptexrbrace=\} +\let\ptexslash=\/ +\let\ptexstar=\* +\let\ptext=\t + +% If this character appears in an error message or help string, it +% starts a new line in the output. +\newlinechar = `^^J + +% Use TeX 3.0's \inputlineno to get the line number, for better error +% messages, but if we're using an old version of TeX, don't do anything. +% +\ifx\inputlineno\thisisundefined + \let\linenumber = \empty % Pre-3.0. +\else + \def\linenumber{l.\the\inputlineno:\space} +\fi + +% Set up fixed words for English if not already set. +\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi +\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi +\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi +\ifx\putwordin\undefined \gdef\putwordin{in}\fi +\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi +\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi +\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi +\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi +\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi +\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi +\ifx\putwordof\undefined \gdef\putwordof{of}\fi +\ifx\putwordon\undefined \gdef\putwordon{on}\fi +\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi +\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi +\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi +\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi +\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi +\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi +\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi +% +\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi +\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi +\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi +\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi +\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi +\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi +\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi +\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi +\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi +\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi +\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi +\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi +% +\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi +\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi +\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi +\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi +\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi + +% Since the category of space is not known, we have to be careful. +\chardef\spacecat = 10 +\def\spaceisspace{\catcode`\ =\spacecat} + +% sometimes characters are active, so we need control sequences. +\chardef\colonChar = `\: +\chardef\commaChar = `\, +\chardef\dashChar = `\- +\chardef\dotChar = `\. +\chardef\exclamChar= `\! +\chardef\lquoteChar= `\` +\chardef\questChar = `\? +\chardef\rquoteChar= `\' +\chardef\semiChar = `\; +\chardef\underChar = `\_ + +% Ignore a token. +% +\def\gobble#1{} + +% The following is used inside several \edef's. +\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname} + +% Hyphenation fixes. +\hyphenation{ + Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script + ap-pen-dix bit-map bit-maps + data-base data-bases eshell fall-ing half-way long-est man-u-script + man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm + par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces + spell-ing spell-ings + stand-alone strong-est time-stamp time-stamps which-ever white-space + wide-spread wrap-around +} + +% Margin to add to right of even pages, to left of odd pages. +\newdimen\bindingoffset +\newdimen\normaloffset +\newdimen\pagewidth \newdimen\pageheight + +% For a final copy, take out the rectangles +% that mark overfull boxes (in case you have decided +% that the text looks ok even though it passes the margin). +% +\def\finalout{\overfullrule=0pt} + +% @| inserts a changebar to the left of the current line. It should +% surround any changed text. This approach does *not* work if the +% change spans more than two lines of output. To handle that, we would +% have adopt a much more difficult approach (putting marks into the main +% vertical list for the beginning and end of each change). +% +\def\|{% + % \vadjust can only be used in horizontal mode. + \leavevmode + % + % Append this vertical mode material after the current line in the output. + \vadjust{% + % We want to insert a rule with the height and depth of the current + % leading; that is exactly what \strutbox is supposed to record. + \vskip-\baselineskip + % + % \vadjust-items are inserted at the left edge of the type. So + % the \llap here moves out into the left-hand margin. + \llap{% + % + % For a thicker or thinner bar, change the `1pt'. + \vrule height\baselineskip width1pt + % + % This is the space between the bar and the text. + \hskip 12pt + }% + }% +} + +% Sometimes it is convenient to have everything in the transcript file +% and nothing on the terminal. We don't just call \tracingall here, +% since that produces some useless output on the terminal. We also make +% some effort to order the tracing commands to reduce output in the log +% file; cf. trace.sty in LaTeX. +% +\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% +\def\loggingall{% + \tracingstats2 + \tracingpages1 + \tracinglostchars2 % 2 gives us more in etex + \tracingparagraphs1 + \tracingoutput1 + \tracingmacros2 + \tracingrestores1 + \showboxbreadth\maxdimen \showboxdepth\maxdimen + \ifx\eTeXversion\undefined\else % etex gives us more logging + \tracingscantokens1 + \tracingifs1 + \tracinggroups1 + \tracingnesting2 + \tracingassigns1 + \fi + \tracingcommands3 % 3 gives us more in etex + \errorcontextlines16 +}% + +% add check for \lastpenalty to plain's definitions. If the last thing +% we did was a \nobreak, we don't want to insert more space. +% +\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount + \removelastskip\penalty-50\smallskip\fi\fi} +\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount + \removelastskip\penalty-100\medskip\fi\fi} +\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount + \removelastskip\penalty-200\bigskip\fi\fi} + +% For @cropmarks command. +% Do @cropmarks to get crop marks. +% +\newif\ifcropmarks +\let\cropmarks = \cropmarkstrue +% +% Dimensions to add cropmarks at corners. +% Added by P. A. MacKay, 12 Nov. 1986 +% +\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines +\newdimen\cornerlong \cornerlong=1pc +\newdimen\cornerthick \cornerthick=.3pt +\newdimen\topandbottommargin \topandbottommargin=.75in + +% Output a mark which sets \thischapter, \thissection and \thiscolor. +% We dump everything together because we only have one kind of mark. +% This works because we only use \botmark / \topmark, not \firstmark. +% +% A mark contains a subexpression of the \ifcase ... \fi construct. +% \get*marks macros below extract the needed part using \ifcase. +% +% Another complication is to let the user choose whether \thischapter +% (\thissection) refers to the chapter (section) in effect at the top +% of a page, or that at the bottom of a page. The solution is +% described on page 260 of The TeXbook. It involves outputting two +% marks for the sectioning macros, one before the section break, and +% one after. I won't pretend I can describe this better than DEK... +\def\domark{% + \toks0=\expandafter{\lastchapterdefs}% + \toks2=\expandafter{\lastsectiondefs}% + \toks4=\expandafter{\prevchapterdefs}% + \toks6=\expandafter{\prevsectiondefs}% + \toks8=\expandafter{\lastcolordefs}% + \mark{% + \the\toks0 \the\toks2 + \noexpand\or \the\toks4 \the\toks6 + \noexpand\else \the\toks8 + }% +} +% \topmark doesn't work for the very first chapter (after the title +% page or the contents), so we use \firstmark there -- this gets us +% the mark with the chapter defs, unless the user sneaks in, e.g., +% @setcolor (or @url, or @link, etc.) between @contents and the very +% first @chapter. +\def\gettopheadingmarks{% + \ifcase0\topmark\fi + \ifx\thischapter\empty \ifcase0\firstmark\fi \fi +} +\def\getbottomheadingmarks{\ifcase1\botmark\fi} +\def\getcolormarks{\ifcase2\topmark\fi} + +% Avoid "undefined control sequence" errors. +\def\lastchapterdefs{} +\def\lastsectiondefs{} +\def\prevchapterdefs{} +\def\prevsectiondefs{} +\def\lastcolordefs{} + +% Main output routine. +\chardef\PAGE = 255 +\output = {\onepageout{\pagecontents\PAGE}} + +\newbox\headlinebox +\newbox\footlinebox + +% \onepageout takes a vbox as an argument. Note that \pagecontents +% does insertions, but you have to call it yourself. +\def\onepageout#1{% + \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi + % + \ifodd\pageno \advance\hoffset by \bindingoffset + \else \advance\hoffset by -\bindingoffset\fi + % + % Do this outside of the \shipout so @code etc. will be expanded in + % the headline as they should be, not taken literally (outputting ''code). + \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi + \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% + \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi + \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% + % + {% + % Have to do this stuff outside the \shipout because we want it to + % take effect in \write's, yet the group defined by the \vbox ends + % before the \shipout runs. + % + \indexdummies % don't expand commands in the output. + \normalturnoffactive % \ in index entries must not stay \, e.g., if + % the page break happens to be in the middle of an example. + % We don't want .vr (or whatever) entries like this: + % \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}} + % "\acronym" won't work when it's read back in; + % it needs to be + % {\code {{\tt \backslashcurfont }acronym} + \shipout\vbox{% + % Do this early so pdf references go to the beginning of the page. + \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi + % + \ifcropmarks \vbox to \outervsize\bgroup + \hsize = \outerhsize + \vskip-\topandbottommargin + \vtop to0pt{% + \line{\ewtop\hfil\ewtop}% + \nointerlineskip + \line{% + \vbox{\moveleft\cornerthick\nstop}% + \hfill + \vbox{\moveright\cornerthick\nstop}% + }% + \vss}% + \vskip\topandbottommargin + \line\bgroup + \hfil % center the page within the outer (page) hsize. + \ifodd\pageno\hskip\bindingoffset\fi + \vbox\bgroup + \fi + % + \unvbox\headlinebox + \pagebody{#1}% + \ifdim\ht\footlinebox > 0pt + % Only leave this space if the footline is nonempty. + % (We lessened \vsize for it in \oddfootingyyy.) + % The \baselineskip=24pt in plain's \makefootline has no effect. + \vskip 24pt + \unvbox\footlinebox + \fi + % + \ifcropmarks + \egroup % end of \vbox\bgroup + \hfil\egroup % end of (centering) \line\bgroup + \vskip\topandbottommargin plus1fill minus1fill + \boxmaxdepth = \cornerthick + \vbox to0pt{\vss + \line{% + \vbox{\moveleft\cornerthick\nsbot}% + \hfill + \vbox{\moveright\cornerthick\nsbot}% + }% + \nointerlineskip + \line{\ewbot\hfil\ewbot}% + }% + \egroup % \vbox from first cropmarks clause + \fi + }% end of \shipout\vbox + }% end of group with \indexdummies + \advancepageno + \ifnum\outputpenalty>-20000 \else\dosupereject\fi +} + +\newinsert\margin \dimen\margin=\maxdimen + +\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} +{\catcode`\@ =11 +\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi +% marginal hacks, juha@viisa.uucp (Juha Takala) +\ifvoid\margin\else % marginal info is present + \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi +\dimen@=\dp#1\relax \unvbox#1\relax +\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi +\ifr@ggedbottom \kern-\dimen@ \vfil \fi} +} + +% Here are the rules for the cropmarks. Note that they are +% offset so that the space between them is truly \outerhsize or \outervsize +% (P. A. MacKay, 12 November, 1986) +% +\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} +\def\nstop{\vbox + {\hrule height\cornerthick depth\cornerlong width\cornerthick}} +\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} +\def\nsbot{\vbox + {\hrule height\cornerlong depth\cornerthick width\cornerthick}} + +% Parse an argument, then pass it to #1. The argument is the rest of +% the input line (except we remove a trailing comment). #1 should be a +% macro which expects an ordinary undelimited TeX argument. +% +\def\parsearg{\parseargusing{}} +\def\parseargusing#1#2{% + \def\argtorun{#2}% + \begingroup + \obeylines + \spaceisspace + #1% + \parseargline\empty% Insert the \empty token, see \finishparsearg below. +} + +{\obeylines % + \gdef\parseargline#1^^M{% + \endgroup % End of the group started in \parsearg. + \argremovecomment #1\comment\ArgTerm% + }% +} + +% First remove any @comment, then any @c comment. +\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm} +\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} + +% Each occurence of `\^^M' or `<space>\^^M' is replaced by a single space. +% +% \argremovec might leave us with trailing space, e.g., +% @end itemize @c foo +% This space token undergoes the same procedure and is eventually removed +% by \finishparsearg. +% +\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M} +\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M} +\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{% + \def\temp{#3}% + \ifx\temp\empty + % Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp: + \let\temp\finishparsearg + \else + \let\temp\argcheckspaces + \fi + % Put the space token in: + \temp#1 #3\ArgTerm +} + +% If a _delimited_ argument is enclosed in braces, they get stripped; so +% to get _exactly_ the rest of the line, we had to prevent such situation. +% We prepended an \empty token at the very beginning and we expand it now, +% just before passing the control to \argtorun. +% (Similarily, we have to think about #3 of \argcheckspacesY above: it is +% either the null string, or it ends with \^^M---thus there is no danger +% that a pair of braces would be stripped. +% +% But first, we have to remove the trailing space token. +% +\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}} + +% \parseargdef\foo{...} +% is roughly equivalent to +% \def\foo{\parsearg\Xfoo} +% \def\Xfoo#1{...} +% +% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my +% favourite TeX trick. --kasal, 16nov03 + +\def\parseargdef#1{% + \expandafter \doparseargdef \csname\string#1\endcsname #1% +} +\def\doparseargdef#1#2{% + \def#2{\parsearg#1}% + \def#1##1% +} + +% Several utility definitions with active space: +{ + \obeyspaces + \gdef\obeyedspace{ } + + % Make each space character in the input produce a normal interword + % space in the output. Don't allow a line break at this space, as this + % is used only in environments like @example, where each line of input + % should produce a line of output anyway. + % + \gdef\sepspaces{\obeyspaces\let =\tie} + + % If an index command is used in an @example environment, any spaces + % therein should become regular spaces in the raw index file, not the + % expansion of \tie (\leavevmode \penalty \@M \ ). + \gdef\unsepspaces{\let =\space} +} + + +\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} + +% Define the framework for environments in texinfo.tex. It's used like this: +% +% \envdef\foo{...} +% \def\Efoo{...} +% +% It's the responsibility of \envdef to insert \begingroup before the +% actual body; @end closes the group after calling \Efoo. \envdef also +% defines \thisenv, so the current environment is known; @end checks +% whether the environment name matches. The \checkenv macro can also be +% used to check whether the current environment is the one expected. +% +% Non-false conditionals (@iftex, @ifset) don't fit into this, so they +% are not treated as enviroments; they don't open a group. (The +% implementation of @end takes care not to call \endgroup in this +% special case.) + + +% At runtime, environments start with this: +\def\startenvironment#1{\begingroup\def\thisenv{#1}} +% initialize +\let\thisenv\empty + +% ... but they get defined via ``\envdef\foo{...}'': +\long\def\envdef#1#2{\def#1{\startenvironment#1#2}} +\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}} + +% Check whether we're in the right environment: +\def\checkenv#1{% + \def\temp{#1}% + \ifx\thisenv\temp + \else + \badenverr + \fi +} + +% Evironment mismatch, #1 expected: +\def\badenverr{% + \errhelp = \EMsimple + \errmessage{This command can appear only \inenvironment\temp, + not \inenvironment\thisenv}% +} +\def\inenvironment#1{% + \ifx#1\empty + out of any environment% + \else + in environment \expandafter\string#1% + \fi +} + +% @end foo executes the definition of \Efoo. +% But first, it executes a specialized version of \checkenv +% +\parseargdef\end{% + \if 1\csname iscond.#1\endcsname + \else + % The general wording of \badenverr may not be ideal, but... --kasal, 06nov03 + \expandafter\checkenv\csname#1\endcsname + \csname E#1\endcsname + \endgroup + \fi +} + +\newhelp\EMsimple{Press RETURN to continue.} + + +%% Simple single-character @ commands + +% @@ prints an @ +% Kludge this until the fonts are right (grr). +\def\@{{\tt\char64}} + +% This is turned off because it was never documented +% and you can use @w{...} around a quote to suppress ligatures. +%% Define @` and @' to be the same as ` and ' +%% but suppressing ligatures. +%\def\`{{`}} +%\def\'{{'}} + +% Used to generate quoted braces. +\def\mylbrace {{\tt\char123}} +\def\myrbrace {{\tt\char125}} +\let\{=\mylbrace +\let\}=\myrbrace +\begingroup + % Definitions to produce \{ and \} commands for indices, + % and @{ and @} for the aux/toc files. + \catcode`\{ = \other \catcode`\} = \other + \catcode`\[ = 1 \catcode`\] = 2 + \catcode`\! = 0 \catcode`\\ = \other + !gdef!lbracecmd[\{]% + !gdef!rbracecmd[\}]% + !gdef!lbraceatcmd[@{]% + !gdef!rbraceatcmd[@}]% +!endgroup + +% @comma{} to avoid , parsing problems. +\let\comma = , + +% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent +% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H. +\let\, = \c +\let\dotaccent = \. +\def\ringaccent#1{{\accent23 #1}} +\let\tieaccent = \t +\let\ubaraccent = \b +\let\udotaccent = \d + +% Other special characters: @questiondown @exclamdown @ordf @ordm +% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss. +\def\questiondown{?`} +\def\exclamdown{!`} +\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}} +\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}} + +% Dotless i and dotless j, used for accents. +\def\imacro{i} +\def\jmacro{j} +\def\dotless#1{% + \def\temp{#1}% + \ifx\temp\imacro \ptexi + \else\ifx\temp\jmacro \j + \else \errmessage{@dotless can be used only with i or j}% + \fi\fi +} + +% The \TeX{} logo, as in plain, but resetting the spacing so that a +% period following counts as ending a sentence. (Idea found in latex.) +% +\edef\TeX{\TeX \spacefactor=1000 } + +% @LaTeX{} logo. Not quite the same results as the definition in +% latex.ltx, since we use a different font for the raised A; it's most +% convenient for us to use an explicitly smaller font, rather than using +% the \scriptstyle font (since we don't reset \scriptstyle and +% \scriptscriptstyle). +% +\def\LaTeX{% + L\kern-.36em + {\setbox0=\hbox{T}% + \vbox to \ht0{\hbox{\selectfonts\lllsize A}\vss}}% + \kern-.15em + \TeX +} + +% Be sure we're in horizontal mode when doing a tie, since we make space +% equivalent to this in @example-like environments. Otherwise, a space +% at the beginning of a line will start with \penalty -- and +% since \penalty is valid in vertical mode, we'd end up putting the +% penalty on the vertical list instead of in the new paragraph. +{\catcode`@ = 11 + % Avoid using \@M directly, because that causes trouble + % if the definition is written into an index file. + \global\let\tiepenalty = \@M + \gdef\tie{\leavevmode\penalty\tiepenalty\ } +} + +% @: forces normal size whitespace following. +\def\:{\spacefactor=1000 } + +% @* forces a line break. +\def\*{\hfil\break\hbox{}\ignorespaces} + +% @/ allows a line break. +\let\/=\allowbreak + +% @. is an end-of-sentence period. +\def\.{.\spacefactor=\endofsentencespacefactor\space} + +% @! is an end-of-sentence bang. +\def\!{!\spacefactor=\endofsentencespacefactor\space} + +% @? is an end-of-sentence query. +\def\?{?\spacefactor=\endofsentencespacefactor\space} + +% @frenchspacing on|off says whether to put extra space after punctuation. +% +\def\onword{on} +\def\offword{off} +% +\parseargdef\frenchspacing{% + \def\temp{#1}% + \ifx\temp\onword \plainfrenchspacing + \else\ifx\temp\offword \plainnonfrenchspacing + \else + \errhelp = \EMsimple + \errmessage{Unknown @frenchspacing option `\temp', must be on/off}% + \fi\fi +} + +% @w prevents a word break. Without the \leavevmode, @w at the +% beginning of a paragraph, when TeX is still in vertical mode, would +% produce a whole line of output instead of starting the paragraph. +\def\w#1{\leavevmode\hbox{#1}} + +% @group ... @end group forces ... to be all on one page, by enclosing +% it in a TeX vbox. We use \vtop instead of \vbox to construct the box +% to keep its height that of a normal line. According to the rules for +% \topskip (p.114 of the TeXbook), the glue inserted is +% max (\topskip - \ht (first item), 0). If that height is large, +% therefore, no glue is inserted, and the space between the headline and +% the text is small, which looks bad. +% +% Another complication is that the group might be very large. This can +% cause the glue on the previous page to be unduly stretched, because it +% does not have much material. In this case, it's better to add an +% explicit \vfill so that the extra space is at the bottom. The +% threshold for doing this is if the group is more than \vfilllimit +% percent of a page (\vfilllimit can be changed inside of @tex). +% +\newbox\groupbox +\def\vfilllimit{0.7} +% +\envdef\group{% + \ifnum\catcode`\^^M=\active \else + \errhelp = \groupinvalidhelp + \errmessage{@group invalid in context where filling is enabled}% + \fi + \startsavinginserts + % + \setbox\groupbox = \vtop\bgroup + % Do @comment since we are called inside an environment such as + % @example, where each end-of-line in the input causes an + % end-of-line in the output. We don't want the end-of-line after + % the `@group' to put extra space in the output. Since @group + % should appear on a line by itself (according to the Texinfo + % manual), we don't worry about eating any user text. + \comment +} +% +% The \vtop produces a box with normal height and large depth; thus, TeX puts +% \baselineskip glue before it, and (when the next line of text is done) +% \lineskip glue after it. Thus, space below is not quite equal to space +% above. But it's pretty close. +\def\Egroup{% + % To get correct interline space between the last line of the group + % and the first line afterwards, we have to propagate \prevdepth. + \endgraf % Not \par, as it may have been set to \lisppar. + \global\dimen1 = \prevdepth + \egroup % End the \vtop. + % \dimen0 is the vertical size of the group's box. + \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox + % \dimen2 is how much space is left on the page (more or less). + \dimen2 = \pageheight \advance\dimen2 by -\pagetotal + % if the group doesn't fit on the current page, and it's a big big + % group, force a page break. + \ifdim \dimen0 > \dimen2 + \ifdim \pagetotal < \vfilllimit\pageheight + \page + \fi + \fi + \box\groupbox + \prevdepth = \dimen1 + \checkinserts +} +% +% TeX puts in an \escapechar (i.e., `@') at the beginning of the help +% message, so this ends up printing `@group can only ...'. +% +\newhelp\groupinvalidhelp{% +group can only be used in environments such as @example,^^J% +where each line of input produces a line of output.} + +% @need space-in-mils +% forces a page break if there is not space-in-mils remaining. + +\newdimen\mil \mil=0.001in + +% Old definition--didn't work. +%\parseargdef\need{\par % +%% This method tries to make TeX break the page naturally +%% if the depth of the box does not fit. +%{\baselineskip=0pt% +%\vtop to #1\mil{\vfil}\kern -#1\mil\nobreak +%\prevdepth=-1000pt +%}} + +\parseargdef\need{% + % Ensure vertical mode, so we don't make a big box in the middle of a + % paragraph. + \par + % + % If the @need value is less than one line space, it's useless. + \dimen0 = #1\mil + \dimen2 = \ht\strutbox + \advance\dimen2 by \dp\strutbox + \ifdim\dimen0 > \dimen2 + % + % Do a \strut just to make the height of this box be normal, so the + % normal leading is inserted relative to the preceding line. + % And a page break here is fine. + \vtop to #1\mil{\strut\vfil}% + % + % TeX does not even consider page breaks if a penalty added to the + % main vertical list is 10000 or more. But in order to see if the + % empty box we just added fits on the page, we must make it consider + % page breaks. On the other hand, we don't want to actually break the + % page after the empty box. So we use a penalty of 9999. + % + % There is an extremely small chance that TeX will actually break the + % page at this \penalty, if there are no other feasible breakpoints in + % sight. (If the user is using lots of big @group commands, which + % almost-but-not-quite fill up a page, TeX will have a hard time doing + % good page breaking, for example.) However, I could not construct an + % example where a page broke at this \penalty; if it happens in a real + % document, then we can reconsider our strategy. + \penalty9999 + % + % Back up by the size of the box, whether we did a page break or not. + \kern -#1\mil + % + % Do not allow a page break right after this kern. + \nobreak + \fi +} + +% @br forces paragraph break (and is undocumented). + +\let\br = \par + +% @page forces the start of a new page. +% +\def\page{\par\vfill\supereject} + +% @exdent text.... +% outputs text on separate line in roman font, starting at standard page margin + +% This records the amount of indent in the innermost environment. +% That's how much \exdent should take out. +\newskip\exdentamount + +% This defn is used inside fill environments such as @defun. +\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break} + +% This defn is used inside nofill environments such as @example. +\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount + \leftline{\hskip\leftskip{\rm#1}}}} + +% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current +% paragraph. For more general purposes, use the \margin insertion +% class. WHICH is `l' or `r'. +% +\newskip\inmarginspacing \inmarginspacing=1cm +\def\strutdepth{\dp\strutbox} +% +\def\doinmargin#1#2{\strut\vadjust{% + \nobreak + \kern-\strutdepth + \vtop to \strutdepth{% + \baselineskip=\strutdepth + \vss + % if you have multiple lines of stuff to put here, you'll need to + % make the vbox yourself of the appropriate size. + \ifx#1l% + \llap{\ignorespaces #2\hskip\inmarginspacing}% + \else + \rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}% + \fi + \null + }% +}} +\def\inleftmargin{\doinmargin l} +\def\inrightmargin{\doinmargin r} +% +% @inmargin{TEXT [, RIGHT-TEXT]} +% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right; +% else use TEXT for both). +% +\def\inmargin#1{\parseinmargin #1,,\finish} +\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing. + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0 > 0pt + \def\lefttext{#1}% have both texts + \def\righttext{#2}% + \else + \def\lefttext{#1}% have only one text + \def\righttext{#1}% + \fi + % + \ifodd\pageno + \def\temp{\inrightmargin\righttext}% odd page -> outside is right margin + \else + \def\temp{\inleftmargin\lefttext}% + \fi + \temp +} + +% @include file insert text of that file as input. +% +\def\include{\parseargusing\filenamecatcodes\includezzz} +\def\includezzz#1{% + \pushthisfilestack + \def\thisfile{#1}% + {% + \makevalueexpandable + \def\temp{\input #1 }% + \expandafter + }\temp + \popthisfilestack +} +\def\filenamecatcodes{% + \catcode`\\=\other + \catcode`~=\other + \catcode`^=\other + \catcode`_=\other + \catcode`|=\other + \catcode`<=\other + \catcode`>=\other + \catcode`+=\other + \catcode`-=\other +} + +\def\pushthisfilestack{% + \expandafter\pushthisfilestackX\popthisfilestack\StackTerm +} +\def\pushthisfilestackX{% + \expandafter\pushthisfilestackY\thisfile\StackTerm +} +\def\pushthisfilestackY #1\StackTerm #2\StackTerm {% + \gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}% +} + +\def\popthisfilestack{\errthisfilestackempty} +\def\errthisfilestackempty{\errmessage{Internal error: + the stack of filenames is empty.}} + +\def\thisfile{} + +% @center line +% outputs that line, centered. +% +\parseargdef\center{% + \ifhmode + \let\next\centerH + \else + \let\next\centerV + \fi + \next{\hfil \ignorespaces#1\unskip \hfil}% +} +\def\centerH#1{% + {% + \hfil\break + \advance\hsize by -\leftskip + \advance\hsize by -\rightskip + \line{#1}% + \break + }% +} +\def\centerV#1{\line{\kern\leftskip #1\kern\rightskip}} + +% @sp n outputs n lines of vertical space + +\parseargdef\sp{\vskip #1\baselineskip} + +% @comment ...line which is ignored... +% @c is the same as @comment +% @ignore ... @end ignore is another way to write a comment + +\def\comment{\begingroup \catcode`\^^M=\other% +\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other% +\commentxxx} +{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}} + +\let\c=\comment + +% @paragraphindent NCHARS +% We'll use ems for NCHARS, close enough. +% NCHARS can also be the word `asis' or `none'. +% We cannot feasibly implement @paragraphindent asis, though. +% +\def\asisword{asis} % no translation, these are keywords +\def\noneword{none} +% +\parseargdef\paragraphindent{% + \def\temp{#1}% + \ifx\temp\asisword + \else + \ifx\temp\noneword + \defaultparindent = 0pt + \else + \defaultparindent = #1em + \fi + \fi + \parindent = \defaultparindent +} + +% @exampleindent NCHARS +% We'll use ems for NCHARS like @paragraphindent. +% It seems @exampleindent asis isn't necessary, but +% I preserve it to make it similar to @paragraphindent. +\parseargdef\exampleindent{% + \def\temp{#1}% + \ifx\temp\asisword + \else + \ifx\temp\noneword + \lispnarrowing = 0pt + \else + \lispnarrowing = #1em + \fi + \fi +} + +% @firstparagraphindent WORD +% If WORD is `none', then suppress indentation of the first paragraph +% after a section heading. If WORD is `insert', then do indent at such +% paragraphs. +% +% The paragraph indentation is suppressed or not by calling +% \suppressfirstparagraphindent, which the sectioning commands do. +% We switch the definition of this back and forth according to WORD. +% By default, we suppress indentation. +% +\def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent} +\def\insertword{insert} +% +\parseargdef\firstparagraphindent{% + \def\temp{#1}% + \ifx\temp\noneword + \let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent + \else\ifx\temp\insertword + \let\suppressfirstparagraphindent = \relax + \else + \errhelp = \EMsimple + \errmessage{Unknown @firstparagraphindent option `\temp'}% + \fi\fi +} + +% Here is how we actually suppress indentation. Redefine \everypar to +% \kern backwards by \parindent, and then reset itself to empty. +% +% We also make \indent itself not actually do anything until the next +% paragraph. +% +\gdef\dosuppressfirstparagraphindent{% + \gdef\indent{% + \restorefirstparagraphindent + \indent + }% + \gdef\noindent{% + \restorefirstparagraphindent + \noindent + }% + \global\everypar = {% + \kern -\parindent + \restorefirstparagraphindent + }% +} + +\gdef\restorefirstparagraphindent{% + \global \let \indent = \ptexindent + \global \let \noindent = \ptexnoindent + \global \everypar = {}% +} + + +% @asis just yields its argument. Used with @table, for example. +% +\def\asis#1{#1} + +% @math outputs its argument in math mode. +% +% One complication: _ usually means subscripts, but it could also mean +% an actual _ character, as in @math{@var{some_variable} + 1}. So make +% _ active, and distinguish by seeing if the current family is \slfam, +% which is what @var uses. +{ + \catcode`\_ = \active + \gdef\mathunderscore{% + \catcode`\_=\active + \def_{\ifnum\fam=\slfam \_\else\sb\fi}% + } +} +% Another complication: we want \\ (and @\) to output a \ character. +% FYI, plain.tex uses \\ as a temporary control sequence (why?), but +% this is not advertised and we don't care. Texinfo does not +% otherwise define @\. +% +% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\. +\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi} +% +\def\math{% + \tex + \mathunderscore + \let\\ = \mathbackslash + \mathactive + $\finishmath +} +\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex. + +% Some active characters (such as <) are spaced differently in math. +% We have to reset their definitions in case the @math was an argument +% to a command which sets the catcodes (such as @item or @section). +% +{ + \catcode`^ = \active + \catcode`< = \active + \catcode`> = \active + \catcode`+ = \active + \gdef\mathactive{% + \let^ = \ptexhat + \let< = \ptexless + \let> = \ptexgtr + \let+ = \ptexplus + } +} + +% @bullet and @minus need the same treatment as @math, just above. +\def\bullet{$\ptexbullet$} +\def\minus{$-$} + +% @dots{} outputs an ellipsis using the current font. +% We do .5em per period so that it has the same spacing in the cm +% typewriter fonts as three actual period characters; on the other hand, +% in other typewriter fonts three periods are wider than 1.5em. So do +% whichever is larger. +% +\def\dots{% + \leavevmode + \setbox0=\hbox{...}% get width of three periods + \ifdim\wd0 > 1.5em + \dimen0 = \wd0 + \else + \dimen0 = 1.5em + \fi + \hbox to \dimen0{% + \hskip 0pt plus.25fil + .\hskip 0pt plus1fil + .\hskip 0pt plus1fil + .\hskip 0pt plus.5fil + }% +} + +% @enddots{} is an end-of-sentence ellipsis. +% +\def\enddots{% + \dots + \spacefactor=\endofsentencespacefactor +} + +% @comma{} is so commas can be inserted into text without messing up +% Texinfo's parsing. +% +\let\comma = , + +% @refill is a no-op. +\let\refill=\relax + +% If working on a large document in chapters, it is convenient to +% be able to disable indexing, cross-referencing, and contents, for test runs. +% This is done with @novalidate (before @setfilename). +% +\newif\iflinks \linkstrue % by default we want the aux files. +\let\novalidate = \linksfalse + +% @setfilename is done at the beginning of every texinfo file. +% So open here the files we need to have open while reading the input. +% This makes it possible to make a .fmt file for texinfo. +\def\setfilename{% + \fixbackslash % Turn off hack to swallow `\input texinfo'. + \iflinks + \tryauxfile + % Open the new aux file. TeX will close it automatically at exit. + \immediate\openout\auxfile=\jobname.aux + \fi % \openindices needs to do some work in any case. + \openindices + \let\setfilename=\comment % Ignore extra @setfilename cmds. + % + % If texinfo.cnf is present on the system, read it. + % Useful for site-wide @afourpaper, etc. + \openin 1 texinfo.cnf + \ifeof 1 \else \input texinfo.cnf \fi + \closein 1 + % + \comment % Ignore the actual filename. +} + +% Called from \setfilename. +% +\def\openindices{% + \newindex{cp}% + \newcodeindex{fn}% + \newcodeindex{vr}% + \newcodeindex{tp}% + \newcodeindex{ky}% + \newcodeindex{pg}% +} + +% @bye. +\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} + + +\message{pdf,} +% adobe `portable' document format +\newcount\tempnum +\newcount\lnkcount +\newtoks\filename +\newcount\filenamelength +\newcount\pgn +\newtoks\toksA +\newtoks\toksB +\newtoks\toksC +\newtoks\toksD +\newbox\boxA +\newcount\countA +\newif\ifpdf +\newif\ifpdfmakepagedest + +% when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1 +% can be set). So we test for \relax and 0 as well as \undefined, +% borrowed from ifpdf.sty. +\ifx\pdfoutput\undefined +\else + \ifx\pdfoutput\relax + \else + \ifcase\pdfoutput + \else + \pdftrue + \fi + \fi +\fi + +% PDF uses PostScript string constants for the names of xref targets, +% for display in the outlines, and in other places. Thus, we have to +% double any backslashes. Otherwise, a name like "\node" will be +% interpreted as a newline (\n), followed by o, d, e. Not good. +% http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html +% (and related messages, the final outcome is that it is up to the TeX +% user to double the backslashes and otherwise make the string valid, so +% that's what we do). + +% double active backslashes. +% +{\catcode`\@=0 \catcode`\\=\active + @gdef@activebackslashdouble{% + @catcode`@\=@active + @let\=@doublebackslash} +} + +% To handle parens, we must adopt a different approach, since parens are +% not active characters. hyperref.dtx (which has the same problem as +% us) handles it with this amazing macro to replace tokens, with minor +% changes for Texinfo. It is included here under the GPL by permission +% from the author, Heiko Oberdiek. +% +% #1 is the tokens to replace. +% #2 is the replacement. +% #3 is the control sequence with the string. +% +\def\HyPsdSubst#1#2#3{% + \def\HyPsdReplace##1#1##2\END{% + ##1% + \ifx\\##2\\% + \else + #2% + \HyReturnAfterFi{% + \HyPsdReplace##2\END + }% + \fi + }% + \xdef#3{\expandafter\HyPsdReplace#3#1\END}% +} +\long\def\HyReturnAfterFi#1\fi{\fi#1} + +% #1 is a control sequence in which to do the replacements. +\def\backslashparens#1{% + \xdef#1{#1}% redefine it as its expansion; the definition is simply + % \lastnode when called from \setref -> \pdfmkdest. + \HyPsdSubst{(}{\realbackslash(}{#1}% + \HyPsdSubst{)}{\realbackslash)}{#1}% +} + +\newhelp\nopdfimagehelp{Texinfo supports .png, .jpg, .jpeg, and .pdf images +with PDF output, and none of those formats could be found. (.eps cannot +be supported due to the design of the PDF format; use regular TeX (DVI +output) for that.)} + +\ifpdf + % + % Color manipulation macros based on pdfcolor.tex. + \def\cmykDarkRed{0.28 1 1 0.35} + \def\cmykBlack{0 0 0 1} + % + \def\pdfsetcolor#1{\pdfliteral{#1 k}} + % Set color, and create a mark which defines \thiscolor accordingly, + % so that \makeheadline knows which color to restore. + \def\setcolor#1{% + \xdef\lastcolordefs{\gdef\noexpand\thiscolor{#1}}% + \domark + \pdfsetcolor{#1}% + } + % + \def\maincolor{\cmykBlack} + \pdfsetcolor{\maincolor} + \edef\thiscolor{\maincolor} + \def\lastcolordefs{} + % + \def\makefootline{% + \baselineskip24pt + \line{\pdfsetcolor{\maincolor}\the\footline}% + } + % + \def\makeheadline{% + \vbox to 0pt{% + \vskip-22.5pt + \line{% + \vbox to8.5pt{}% + % Extract \thiscolor definition from the marks. + \getcolormarks + % Typeset the headline with \maincolor, then restore the color. + \pdfsetcolor{\maincolor}\the\headline\pdfsetcolor{\thiscolor}% + }% + \vss + }% + \nointerlineskip + } + % + % + \pdfcatalog{/PageMode /UseOutlines} + % + % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto). + \def\dopdfimage#1#2#3{% + \def\imagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}% + \def\imageheight{#3}\setbox2 = \hbox{\ignorespaces #3}% + % + % pdftex (and the PDF format) support .png, .jpg, .pdf (among + % others). Let's try in that order. + \let\pdfimgext=\empty + \begingroup + \openin 1 #1.png \ifeof 1 + \openin 1 #1.jpg \ifeof 1 + \openin 1 #1.jpeg \ifeof 1 + \openin 1 #1.JPG \ifeof 1 + \openin 1 #1.pdf \ifeof 1 + \errhelp = \nopdfimagehelp + \errmessage{Could not find image file #1 for pdf}% + \else \gdef\pdfimgext{pdf}% + \fi + \else \gdef\pdfimgext{JPG}% + \fi + \else \gdef\pdfimgext{jpeg}% + \fi + \else \gdef\pdfimgext{jpg}% + \fi + \else \gdef\pdfimgext{png}% + \fi + \closein 1 + \endgroup + % + % without \immediate, pdftex seg faults when the same image is + % included twice. (Version 3.14159-pre-1.0-unofficial-20010704.) + \ifnum\pdftexversion < 14 + \immediate\pdfimage + \else + \immediate\pdfximage + \fi + \ifdim \wd0 >0pt width \imagewidth \fi + \ifdim \wd2 >0pt height \imageheight \fi + \ifnum\pdftexversion<13 + #1.\pdfimgext + \else + {#1.\pdfimgext}% + \fi + \ifnum\pdftexversion < 14 \else + \pdfrefximage \pdflastximage + \fi} + % + \def\pdfmkdest#1{{% + % We have to set dummies so commands such as @code, and characters + % such as \, aren't expanded when present in a section title. + \indexnofonts + \turnoffactive + \activebackslashdouble + \makevalueexpandable + \def\pdfdestname{#1}% + \backslashparens\pdfdestname + \safewhatsit{\pdfdest name{\pdfdestname} xyz}% + }} + % + % used to mark target names; must be expandable. + \def\pdfmkpgn#1{#1} + % + % by default, use a color that is dark enough to print on paper as + % nearly black, but still distinguishable for online viewing. + \def\urlcolor{\cmykDarkRed} + \def\linkcolor{\cmykDarkRed} + \def\endlink{\setcolor{\maincolor}\pdfendlink} + % + % Adding outlines to PDF; macros for calculating structure of outlines + % come from Petr Olsak + \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0% + \else \csname#1\endcsname \fi} + \def\advancenumber#1{\tempnum=\expnumber{#1}\relax + \advance\tempnum by 1 + \expandafter\xdef\csname#1\endcsname{\the\tempnum}} + % + % #1 is the section text, which is what will be displayed in the + % outline by the pdf viewer. #2 is the pdf expression for the number + % of subentries (or empty, for subsubsections). #3 is the node text, + % which might be empty if this toc entry had no corresponding node. + % #4 is the page number + % + \def\dopdfoutline#1#2#3#4{% + % Generate a link to the node text if that exists; else, use the + % page number. We could generate a destination for the section + % text in the case where a section has no node, but it doesn't + % seem worth the trouble, since most documents are normally structured. + \def\pdfoutlinedest{#3}% + \ifx\pdfoutlinedest\empty + \def\pdfoutlinedest{#4}% + \else + % Doubled backslashes in the name. + {\activebackslashdouble \xdef\pdfoutlinedest{#3}% + \backslashparens\pdfoutlinedest}% + \fi + % + % Also double the backslashes in the display string. + {\activebackslashdouble \xdef\pdfoutlinetext{#1}% + \backslashparens\pdfoutlinetext}% + % + \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}% + } + % + \def\pdfmakeoutlines{% + \begingroup + % Thanh's hack / proper braces in bookmarks + \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace + \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace + % + % Read toc silently, to get counts of subentries for \pdfoutline. + \def\numchapentry##1##2##3##4{% + \def\thischapnum{##2}% + \def\thissecnum{0}% + \def\thissubsecnum{0}% + }% + \def\numsecentry##1##2##3##4{% + \advancenumber{chap\thischapnum}% + \def\thissecnum{##2}% + \def\thissubsecnum{0}% + }% + \def\numsubsecentry##1##2##3##4{% + \advancenumber{sec\thissecnum}% + \def\thissubsecnum{##2}% + }% + \def\numsubsubsecentry##1##2##3##4{% + \advancenumber{subsec\thissubsecnum}% + }% + \def\thischapnum{0}% + \def\thissecnum{0}% + \def\thissubsecnum{0}% + % + % use \def rather than \let here because we redefine \chapentry et + % al. a second time, below. + \def\appentry{\numchapentry}% + \def\appsecentry{\numsecentry}% + \def\appsubsecentry{\numsubsecentry}% + \def\appsubsubsecentry{\numsubsubsecentry}% + \def\unnchapentry{\numchapentry}% + \def\unnsecentry{\numsecentry}% + \def\unnsubsecentry{\numsubsecentry}% + \def\unnsubsubsecentry{\numsubsubsecentry}% + \readdatafile{toc}% + % + % Read toc second time, this time actually producing the outlines. + % The `-' means take the \expnumber as the absolute number of + % subentries, which we calculated on our first read of the .toc above. + % + % We use the node names as the destinations. + \def\numchapentry##1##2##3##4{% + \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}% + \def\numsecentry##1##2##3##4{% + \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}% + \def\numsubsecentry##1##2##3##4{% + \dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}% + \def\numsubsubsecentry##1##2##3##4{% count is always zero + \dopdfoutline{##1}{}{##3}{##4}}% + % + % PDF outlines are displayed using system fonts, instead of + % document fonts. Therefore we cannot use special characters, + % since the encoding is unknown. For example, the eogonek from + % Latin 2 (0xea) gets translated to a | character. Info from + % Staszek Wawrykiewicz, 19 Jan 2004 04:09:24 +0100. + % + % xx to do this right, we have to translate 8-bit characters to + % their "best" equivalent, based on the @documentencoding. Right + % now, I guess we'll just let the pdf reader have its way. + \indexnofonts + \setupdatafile + \catcode`\\=\active \otherbackslash + \input \tocreadfilename + \endgroup + } + % + \def\skipspaces#1{\def\PP{#1}\def\D{|}% + \ifx\PP\D\let\nextsp\relax + \else\let\nextsp\skipspaces + \ifx\p\space\else\addtokens{\filename}{\PP}% + \advance\filenamelength by 1 + \fi + \fi + \nextsp} + \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax} + \ifnum\pdftexversion < 14 + \let \startlink \pdfannotlink + \else + \let \startlink \pdfstartlink + \fi + % make a live url in pdf output. + \def\pdfurl#1{% + \begingroup + % it seems we really need yet another set of dummies; have not + % tried to figure out what each command should do in the context + % of @url. for now, just make @/ a no-op, that's the only one + % people have actually reported a problem with. + % + \normalturnoffactive + \def\@{@}% + \let\/=\empty + \makevalueexpandable + \leavevmode\setcolor{\urlcolor}% + \startlink attr{/Border [0 0 0]}% + user{/Subtype /Link /A << /S /URI /URI (#1) >>}% + \endgroup} + \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}} + \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} + \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks} + \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}} + \def\maketoks{% + \expandafter\poptoks\the\toksA|ENDTOKS|\relax + \ifx\first0\adn0 + \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3 + \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6 + \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9 + \else + \ifnum0=\countA\else\makelink\fi + \ifx\first.\let\next=\done\else + \let\next=\maketoks + \addtokens{\toksB}{\the\toksD} + \ifx\first,\addtokens{\toksB}{\space}\fi + \fi + \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi + \next} + \def\makelink{\addtokens{\toksB}% + {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0} + \def\pdflink#1{% + \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}} + \setcolor{\linkcolor}#1\endlink} + \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st} +\else + \let\pdfmkdest = \gobble + \let\pdfurl = \gobble + \let\endlink = \relax + \let\setcolor = \gobble + \let\pdfsetcolor = \gobble + \let\pdfmakeoutlines = \relax +\fi % \ifx\pdfoutput + + +\message{fonts,} + +% Change the current font style to #1, remembering it in \curfontstyle. +% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in +% italics, not bold italics. +% +\def\setfontstyle#1{% + \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd. + \csname ten#1\endcsname % change the current font +} + +% Select #1 fonts with the current style. +% +\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname} + +\def\rm{\fam=0 \setfontstyle{rm}} +\def\it{\fam=\itfam \setfontstyle{it}} +\def\sl{\fam=\slfam \setfontstyle{sl}} +\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf} +\def\tt{\fam=\ttfam \setfontstyle{tt}} + +% Texinfo sort of supports the sans serif font style, which plain TeX does not. +% So we set up a \sf. +\newfam\sffam +\def\sf{\fam=\sffam \setfontstyle{sf}} +\let\li = \sf % Sometimes we call it \li, not \sf. + +% We don't need math for this font style. +\def\ttsl{\setfontstyle{ttsl}} + + +% Default leading. +\newdimen\textleading \textleading = 13.2pt + +% Set the baselineskip to #1, and the lineskip and strut size +% correspondingly. There is no deep meaning behind these magic numbers +% used as factors; they just match (closely enough) what Knuth defined. +% +\def\lineskipfactor{.08333} +\def\strutheightpercent{.70833} +\def\strutdepthpercent {.29167} +% +% can get a sort of poor man's double spacing by redefining this. +\def\baselinefactor{1} +% +\def\setleading#1{% + \dimen0 = #1\relax + \normalbaselineskip = \baselinefactor\dimen0 + \normallineskip = \lineskipfactor\normalbaselineskip + \normalbaselines + \setbox\strutbox =\hbox{% + \vrule width0pt height\strutheightpercent\baselineskip + depth \strutdepthpercent \baselineskip + }% +} + +% PDF CMaps. See also LaTeX's t1.cmap. +% +% do nothing with this by default. +\expandafter\let\csname cmapOT1\endcsname\gobble +\expandafter\let\csname cmapOT1IT\endcsname\gobble +\expandafter\let\csname cmapOT1TT\endcsname\gobble + +% if we are producing pdf, and we have \pdffontattr, then define cmaps. +% (\pdffontattr was introduced many years ago, but people still run +% older pdftex's; it's easy to conditionalize, so we do.) +\ifpdf \ifx\pdffontattr\undefined \else + \begingroup + \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. + \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap +%%DocumentNeededResources: ProcSet (CIDInit) +%%IncludeResource: ProcSet (CIDInit) +%%BeginResource: CMap (TeX-OT1-0) +%%Title: (TeX-OT1-0 TeX OT1 0) +%%Version: 1.000 +%%EndComments +/CIDInit /ProcSet findresource begin +12 dict begin +begincmap +/CIDSystemInfo +<< /Registry (TeX) +/Ordering (OT1) +/Supplement 0 +>> def +/CMapName /TeX-OT1-0 def +/CMapType 2 def +1 begincodespacerange +<00> <7F> +endcodespacerange +8 beginbfrange +<00> <01> <0393> +<09> <0A> <03A8> +<23> <26> <0023> +<28> <3B> <0028> +<3F> <5B> <003F> +<5D> <5E> <005D> +<61> <7A> <0061> +<7B> <7C> <2013> +endbfrange +40 beginbfchar +<02> <0398> +<03> <039B> +<04> <039E> +<05> <03A0> +<06> <03A3> +<07> <03D2> +<08> <03A6> +<0B> <00660066> +<0C> <00660069> +<0D> <0066006C> +<0E> <006600660069> +<0F> <00660066006C> +<10> <0131> +<11> <0237> +<12> <0060> +<13> <00B4> +<14> <02C7> +<15> <02D8> +<16> <00AF> +<17> <02DA> +<18> <00B8> +<19> <00DF> +<1A> <00E6> +<1B> <0153> +<1C> <00F8> +<1D> <00C6> +<1E> <0152> +<1F> <00D8> +<21> <0021> +<22> <201D> +<27> <2019> +<3C> <00A1> +<3D> <003D> +<3E> <00BF> +<5C> <201C> +<5F> <02D9> +<60> <2018> +<7D> <02DD> +<7E> <007E> +<7F> <00A8> +endbfchar +endcmap +CMapName currentdict /CMap defineresource pop +end +end +%%EndResource +%%EOF + }\endgroup + \expandafter\edef\csname cmapOT1\endcsname#1{% + \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% + }% +% +% \cmapOT1IT + \begingroup + \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. + \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap +%%DocumentNeededResources: ProcSet (CIDInit) +%%IncludeResource: ProcSet (CIDInit) +%%BeginResource: CMap (TeX-OT1IT-0) +%%Title: (TeX-OT1IT-0 TeX OT1IT 0) +%%Version: 1.000 +%%EndComments +/CIDInit /ProcSet findresource begin +12 dict begin +begincmap +/CIDSystemInfo +<< /Registry (TeX) +/Ordering (OT1IT) +/Supplement 0 +>> def +/CMapName /TeX-OT1IT-0 def +/CMapType 2 def +1 begincodespacerange +<00> <7F> +endcodespacerange +8 beginbfrange +<00> <01> <0393> +<09> <0A> <03A8> +<25> <26> <0025> +<28> <3B> <0028> +<3F> <5B> <003F> +<5D> <5E> <005D> +<61> <7A> <0061> +<7B> <7C> <2013> +endbfrange +42 beginbfchar +<02> <0398> +<03> <039B> +<04> <039E> +<05> <03A0> +<06> <03A3> +<07> <03D2> +<08> <03A6> +<0B> <00660066> +<0C> <00660069> +<0D> <0066006C> +<0E> <006600660069> +<0F> <00660066006C> +<10> <0131> +<11> <0237> +<12> <0060> +<13> <00B4> +<14> <02C7> +<15> <02D8> +<16> <00AF> +<17> <02DA> +<18> <00B8> +<19> <00DF> +<1A> <00E6> +<1B> <0153> +<1C> <00F8> +<1D> <00C6> +<1E> <0152> +<1F> <00D8> +<21> <0021> +<22> <201D> +<23> <0023> +<24> <00A3> +<27> <2019> +<3C> <00A1> +<3D> <003D> +<3E> <00BF> +<5C> <201C> +<5F> <02D9> +<60> <2018> +<7D> <02DD> +<7E> <007E> +<7F> <00A8> +endbfchar +endcmap +CMapName currentdict /CMap defineresource pop +end +end +%%EndResource +%%EOF + }\endgroup + \expandafter\edef\csname cmapOT1IT\endcsname#1{% + \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% + }% +% +% \cmapOT1TT + \begingroup + \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. + \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap +%%DocumentNeededResources: ProcSet (CIDInit) +%%IncludeResource: ProcSet (CIDInit) +%%BeginResource: CMap (TeX-OT1TT-0) +%%Title: (TeX-OT1TT-0 TeX OT1TT 0) +%%Version: 1.000 +%%EndComments +/CIDInit /ProcSet findresource begin +12 dict begin +begincmap +/CIDSystemInfo +<< /Registry (TeX) +/Ordering (OT1TT) +/Supplement 0 +>> def +/CMapName /TeX-OT1TT-0 def +/CMapType 2 def +1 begincodespacerange +<00> <7F> +endcodespacerange +5 beginbfrange +<00> <01> <0393> +<09> <0A> <03A8> +<21> <26> <0021> +<28> <5F> <0028> +<61> <7E> <0061> +endbfrange +32 beginbfchar +<02> <0398> +<03> <039B> +<04> <039E> +<05> <03A0> +<06> <03A3> +<07> <03D2> +<08> <03A6> +<0B> <2191> +<0C> <2193> +<0D> <0027> +<0E> <00A1> +<0F> <00BF> +<10> <0131> +<11> <0237> +<12> <0060> +<13> <00B4> +<14> <02C7> +<15> <02D8> +<16> <00AF> +<17> <02DA> +<18> <00B8> +<19> <00DF> +<1A> <00E6> +<1B> <0153> +<1C> <00F8> +<1D> <00C6> +<1E> <0152> +<1F> <00D8> +<20> <2423> +<27> <2019> +<60> <2018> +<7F> <00A8> +endbfchar +endcmap +CMapName currentdict /CMap defineresource pop +end +end +%%EndResource +%%EOF + }\endgroup + \expandafter\edef\csname cmapOT1TT\endcsname#1{% + \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% + }% +\fi\fi + + +% Set the font macro #1 to the font named #2, adding on the +% specified font prefix (normally `cm'). +% #3 is the font's design size, #4 is a scale factor, #5 is the CMap +% encoding (currently only OT1, OT1IT and OT1TT are allowed, pass +% empty to omit). +\def\setfont#1#2#3#4#5{% + \font#1=\fontprefix#2#3 scaled #4 + \csname cmap#5\endcsname#1% +} +% This is what gets called when #5 of \setfont is empty. +\let\cmap\gobble +% emacs-page end of cmaps + +% Use cm as the default font prefix. +% To specify the font prefix, you must define \fontprefix +% before you read in texinfo.tex. +\ifx\fontprefix\undefined +\def\fontprefix{cm} +\fi +% Support font families that don't use the same naming scheme as CM. +\def\rmshape{r} +\def\rmbshape{bx} %where the normal face is bold +\def\bfshape{b} +\def\bxshape{bx} +\def\ttshape{tt} +\def\ttbshape{tt} +\def\ttslshape{sltt} +\def\itshape{ti} +\def\itbshape{bxti} +\def\slshape{sl} +\def\slbshape{bxsl} +\def\sfshape{ss} +\def\sfbshape{ss} +\def\scshape{csc} +\def\scbshape{csc} + +% Definitions for a main text size of 11pt. This is the default in +% Texinfo. +% +\def\definetextfontsizexi{% +% Text fonts (11.2pt, magstep1). +\def\textnominalsize{11pt} +\edef\mainmagstep{\magstephalf} +\setfont\textrm\rmshape{10}{\mainmagstep}{OT1} +\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT} +\setfont\textbf\bfshape{10}{\mainmagstep}{OT1} +\setfont\textit\itshape{10}{\mainmagstep}{OT1IT} +\setfont\textsl\slshape{10}{\mainmagstep}{OT1} +\setfont\textsf\sfshape{10}{\mainmagstep}{OT1} +\setfont\textsc\scshape{10}{\mainmagstep}{OT1} +\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT} +\font\texti=cmmi10 scaled \mainmagstep +\font\textsy=cmsy10 scaled \mainmagstep +\def\textecsize{1095} + +% A few fonts for @defun names and args. +\setfont\defbf\bfshape{10}{\magstep1}{OT1} +\setfont\deftt\ttshape{10}{\magstep1}{OT1TT} +\setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} + +% Fonts for indices, footnotes, small examples (9pt). +\def\smallnominalsize{9pt} +\setfont\smallrm\rmshape{9}{1000}{OT1} +\setfont\smalltt\ttshape{9}{1000}{OT1TT} +\setfont\smallbf\bfshape{10}{900}{OT1} +\setfont\smallit\itshape{9}{1000}{OT1IT} +\setfont\smallsl\slshape{9}{1000}{OT1} +\setfont\smallsf\sfshape{9}{1000}{OT1} +\setfont\smallsc\scshape{10}{900}{OT1} +\setfont\smallttsl\ttslshape{10}{900}{OT1TT} +\font\smalli=cmmi9 +\font\smallsy=cmsy9 +\def\smallecsize{0900} + +% Fonts for small examples (8pt). +\def\smallernominalsize{8pt} +\setfont\smallerrm\rmshape{8}{1000}{OT1} +\setfont\smallertt\ttshape{8}{1000}{OT1TT} +\setfont\smallerbf\bfshape{10}{800}{OT1} +\setfont\smallerit\itshape{8}{1000}{OT1IT} +\setfont\smallersl\slshape{8}{1000}{OT1} +\setfont\smallersf\sfshape{8}{1000}{OT1} +\setfont\smallersc\scshape{10}{800}{OT1} +\setfont\smallerttsl\ttslshape{10}{800}{OT1TT} +\font\smalleri=cmmi8 +\font\smallersy=cmsy8 +\def\smallerecsize{0800} + +% Fonts for title page (20.4pt): +\def\titlenominalsize{20pt} +\setfont\titlerm\rmbshape{12}{\magstep3}{OT1} +\setfont\titleit\itbshape{10}{\magstep4}{OT1IT} +\setfont\titlesl\slbshape{10}{\magstep4}{OT1} +\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT} +\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT} +\setfont\titlesf\sfbshape{17}{\magstep1}{OT1} +\let\titlebf=\titlerm +\setfont\titlesc\scbshape{10}{\magstep4}{OT1} +\font\titlei=cmmi12 scaled \magstep3 +\font\titlesy=cmsy10 scaled \magstep4 +\def\authorrm{\secrm} +\def\authortt{\sectt} +\def\titleecsize{2074} + +% Chapter (and unnumbered) fonts (17.28pt). +\def\chapnominalsize{17pt} +\setfont\chaprm\rmbshape{12}{\magstep2}{OT1} +\setfont\chapit\itbshape{10}{\magstep3}{OT1IT} +\setfont\chapsl\slbshape{10}{\magstep3}{OT1} +\setfont\chaptt\ttbshape{12}{\magstep2}{OT1TT} +\setfont\chapttsl\ttslshape{10}{\magstep3}{OT1TT} +\setfont\chapsf\sfbshape{17}{1000}{OT1} +\let\chapbf=\chaprm +\setfont\chapsc\scbshape{10}{\magstep3}{OT1} +\font\chapi=cmmi12 scaled \magstep2 +\font\chapsy=cmsy10 scaled \magstep3 +\def\chapecsize{1728} + +% Section fonts (14.4pt). +\def\secnominalsize{14pt} +\setfont\secrm\rmbshape{12}{\magstep1}{OT1} +\setfont\secit\itbshape{10}{\magstep2}{OT1IT} +\setfont\secsl\slbshape{10}{\magstep2}{OT1} +\setfont\sectt\ttbshape{12}{\magstep1}{OT1TT} +\setfont\secttsl\ttslshape{10}{\magstep2}{OT1TT} +\setfont\secsf\sfbshape{12}{\magstep1}{OT1} +\let\secbf\secrm +\setfont\secsc\scbshape{10}{\magstep2}{OT1} +\font\seci=cmmi12 scaled \magstep1 +\font\secsy=cmsy10 scaled \magstep2 +\def\sececsize{1440} + +% Subsection fonts (13.15pt). +\def\ssecnominalsize{13pt} +\setfont\ssecrm\rmbshape{12}{\magstephalf}{OT1} +\setfont\ssecit\itbshape{10}{1315}{OT1IT} +\setfont\ssecsl\slbshape{10}{1315}{OT1} +\setfont\ssectt\ttbshape{12}{\magstephalf}{OT1TT} +\setfont\ssecttsl\ttslshape{10}{1315}{OT1TT} +\setfont\ssecsf\sfbshape{12}{\magstephalf}{OT1} +\let\ssecbf\ssecrm +\setfont\ssecsc\scbshape{10}{1315}{OT1} +\font\sseci=cmmi12 scaled \magstephalf +\font\ssecsy=cmsy10 scaled 1315 +\def\ssececsize{1200} + +% Reduced fonts for @acro in text (10pt). +\def\reducednominalsize{10pt} +\setfont\reducedrm\rmshape{10}{1000}{OT1} +\setfont\reducedtt\ttshape{10}{1000}{OT1TT} +\setfont\reducedbf\bfshape{10}{1000}{OT1} +\setfont\reducedit\itshape{10}{1000}{OT1IT} +\setfont\reducedsl\slshape{10}{1000}{OT1} +\setfont\reducedsf\sfshape{10}{1000}{OT1} +\setfont\reducedsc\scshape{10}{1000}{OT1} +\setfont\reducedttsl\ttslshape{10}{1000}{OT1TT} +\font\reducedi=cmmi10 +\font\reducedsy=cmsy10 +\def\reducedecsize{1000} + +% reset the current fonts +\textfonts +\rm +} % end of 11pt text font size definitions + + +% Definitions to make the main text be 10pt Computer Modern, with +% section, chapter, etc., sizes following suit. This is for the GNU +% Press printing of the Emacs 22 manual. Maybe other manuals in the +% future. Used with @smallbook, which sets the leading to 12pt. +% +\def\definetextfontsizex{% +% Text fonts (10pt). +\def\textnominalsize{10pt} +\edef\mainmagstep{1000} +\setfont\textrm\rmshape{10}{\mainmagstep}{OT1} +\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT} +\setfont\textbf\bfshape{10}{\mainmagstep}{OT1} +\setfont\textit\itshape{10}{\mainmagstep}{OT1IT} +\setfont\textsl\slshape{10}{\mainmagstep}{OT1} +\setfont\textsf\sfshape{10}{\mainmagstep}{OT1} +\setfont\textsc\scshape{10}{\mainmagstep}{OT1} +\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT} +\font\texti=cmmi10 scaled \mainmagstep +\font\textsy=cmsy10 scaled \mainmagstep +\def\textecsize{1000} + +% A few fonts for @defun names and args. +\setfont\defbf\bfshape{10}{\magstephalf}{OT1} +\setfont\deftt\ttshape{10}{\magstephalf}{OT1TT} +\setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} + +% Fonts for indices, footnotes, small examples (9pt). +\def\smallnominalsize{9pt} +\setfont\smallrm\rmshape{9}{1000}{OT1} +\setfont\smalltt\ttshape{9}{1000}{OT1TT} +\setfont\smallbf\bfshape{10}{900}{OT1} +\setfont\smallit\itshape{9}{1000}{OT1IT} +\setfont\smallsl\slshape{9}{1000}{OT1} +\setfont\smallsf\sfshape{9}{1000}{OT1} +\setfont\smallsc\scshape{10}{900}{OT1} +\setfont\smallttsl\ttslshape{10}{900}{OT1TT} +\font\smalli=cmmi9 +\font\smallsy=cmsy9 +\def\smallecsize{0900} + +% Fonts for small examples (8pt). +\def\smallernominalsize{8pt} +\setfont\smallerrm\rmshape{8}{1000}{OT1} +\setfont\smallertt\ttshape{8}{1000}{OT1TT} +\setfont\smallerbf\bfshape{10}{800}{OT1} +\setfont\smallerit\itshape{8}{1000}{OT1IT} +\setfont\smallersl\slshape{8}{1000}{OT1} +\setfont\smallersf\sfshape{8}{1000}{OT1} +\setfont\smallersc\scshape{10}{800}{OT1} +\setfont\smallerttsl\ttslshape{10}{800}{OT1TT} +\font\smalleri=cmmi8 +\font\smallersy=cmsy8 +\def\smallerecsize{0800} + +% Fonts for title page (20.4pt): +\def\titlenominalsize{20pt} +\setfont\titlerm\rmbshape{12}{\magstep3}{OT1} +\setfont\titleit\itbshape{10}{\magstep4}{OT1IT} +\setfont\titlesl\slbshape{10}{\magstep4}{OT1} +\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT} +\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT} +\setfont\titlesf\sfbshape{17}{\magstep1}{OT1} +\let\titlebf=\titlerm +\setfont\titlesc\scbshape{10}{\magstep4}{OT1} +\font\titlei=cmmi12 scaled \magstep3 +\font\titlesy=cmsy10 scaled \magstep4 +\def\authorrm{\secrm} +\def\authortt{\sectt} +\def\titleecsize{2074} + +% Chapter fonts (14.4pt). +\def\chapnominalsize{14pt} +\setfont\chaprm\rmbshape{12}{\magstep1}{OT1} +\setfont\chapit\itbshape{10}{\magstep2}{OT1IT} +\setfont\chapsl\slbshape{10}{\magstep2}{OT1} +\setfont\chaptt\ttbshape{12}{\magstep1}{OT1TT} +\setfont\chapttsl\ttslshape{10}{\magstep2}{OT1TT} +\setfont\chapsf\sfbshape{12}{\magstep1}{OT1} +\let\chapbf\chaprm +\setfont\chapsc\scbshape{10}{\magstep2}{OT1} +\font\chapi=cmmi12 scaled \magstep1 +\font\chapsy=cmsy10 scaled \magstep2 +\def\chapecsize{1440} + +% Section fonts (12pt). +\def\secnominalsize{12pt} +\setfont\secrm\rmbshape{12}{1000}{OT1} +\setfont\secit\itbshape{10}{\magstep1}{OT1IT} +\setfont\secsl\slbshape{10}{\magstep1}{OT1} +\setfont\sectt\ttbshape{12}{1000}{OT1TT} +\setfont\secttsl\ttslshape{10}{\magstep1}{OT1TT} +\setfont\secsf\sfbshape{12}{1000}{OT1} +\let\secbf\secrm +\setfont\secsc\scbshape{10}{\magstep1}{OT1} +\font\seci=cmmi12 +\font\secsy=cmsy10 scaled \magstep1 +\def\sececsize{1200} + +% Subsection fonts (10pt). +\def\ssecnominalsize{10pt} +\setfont\ssecrm\rmbshape{10}{1000}{OT1} +\setfont\ssecit\itbshape{10}{1000}{OT1IT} +\setfont\ssecsl\slbshape{10}{1000}{OT1} +\setfont\ssectt\ttbshape{10}{1000}{OT1TT} +\setfont\ssecttsl\ttslshape{10}{1000}{OT1TT} +\setfont\ssecsf\sfbshape{10}{1000}{OT1} +\let\ssecbf\ssecrm +\setfont\ssecsc\scbshape{10}{1000}{OT1} +\font\sseci=cmmi10 +\font\ssecsy=cmsy10 +\def\ssececsize{1000} + +% Reduced fonts for @acro in text (9pt). +\def\reducednominalsize{9pt} +\setfont\reducedrm\rmshape{9}{1000}{OT1} +\setfont\reducedtt\ttshape{9}{1000}{OT1TT} +\setfont\reducedbf\bfshape{10}{900}{OT1} +\setfont\reducedit\itshape{9}{1000}{OT1IT} +\setfont\reducedsl\slshape{9}{1000}{OT1} +\setfont\reducedsf\sfshape{9}{1000}{OT1} +\setfont\reducedsc\scshape{10}{900}{OT1} +\setfont\reducedttsl\ttslshape{10}{900}{OT1TT} +\font\reducedi=cmmi9 +\font\reducedsy=cmsy9 +\def\reducedecsize{0900} + +% reduce space between paragraphs +\divide\parskip by 2 + +% reset the current fonts +\textfonts +\rm +} % end of 10pt text font size definitions + + +% We provide the user-level command +% @fonttextsize 10 +% (or 11) to redefine the text font size. pt is assumed. +% +\def\xword{10} +\def\xiword{11} +% +\parseargdef\fonttextsize{% + \def\textsizearg{#1}% + \wlog{doing @fonttextsize \textsizearg}% + % + % Set \globaldefs so that documents can use this inside @tex, since + % makeinfo 4.8 does not support it, but we need it nonetheless. + % + \begingroup \globaldefs=1 + \ifx\textsizearg\xword \definetextfontsizex + \else \ifx\textsizearg\xiword \definetextfontsizexi + \else + \errhelp=\EMsimple + \errmessage{@fonttextsize only supports `10' or `11', not `\textsizearg'} + \fi\fi + \endgroup +} + + +% In order for the font changes to affect most math symbols and letters, +% we have to define the \textfont of the standard families. Since +% texinfo doesn't allow for producing subscripts and superscripts except +% in the main text, we don't bother to reset \scriptfont and +% \scriptscriptfont (which would also require loading a lot more fonts). +% +\def\resetmathfonts{% + \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy + \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf + \textfont\ttfam=\tentt \textfont\sffam=\tensf +} + +% The font-changing commands redefine the meanings of \tenSTYLE, instead +% of just \STYLE. We do this because \STYLE needs to also set the +% current \fam for math mode. Our \STYLE (e.g., \rm) commands hardwire +% \tenSTYLE to set the current font. +% +% Each font-changing command also sets the names \lsize (one size lower) +% and \lllsize (three sizes lower). These relative commands are used in +% the LaTeX logo and acronyms. +% +% This all needs generalizing, badly. +% +\def\textfonts{% + \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl + \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc + \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy + \let\tenttsl=\textttsl + \def\curfontsize{text}% + \def\lsize{reduced}\def\lllsize{smaller}% + \resetmathfonts \setleading{\textleading}} +\def\titlefonts{% + \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl + \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc + \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy + \let\tenttsl=\titlettsl + \def\curfontsize{title}% + \def\lsize{chap}\def\lllsize{subsec}% + \resetmathfonts \setleading{25pt}} +\def\titlefont#1{{\titlefonts\rm #1}} +\def\chapfonts{% + \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl + \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc + \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy + \let\tenttsl=\chapttsl + \def\curfontsize{chap}% + \def\lsize{sec}\def\lllsize{text}% + \resetmathfonts \setleading{19pt}} +\def\secfonts{% + \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl + \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc + \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy + \let\tenttsl=\secttsl + \def\curfontsize{sec}% + \def\lsize{subsec}\def\lllsize{reduced}% + \resetmathfonts \setleading{16pt}} +\def\subsecfonts{% + \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl + \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc + \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy + \let\tenttsl=\ssecttsl + \def\curfontsize{ssec}% + \def\lsize{text}\def\lllsize{small}% + \resetmathfonts \setleading{15pt}} +\let\subsubsecfonts = \subsecfonts +\def\reducedfonts{% + \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl + \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc + \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy + \let\tenttsl=\reducedttsl + \def\curfontsize{reduced}% + \def\lsize{small}\def\lllsize{smaller}% + \resetmathfonts \setleading{10.5pt}} +\def\smallfonts{% + \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl + \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc + \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy + \let\tenttsl=\smallttsl + \def\curfontsize{small}% + \def\lsize{smaller}\def\lllsize{smaller}% + \resetmathfonts \setleading{10.5pt}} +\def\smallerfonts{% + \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl + \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc + \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy + \let\tenttsl=\smallerttsl + \def\curfontsize{smaller}% + \def\lsize{smaller}\def\lllsize{smaller}% + \resetmathfonts \setleading{9.5pt}} + +% Set the fonts to use with the @small... environments. +\let\smallexamplefonts = \smallfonts + +% About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample +% can fit this many characters: +% 8.5x11=86 smallbook=72 a4=90 a5=69 +% If we use \scriptfonts (8pt), then we can fit this many characters: +% 8.5x11=90+ smallbook=80 a4=90+ a5=77 +% For me, subjectively, the few extra characters that fit aren't worth +% the additional smallness of 8pt. So I'm making the default 9pt. +% +% By the way, for comparison, here's what fits with @example (10pt): +% 8.5x11=71 smallbook=60 a4=75 a5=58 +% +% I wish the USA used A4 paper. +% --karl, 24jan03. + + +% Set up the default fonts, so we can use them for creating boxes. +% +\definetextfontsizexi + +% Define these so they can be easily changed for other fonts. +\def\angleleft{$\langle$} +\def\angleright{$\rangle$} + +% Count depth in font-changes, for error checks +\newcount\fontdepth \fontdepth=0 + +% Fonts for short table of contents. +\setfont\shortcontrm\rmshape{12}{1000}{OT1} +\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12 +\setfont\shortcontsl\slshape{12}{1000}{OT1} +\setfont\shortconttt\ttshape{12}{1000}{OT1TT} + +%% Add scribe-like font environments, plus @l for inline lisp (usually sans +%% serif) and @ii for TeX italic + +% \smartitalic{ARG} outputs arg in italics, followed by an italic correction +% unless the following character is such as not to need one. +\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else + \ptexslash\fi\fi\fi} +\def\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx} +\def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx} + +% like \smartslanted except unconditionally uses \ttsl. +% @var is set to this for defun arguments. +\def\ttslanted#1{{\ttsl #1}\futurelet\next\smartitalicx} + +% like \smartslanted except unconditionally use \sl. We never want +% ttsl for book titles, do we? +\def\cite#1{{\sl #1}\futurelet\next\smartitalicx} + +\let\i=\smartitalic +\let\slanted=\smartslanted +\let\var=\smartslanted +\let\dfn=\smartslanted +\let\emph=\smartitalic + +% @b, explicit bold. +\def\b#1{{\bf #1}} +\let\strong=\b + +% @sansserif, explicit sans. +\def\sansserif#1{{\sf #1}} + +% We can't just use \exhyphenpenalty, because that only has effect at +% the end of a paragraph. Restore normal hyphenation at the end of the +% group within which \nohyphenation is presumably called. +% +\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} +\def\restorehyphenation{\hyphenchar\font = `- } + +% Set sfcode to normal for the chars that usually have another value. +% Can't use plain's \frenchspacing because it uses the `\x notation, and +% sometimes \x has an active definition that messes things up. +% +\catcode`@=11 + \def\plainfrenchspacing{% + \sfcode\dotChar =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m + \sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m + \def\endofsentencespacefactor{1000}% for @. and friends + } + \def\plainnonfrenchspacing{% + \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000 + \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250 + \def\endofsentencespacefactor{3000}% for @. and friends + } +\catcode`@=\other +\def\endofsentencespacefactor{3000}% default + +\def\t#1{% + {\tt \rawbackslash \plainfrenchspacing #1}% + \null +} +\def\samp#1{`\tclose{#1}'\null} +\setfont\keyrm\rmshape{8}{1000}{OT1} +\font\keysy=cmsy9 +\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{% + \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{% + \vbox{\hrule\kern-0.4pt + \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}% + \kern-0.4pt\hrule}% + \kern-.06em\raise0.4pt\hbox{\angleright}}}} +\def\key #1{{\nohyphenation \uppercase{#1}}\null} +% The old definition, with no lozenge: +%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null} +\def\ctrl #1{{\tt \rawbackslash \hat}#1} + +% @file, @option are the same as @samp. +\let\file=\samp +\let\option=\samp + +% @code is a modification of @t, +% which makes spaces the same size as normal in the surrounding text. +\def\tclose#1{% + {% + % Change normal interword space to be same as for the current font. + \spaceskip = \fontdimen2\font + % + % Switch to typewriter. + \tt + % + % But `\ ' produces the large typewriter interword space. + \def\ {{\spaceskip = 0pt{} }}% + % + % Turn off hyphenation. + \nohyphenation + % + \rawbackslash + \plainfrenchspacing + #1% + }% + \null +} + +% We *must* turn on hyphenation at `-' and `_' in @code. +% Otherwise, it is too hard to avoid overfull hboxes +% in the Emacs manual, the Library manual, etc. + +% Unfortunately, TeX uses one parameter (\hyphenchar) to control +% both hyphenation at - and hyphenation within words. +% We must therefore turn them both off (\tclose does that) +% and arrange explicitly to hyphenate at a dash. +% -- rms. +{ + \catcode`\-=\active \catcode`\_=\active + \catcode`\'=\active \catcode`\`=\active + % + \global\def\code{\begingroup + \catcode\rquoteChar=\active \catcode\lquoteChar=\active + \let'\codequoteright \let`\codequoteleft + % + \catcode\dashChar=\active \catcode\underChar=\active + \ifallowcodebreaks + \let-\codedash + \let_\codeunder + \else + \let-\realdash + \let_\realunder + \fi + \codex + } +} + +\def\realdash{-} +\def\codedash{-\discretionary{}{}{}} +\def\codeunder{% + % this is all so @math{@code{var_name}+1} can work. In math mode, _ + % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.) + % will therefore expand the active definition of _, which is us + % (inside @code that is), therefore an endless loop. + \ifusingtt{\ifmmode + \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_. + \else\normalunderscore \fi + \discretionary{}{}{}}% + {\_}% +} +\def\codex #1{\tclose{#1}\endgroup} + +% An additional complication: the above will allow breaks after, e.g., +% each of the four underscores in __typeof__. This is undesirable in +% some manuals, especially if they don't have long identifiers in +% general. @allowcodebreaks provides a way to control this. +% +\newif\ifallowcodebreaks \allowcodebreakstrue + +\def\keywordtrue{true} +\def\keywordfalse{false} + +\parseargdef\allowcodebreaks{% + \def\txiarg{#1}% + \ifx\txiarg\keywordtrue + \allowcodebreakstrue + \else\ifx\txiarg\keywordfalse + \allowcodebreaksfalse + \else + \errhelp = \EMsimple + \errmessage{Unknown @allowcodebreaks option `\txiarg'}% + \fi\fi +} + +% @kbd is like @code, except that if the argument is just one @key command, +% then @kbd has no effect. + +% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), +% `example' (@kbd uses ttsl only inside of @example and friends), +% or `code' (@kbd uses normal tty font always). +\parseargdef\kbdinputstyle{% + \def\txiarg{#1}% + \ifx\txiarg\worddistinct + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}% + \else\ifx\txiarg\wordexample + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}% + \else\ifx\txiarg\wordcode + \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}% + \else + \errhelp = \EMsimple + \errmessage{Unknown @kbdinputstyle option `\txiarg'}% + \fi\fi\fi +} +\def\worddistinct{distinct} +\def\wordexample{example} +\def\wordcode{code} + +% Default is `distinct.' +\kbdinputstyle distinct + +\def\xkey{\key} +\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% +\ifx\one\xkey\ifx\threex\three \key{#2}% +\else{\tclose{\kbdfont\look}}\fi +\else{\tclose{\kbdfont\look}}\fi} + +% For @indicateurl, @env, @command quotes seem unnecessary, so use \code. +\let\indicateurl=\code +\let\env=\code +\let\command=\code + +% @uref (abbreviation for `urlref') takes an optional (comma-separated) +% second argument specifying the text to display and an optional third +% arg as text to display instead of (rather than in addition to) the url +% itself. First (mandatory) arg is the url. Perhaps eventually put in +% a hypertex \special here. +% +\def\uref#1{\douref #1,,,\finish} +\def\douref#1,#2,#3,#4\finish{\begingroup + \unsepspaces + \pdfurl{#1}% + \setbox0 = \hbox{\ignorespaces #3}% + \ifdim\wd0 > 0pt + \unhbox0 % third arg given, show only that + \else + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0 > 0pt + \ifpdf + \unhbox0 % PDF: 2nd arg given, show only it + \else + \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url + \fi + \else + \code{#1}% only url given, so show it + \fi + \fi + \endlink +\endgroup} + +% @url synonym for @uref, since that's how everyone uses it. +% +\let\url=\uref + +% rms does not like angle brackets --karl, 17may97. +% So now @email is just like @uref, unless we are pdf. +% +%\def\email#1{\angleleft{\tt #1}\angleright} +\ifpdf + \def\email#1{\doemail#1,,\finish} + \def\doemail#1,#2,#3\finish{\begingroup + \unsepspaces + \pdfurl{mailto:#1}% + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi + \endlink + \endgroup} +\else + \let\email=\uref +\fi + +% Check if we are currently using a typewriter font. Since all the +% Computer Modern typewriter fonts have zero interword stretch (and +% shrink), and it is reasonable to expect all typewriter fonts to have +% this property, we can check that font parameter. +% +\def\ifmonospace{\ifdim\fontdimen3\font=0pt } + +% Typeset a dimension, e.g., `in' or `pt'. The only reason for the +% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt. +% +\def\dmn#1{\thinspace #1} + +\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par} + +% @l was never documented to mean ``switch to the Lisp font'', +% and it is not used as such in any manual I can find. We need it for +% Polish suppressed-l. --karl, 22sep96. +%\def\l#1{{\li #1}\null} + +% Explicit font changes: @r, @sc, undocumented @ii. +\def\r#1{{\rm #1}} % roman font +\def\sc#1{{\smallcaps#1}} % smallcaps font +\def\ii#1{{\it #1}} % italic font + +% @acronym for "FBI", "NATO", and the like. +% We print this one point size smaller, since it's intended for +% all-uppercase. +% +\def\acronym#1{\doacronym #1,,\finish} +\def\doacronym#1,#2,#3\finish{% + {\selectfonts\lsize #1}% + \def\temp{#2}% + \ifx\temp\empty \else + \space ({\unsepspaces \ignorespaces \temp \unskip})% + \fi +} + +% @abbr for "Comput. J." and the like. +% No font change, but don't do end-of-sentence spacing. +% +\def\abbr#1{\doabbr #1,,\finish} +\def\doabbr#1,#2,#3\finish{% + {\plainfrenchspacing #1}% + \def\temp{#2}% + \ifx\temp\empty \else + \space ({\unsepspaces \ignorespaces \temp \unskip})% + \fi +} + +% @pounds{} is a sterling sign, which Knuth put in the CM italic font. +% +\def\pounds{{\it\$}} + +% @euro{} comes from a separate font, depending on the current style. +% We use the free feym* fonts from the eurosym package by Henrik +% Theiling, which support regular, slanted, bold and bold slanted (and +% "outlined" (blackboard board, sort of) versions, which we don't need). +% It is available from http://www.ctan.org/tex-archive/fonts/eurosym. +% +% Although only regular is the truly official Euro symbol, we ignore +% that. The Euro is designed to be slightly taller than the regular +% font height. +% +% feymr - regular +% feymo - slanted +% feybr - bold +% feybo - bold slanted +% +% There is no good (free) typewriter version, to my knowledge. +% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide. +% Hmm. +% +% Also doesn't work in math. Do we need to do math with euro symbols? +% Hope not. +% +% +\def\euro{{\eurofont e}} +\def\eurofont{% + % We set the font at each command, rather than predefining it in + % \textfonts and the other font-switching commands, so that + % installations which never need the symbol don't have to have the + % font installed. + % + % There is only one designed size (nominal 10pt), so we always scale + % that to the current nominal size. + % + % By the way, simply using "at 1em" works for cmr10 and the like, but + % does not work for cmbx10 and other extended/shrunken fonts. + % + \def\eurosize{\csname\curfontsize nominalsize\endcsname}% + % + \ifx\curfontstyle\bfstylename + % bold: + \font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize + \else + % regular: + \font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize + \fi + \thiseurofont +} + +% Hacks for glyphs from the EC fonts similar to \euro. We don't +% use \let for the aliases, because sometimes we redefine the original +% macro, and the alias should reflect the redefinition. +\def\guillemetleft{{\ecfont \char"13}} +\def\guillemotleft{\guillemetleft} +\def\guillemetright{{\ecfont \char"14}} +\def\guillemotright{\guillemetright} +\def\guilsinglleft{{\ecfont \char"0E}} +\def\guilsinglright{{\ecfont \char"0F}} +\def\quotedblbase{{\ecfont \char"12}} +\def\quotesinglbase{{\ecfont \char"0D}} +% +\def\ecfont{% + % We can't distinguish serif/sanserif and italic/slanted, but this + % is used for crude hacks anyway (like adding French and German + % quotes to documents typeset with CM, where we lose kerning), so + % hopefully nobody will notice/care. + \edef\ecsize{\csname\curfontsize ecsize\endcsname}% + \edef\nominalsize{\csname\curfontsize nominalsize\endcsname}% + \ifx\curfontstyle\bfstylename + % bold: + \font\thisecfont = ecb\ifusingit{i}{x}\ecsize \space at \nominalsize + \else + % regular: + \font\thisecfont = ec\ifusingit{ti}{rm}\ecsize \space at \nominalsize + \fi + \thisecfont +} + +% @registeredsymbol - R in a circle. The font for the R should really +% be smaller yet, but lllsize is the best we can do for now. +% Adapted from the plain.tex definition of \copyright. +% +\def\registeredsymbol{% + $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}% + \hfil\crcr\Orb}}% + }$% +} + +% @textdegree - the normal degrees sign. +% +\def\textdegree{$^\circ$} + +% Laurent Siebenmann reports \Orb undefined with: +% Textures 1.7.7 (preloaded format=plain 93.10.14) (68K) 16 APR 2004 02:38 +% so we'll define it if necessary. +% +\ifx\Orb\undefined +\def\Orb{\mathhexbox20D} +\fi + +% Quotes. +\chardef\quotedblleft="5C +\chardef\quotedblright=`\" +\chardef\quoteleft=`\` +\chardef\quoteright=`\' + + +\message{page headings,} + +\newskip\titlepagetopglue \titlepagetopglue = 1.5in +\newskip\titlepagebottomglue \titlepagebottomglue = 2pc + +% First the title page. Must do @settitle before @titlepage. +\newif\ifseenauthor +\newif\iffinishedtitlepage + +% Do an implicit @contents or @shortcontents after @end titlepage if the +% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage. +% +\newif\ifsetcontentsaftertitlepage + \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue +\newif\ifsetshortcontentsaftertitlepage + \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue + +\parseargdef\shorttitlepage{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% + \endgroup\page\hbox{}\page} + +\envdef\titlepage{% + % Open one extra group, as we want to close it in the middle of \Etitlepage. + \begingroup + \parindent=0pt \textfonts + % Leave some space at the very top of the page. + \vglue\titlepagetopglue + % No rule at page bottom unless we print one at the top with @title. + \finishedtitlepagetrue + % + % Most title ``pages'' are actually two pages long, with space + % at the top of the second. We don't want the ragged left on the second. + \let\oldpage = \page + \def\page{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + \let\page = \oldpage + \page + \null + }% +} + +\def\Etitlepage{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + % It is important to do the page break before ending the group, + % because the headline and footline are only empty inside the group. + % If we use the new definition of \page, we always get a blank page + % after the title page, which we certainly don't want. + \oldpage + \endgroup + % + % Need this before the \...aftertitlepage checks so that if they are + % in effect the toc pages will come out with page numbers. + \HEADINGSon + % + % If they want short, they certainly want long too. + \ifsetshortcontentsaftertitlepage + \shortcontents + \contents + \global\let\shortcontents = \relax + \global\let\contents = \relax + \fi + % + \ifsetcontentsaftertitlepage + \contents + \global\let\contents = \relax + \global\let\shortcontents = \relax + \fi +} + +\def\finishtitlepage{% + \vskip4pt \hrule height 2pt width \hsize + \vskip\titlepagebottomglue + \finishedtitlepagetrue +} + +%%% Macros to be used within @titlepage: + +\let\subtitlerm=\tenrm +\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines} + +\def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines + \let\tt=\authortt} + +\parseargdef\title{% + \checkenv\titlepage + \leftline{\titlefonts\rm #1} + % print a rule at the page bottom also. + \finishedtitlepagefalse + \vskip4pt \hrule height 4pt width \hsize \vskip4pt +} + +\parseargdef\subtitle{% + \checkenv\titlepage + {\subtitlefont \rightline{#1}}% +} + +% @author should come last, but may come many times. +% It can also be used inside @quotation. +% +\parseargdef\author{% + \def\temp{\quotation}% + \ifx\thisenv\temp + \def\quotationauthor{#1}% printed in \Equotation. + \else + \checkenv\titlepage + \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi + {\authorfont \leftline{#1}}% + \fi +} + + +%%% Set up page headings and footings. + +\let\thispage=\folio + +\newtoks\evenheadline % headline on even pages +\newtoks\oddheadline % headline on odd pages +\newtoks\evenfootline % footline on even pages +\newtoks\oddfootline % footline on odd pages + +% Now make TeX use those variables +\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline + \else \the\evenheadline \fi}} +\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline + \else \the\evenfootline \fi}\HEADINGShook} +\let\HEADINGShook=\relax + +% Commands to set those variables. +% For example, this is what @headings on does +% @evenheading @thistitle|@thispage|@thischapter +% @oddheading @thischapter|@thispage|@thistitle +% @evenfooting @thisfile|| +% @oddfooting ||@thisfile + + +\def\evenheading{\parsearg\evenheadingxxx} +\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish} +\def\evenheadingyyy #1\|#2\|#3\|#4\finish{% +\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\def\oddheading{\parsearg\oddheadingxxx} +\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish} +\def\oddheadingyyy #1\|#2\|#3\|#4\finish{% +\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}% + +\def\evenfooting{\parsearg\evenfootingxxx} +\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish} +\def\evenfootingyyy #1\|#2\|#3\|#4\finish{% +\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\def\oddfooting{\parsearg\oddfootingxxx} +\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish} +\def\oddfootingyyy #1\|#2\|#3\|#4\finish{% + \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}% + % + % Leave some space for the footline. Hopefully ok to assume + % @evenfooting will not be used by itself. + \global\advance\pageheight by -12pt + \global\advance\vsize by -12pt +} + +\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}} + +% @evenheadingmarks top \thischapter <- chapter at the top of a page +% @evenheadingmarks bottom \thischapter <- chapter at the bottom of a page +% +% The same set of arguments for: +% +% @oddheadingmarks +% @evenfootingmarks +% @oddfootingmarks +% @everyheadingmarks +% @everyfootingmarks + +\def\evenheadingmarks{\headingmarks{even}{heading}} +\def\oddheadingmarks{\headingmarks{odd}{heading}} +\def\evenfootingmarks{\headingmarks{even}{footing}} +\def\oddfootingmarks{\headingmarks{odd}{footing}} +\def\everyheadingmarks#1 {\headingmarks{even}{heading}{#1} + \headingmarks{odd}{heading}{#1} } +\def\everyfootingmarks#1 {\headingmarks{even}{footing}{#1} + \headingmarks{odd}{footing}{#1} } +% #1 = even/odd, #2 = heading/footing, #3 = top/bottom. +\def\headingmarks#1#2#3 {% + \expandafter\let\expandafter\temp \csname get#3headingmarks\endcsname + \global\expandafter\let\csname get#1#2marks\endcsname \temp +} + +\everyheadingmarks bottom +\everyfootingmarks bottom + +% @headings double turns headings on for double-sided printing. +% @headings single turns headings on for single-sided printing. +% @headings off turns them off. +% @headings on same as @headings double, retained for compatibility. +% @headings after turns on double-sided headings after this page. +% @headings doubleafter turns on double-sided headings after this page. +% @headings singleafter turns on single-sided headings after this page. +% By default, they are off at the start of a document, +% and turned `on' after @end titlepage. + +\def\headings #1 {\csname HEADINGS#1\endcsname} + +\def\HEADINGSoff{% +\global\evenheadline={\hfil} \global\evenfootline={\hfil} +\global\oddheadline={\hfil} \global\oddfootline={\hfil}} +\HEADINGSoff +% When we turn headings on, set the page number to 1. +% For double-sided printing, put current file name in lower left corner, +% chapter name on inside top of right hand pages, document +% title on inside top of left hand pages, and page numbers on outside top +% edge of all pages. +\def\HEADINGSdouble{% +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chapoddpage +} +\let\contentsalignmacro = \chappager + +% For single-sided printing, chapter title goes across top left of page, +% page number on top right. +\def\HEADINGSsingle{% +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chappager +} +\def\HEADINGSon{\HEADINGSdouble} + +\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex} +\let\HEADINGSdoubleafter=\HEADINGSafter +\def\HEADINGSdoublex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chapoddpage +} + +\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} +\def\HEADINGSsinglex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chappager +} + +% Subroutines used in generating headings +% This produces Day Month Year style of output. +% Only define if not already defined, in case a txi-??.tex file has set +% up a different format (e.g., txi-cs.tex does this). +\ifx\today\undefined +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} +\fi + +% @settitle line... specifies the title of the document, for headings. +% It generates no output of its own. +\def\thistitle{\putwordNoTitle} +\def\settitle{\parsearg{\gdef\thistitle}} + + +\message{tables,} +% Tables -- @table, @ftable, @vtable, @item(x). + +% default indentation of table text +\newdimen\tableindent \tableindent=.8in +% default indentation of @itemize and @enumerate text +\newdimen\itemindent \itemindent=.3in +% margin between end of table item and start of table text. +\newdimen\itemmargin \itemmargin=.1in + +% used internally for \itemindent minus \itemmargin +\newdimen\itemmax + +% Note @table, @ftable, and @vtable define @item, @itemx, etc., with +% these defs. +% They also define \itemindex +% to index the item name in whatever manner is desired (perhaps none). + +\newif\ifitemxneedsnegativevskip + +\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi} + +\def\internalBitem{\smallbreak \parsearg\itemzzz} +\def\internalBitemx{\itemxpar \parsearg\itemzzz} + +\def\itemzzz #1{\begingroup % + \advance\hsize by -\rightskip + \advance\hsize by -\tableindent + \setbox0=\hbox{\itemindicate{#1}}% + \itemindex{#1}% + \nobreak % This prevents a break before @itemx. + % + % If the item text does not fit in the space we have, put it on a line + % by itself, and do not allow a page break either before or after that + % line. We do not start a paragraph here because then if the next + % command is, e.g., @kindex, the whatsit would get put into the + % horizontal list on a line by itself, resulting in extra blank space. + \ifdim \wd0>\itemmax + % + % Make this a paragraph so we get the \parskip glue and wrapping, + % but leave it ragged-right. + \begingroup + \advance\leftskip by-\tableindent + \advance\hsize by\tableindent + \advance\rightskip by0pt plus1fil + \leavevmode\unhbox0\par + \endgroup + % + % We're going to be starting a paragraph, but we don't want the + % \parskip glue -- logically it's part of the @item we just started. + \nobreak \vskip-\parskip + % + % Stop a page break at the \parskip glue coming up. However, if + % what follows is an environment such as @example, there will be no + % \parskip glue; then the negative vskip we just inserted would + % cause the example and the item to crash together. So we use this + % bizarre value of 10001 as a signal to \aboveenvbreak to insert + % \parskip glue after all. Section titles are handled this way also. + % + \penalty 10001 + \endgroup + \itemxneedsnegativevskipfalse + \else + % The item text fits into the space. Start a paragraph, so that the + % following text (if any) will end up on the same line. + \noindent + % Do this with kerns and \unhbox so that if there is a footnote in + % the item text, it can migrate to the main vertical list and + % eventually be printed. + \nobreak\kern-\tableindent + \dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0 + \unhbox0 + \nobreak\kern\dimen0 + \endgroup + \itemxneedsnegativevskiptrue + \fi +} + +\def\item{\errmessage{@item while not in a list environment}} +\def\itemx{\errmessage{@itemx while not in a list environment}} + +% @table, @ftable, @vtable. +\envdef\table{% + \let\itemindex\gobble + \tablecheck{table}% +} +\envdef\ftable{% + \def\itemindex ##1{\doind {fn}{\code{##1}}}% + \tablecheck{ftable}% +} +\envdef\vtable{% + \def\itemindex ##1{\doind {vr}{\code{##1}}}% + \tablecheck{vtable}% +} +\def\tablecheck#1{% + \ifnum \the\catcode`\^^M=\active + \endgroup + \errmessage{This command won't work in this context; perhaps the problem is + that we are \inenvironment\thisenv}% + \def\next{\doignore{#1}}% + \else + \let\next\tablex + \fi + \next +} +\def\tablex#1{% + \def\itemindicate{#1}% + \parsearg\tabley +} +\def\tabley#1{% + {% + \makevalueexpandable + \edef\temp{\noexpand\tablez #1\space\space\space}% + \expandafter + }\temp \endtablez +} +\def\tablez #1 #2 #3 #4\endtablez{% + \aboveenvbreak + \ifnum 0#1>0 \advance \leftskip by #1\mil \fi + \ifnum 0#2>0 \tableindent=#2\mil \fi + \ifnum 0#3>0 \advance \rightskip by #3\mil \fi + \itemmax=\tableindent + \advance \itemmax by -\itemmargin + \advance \leftskip by \tableindent + \exdentamount=\tableindent + \parindent = 0pt + \parskip = \smallskipamount + \ifdim \parskip=0pt \parskip=2pt \fi + \let\item = \internalBitem + \let\itemx = \internalBitemx +} +\def\Etable{\endgraf\afterenvbreak} +\let\Eftable\Etable +\let\Evtable\Etable +\let\Eitemize\Etable +\let\Eenumerate\Etable + +% This is the counter used by @enumerate, which is really @itemize + +\newcount \itemno + +\envdef\itemize{\parsearg\doitemize} + +\def\doitemize#1{% + \aboveenvbreak + \itemmax=\itemindent + \advance\itemmax by -\itemmargin + \advance\leftskip by \itemindent + \exdentamount=\itemindent + \parindent=0pt + \parskip=\smallskipamount + \ifdim\parskip=0pt \parskip=2pt \fi + \def\itemcontents{#1}% + % @itemize with no arg is equivalent to @itemize @bullet. + \ifx\itemcontents\empty\def\itemcontents{\bullet}\fi + \let\item=\itemizeitem +} + +% Definition of @item while inside @itemize and @enumerate. +% +\def\itemizeitem{% + \advance\itemno by 1 % for enumerations + {\let\par=\endgraf \smallbreak}% reasonable place to break + {% + % If the document has an @itemize directly after a section title, a + % \nobreak will be last on the list, and \sectionheading will have + % done a \vskip-\parskip. In that case, we don't want to zero + % parskip, or the item text will crash with the heading. On the + % other hand, when there is normal text preceding the item (as there + % usually is), we do want to zero parskip, or there would be too much + % space. In that case, we won't have a \nobreak before. At least + % that's the theory. + \ifnum\lastpenalty<10000 \parskip=0in \fi + \noindent + \hbox to 0pt{\hss \itemcontents \kern\itemmargin}% + \vadjust{\penalty 1200}}% not good to break after first line of item. + \flushcr +} + +% \splitoff TOKENS\endmark defines \first to be the first token in +% TOKENS, and \rest to be the remainder. +% +\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% + +% Allow an optional argument of an uppercase letter, lowercase letter, +% or number, to specify the first label in the enumerated list. No +% argument is the same as `1'. +% +\envparseargdef\enumerate{\enumeratey #1 \endenumeratey} +\def\enumeratey #1 #2\endenumeratey{% + % If we were given no argument, pretend we were given `1'. + \def\thearg{#1}% + \ifx\thearg\empty \def\thearg{1}\fi + % + % Detect if the argument is a single token. If so, it might be a + % letter. Otherwise, the only valid thing it can be is a number. + % (We will always have one token, because of the test we just made. + % This is a good thing, since \splitoff doesn't work given nothing at + % all -- the first parameter is undelimited.) + \expandafter\splitoff\thearg\endmark + \ifx\rest\empty + % Only one token in the argument. It could still be anything. + % A ``lowercase letter'' is one whose \lccode is nonzero. + % An ``uppercase letter'' is one whose \lccode is both nonzero, and + % not equal to itself. + % Otherwise, we assume it's a number. + % + % We need the \relax at the end of the \ifnum lines to stop TeX from + % continuing to look for a <number>. + % + \ifnum\lccode\expandafter`\thearg=0\relax + \numericenumerate % a number (we hope) + \else + % It's a letter. + \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax + \lowercaseenumerate % lowercase letter + \else + \uppercaseenumerate % uppercase letter + \fi + \fi + \else + % Multiple tokens in the argument. We hope it's a number. + \numericenumerate + \fi +} + +% An @enumerate whose labels are integers. The starting integer is +% given in \thearg. +% +\def\numericenumerate{% + \itemno = \thearg + \startenumeration{\the\itemno}% +} + +% The starting (lowercase) letter is in \thearg. +\def\lowercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more lowercase letters in @enumerate; get a bigger + alphabet}% + \fi + \char\lccode\itemno + }% +} + +% The starting (uppercase) letter is in \thearg. +\def\uppercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more uppercase letters in @enumerate; get a bigger + alphabet} + \fi + \char\uccode\itemno + }% +} + +% Call \doitemize, adding a period to the first argument and supplying the +% common last two arguments. Also subtract one from the initial value in +% \itemno, since @item increments \itemno. +% +\def\startenumeration#1{% + \advance\itemno by -1 + \doitemize{#1.}\flushcr +} + +% @alphaenumerate and @capsenumerate are abbreviations for giving an arg +% to @enumerate. +% +\def\alphaenumerate{\enumerate{a}} +\def\capsenumerate{\enumerate{A}} +\def\Ealphaenumerate{\Eenumerate} +\def\Ecapsenumerate{\Eenumerate} + + +% @multitable macros +% Amy Hendrickson, 8/18/94, 3/6/96 +% +% @multitable ... @end multitable will make as many columns as desired. +% Contents of each column will wrap at width given in preamble. Width +% can be specified either with sample text given in a template line, +% or in percent of \hsize, the current width of text on page. + +% Table can continue over pages but will only break between lines. + +% To make preamble: +% +% Either define widths of columns in terms of percent of \hsize: +% @multitable @columnfractions .25 .3 .45 +% @item ... +% +% Numbers following @columnfractions are the percent of the total +% current hsize to be used for each column. You may use as many +% columns as desired. + + +% Or use a template: +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item ... +% using the widest term desired in each column. + +% Each new table line starts with @item, each subsequent new column +% starts with @tab. Empty columns may be produced by supplying @tab's +% with nothing between them for as many times as empty columns are needed, +% ie, @tab@tab@tab will produce two empty columns. + +% @item, @tab do not need to be on their own lines, but it will not hurt +% if they are. + +% Sample multitable: + +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item first col stuff @tab second col stuff @tab third col +% @item +% first col stuff +% @tab +% second col stuff +% @tab +% third col +% @item first col stuff @tab second col stuff +% @tab Many paragraphs of text may be used in any column. +% +% They will wrap at the width determined by the template. +% @item@tab@tab This will be in third column. +% @end multitable + +% Default dimensions may be reset by user. +% @multitableparskip is vertical space between paragraphs in table. +% @multitableparindent is paragraph indent in table. +% @multitablecolmargin is horizontal space to be left between columns. +% @multitablelinespace is space to leave between table items, baseline +% to baseline. +% 0pt means it depends on current normal line spacing. +% +\newskip\multitableparskip +\newskip\multitableparindent +\newdimen\multitablecolspace +\newskip\multitablelinespace +\multitableparskip=0pt +\multitableparindent=6pt +\multitablecolspace=12pt +\multitablelinespace=0pt + +% Macros used to set up halign preamble: +% +\let\endsetuptable\relax +\def\xendsetuptable{\endsetuptable} +\let\columnfractions\relax +\def\xcolumnfractions{\columnfractions} +\newif\ifsetpercent + +% #1 is the @columnfraction, usually a decimal number like .5, but might +% be just 1. We just use it, whatever it is. +% +\def\pickupwholefraction#1 {% + \global\advance\colcount by 1 + \expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}% + \setuptable +} + +\newcount\colcount +\def\setuptable#1{% + \def\firstarg{#1}% + \ifx\firstarg\xendsetuptable + \let\go = \relax + \else + \ifx\firstarg\xcolumnfractions + \global\setpercenttrue + \else + \ifsetpercent + \let\go\pickupwholefraction + \else + \global\advance\colcount by 1 + \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a + % separator; typically that is always in the input, anyway. + \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% + \fi + \fi + \ifx\go\pickupwholefraction + % Put the argument back for the \pickupwholefraction call, so + % we'll always have a period there to be parsed. + \def\go{\pickupwholefraction#1}% + \else + \let\go = \setuptable + \fi% + \fi + \go +} + +% multitable-only commands. +% +% @headitem starts a heading row, which we typeset in bold. +% Assignments have to be global since we are inside the implicit group +% of an alignment entry. Note that \everycr resets \everytab. +\def\headitem{\checkenv\multitable \crcr \global\everytab={\bf}\the\everytab}% +% +% A \tab used to include \hskip1sp. But then the space in a template +% line is not enough. That is bad. So let's go back to just `&' until +% we encounter the problem it was intended to solve again. +% --karl, nathan@acm.org, 20apr99. +\def\tab{\checkenv\multitable &\the\everytab}% + +% @multitable ... @end multitable definitions: +% +\newtoks\everytab % insert after every tab. +% +\envdef\multitable{% + \vskip\parskip + \startsavinginserts + % + % @item within a multitable starts a normal row. + % We use \def instead of \let so that if one of the multitable entries + % contains an @itemize, we don't choke on the \item (seen as \crcr aka + % \endtemplate) expanding \doitemize. + \def\item{\crcr}% + % + \tolerance=9500 + \hbadness=9500 + \setmultitablespacing + \parskip=\multitableparskip + \parindent=\multitableparindent + \overfullrule=0pt + \global\colcount=0 + % + \everycr = {% + \noalign{% + \global\everytab={}% + \global\colcount=0 % Reset the column counter. + % Check for saved footnotes, etc. + \checkinserts + % Keeps underfull box messages off when table breaks over pages. + %\filbreak + % Maybe so, but it also creates really weird page breaks when the + % table breaks over pages. Wouldn't \vfil be better? Wait until the + % problem manifests itself, so it can be fixed for real --karl. + }% + }% + % + \parsearg\domultitable +} +\def\domultitable#1{% + % To parse everything between @multitable and @item: + \setuptable#1 \endsetuptable + % + % This preamble sets up a generic column definition, which will + % be used as many times as user calls for columns. + % \vtop will set a single line and will also let text wrap and + % continue for many paragraphs if desired. + \halign\bgroup &% + \global\advance\colcount by 1 + \multistrut + \vtop{% + % Use the current \colcount to find the correct column width: + \hsize=\expandafter\csname col\the\colcount\endcsname + % + % In order to keep entries from bumping into each other + % we will add a \leftskip of \multitablecolspace to all columns after + % the first one. + % + % If a template has been used, we will add \multitablecolspace + % to the width of each template entry. + % + % If the user has set preamble in terms of percent of \hsize we will + % use that dimension as the width of the column, and the \leftskip + % will keep entries from bumping into each other. Table will start at + % left margin and final column will justify at right margin. + % + % Make sure we don't inherit \rightskip from the outer environment. + \rightskip=0pt + \ifnum\colcount=1 + % The first column will be indented with the surrounding text. + \advance\hsize by\leftskip + \else + \ifsetpercent \else + % If user has not set preamble in terms of percent of \hsize + % we will advance \hsize by \multitablecolspace. + \advance\hsize by \multitablecolspace + \fi + % In either case we will make \leftskip=\multitablecolspace: + \leftskip=\multitablecolspace + \fi + % Ignoring space at the beginning and end avoids an occasional spurious + % blank line, when TeX decides to break the line at the space before the + % box from the multistrut, so the strut ends up on a line by itself. + % For example: + % @multitable @columnfractions .11 .89 + % @item @code{#} + % @tab Legal holiday which is valid in major parts of the whole country. + % Is automatically provided with highlighting sequences respectively + % marking characters. + \noindent\ignorespaces##\unskip\multistrut + }\cr +} +\def\Emultitable{% + \crcr + \egroup % end the \halign + \global\setpercentfalse +} + +\def\setmultitablespacing{% + \def\multistrut{\strut}% just use the standard line spacing + % + % Compute \multitablelinespace (if not defined by user) for use in + % \multitableparskip calculation. We used define \multistrut based on + % this, but (ironically) that caused the spacing to be off. + % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100. +\ifdim\multitablelinespace=0pt +\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip +\global\advance\multitablelinespace by-\ht0 +\fi +%% Test to see if parskip is larger than space between lines of +%% table. If not, do nothing. +%% If so, set to same dimension as multitablelinespace. +\ifdim\multitableparskip>\multitablelinespace +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi% +\ifdim\multitableparskip=0pt +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi} + + +\message{conditionals,} + +% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext, +% @ifnotxml always succeed. They currently do nothing; we don't +% attempt to check whether the conditionals are properly nested. But we +% have to remember that they are conditionals, so that @end doesn't +% attempt to close an environment group. +% +\def\makecond#1{% + \expandafter\let\csname #1\endcsname = \relax + \expandafter\let\csname iscond.#1\endcsname = 1 +} +\makecond{iftex} +\makecond{ifnotdocbook} +\makecond{ifnothtml} +\makecond{ifnotinfo} +\makecond{ifnotplaintext} +\makecond{ifnotxml} + +% Ignore @ignore, @ifhtml, @ifinfo, and the like. +% +\def\direntry{\doignore{direntry}} +\def\documentdescription{\doignore{documentdescription}} +\def\docbook{\doignore{docbook}} +\def\html{\doignore{html}} +\def\ifdocbook{\doignore{ifdocbook}} +\def\ifhtml{\doignore{ifhtml}} +\def\ifinfo{\doignore{ifinfo}} +\def\ifnottex{\doignore{ifnottex}} +\def\ifplaintext{\doignore{ifplaintext}} +\def\ifxml{\doignore{ifxml}} +\def\ignore{\doignore{ignore}} +\def\menu{\doignore{menu}} +\def\xml{\doignore{xml}} + +% Ignore text until a line `@end #1', keeping track of nested conditionals. +% +% A count to remember the depth of nesting. +\newcount\doignorecount + +\def\doignore#1{\begingroup + % Scan in ``verbatim'' mode: + \obeylines + \catcode`\@ = \other + \catcode`\{ = \other + \catcode`\} = \other + % + % Make sure that spaces turn into tokens that match what \doignoretext wants. + \spaceisspace + % + % Count number of #1's that we've seen. + \doignorecount = 0 + % + % Swallow text until we reach the matching `@end #1'. + \dodoignore{#1}% +} + +{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source. + \obeylines % + % + \gdef\dodoignore#1{% + % #1 contains the command name as a string, e.g., `ifinfo'. + % + % Define a command to find the next `@end #1'. + \long\def\doignoretext##1^^M@end #1{% + \doignoretextyyy##1^^M@#1\_STOP_}% + % + % And this command to find another #1 command, at the beginning of a + % line. (Otherwise, we would consider a line `@c @ifset', for + % example, to count as an @ifset for nesting.) + \long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}% + % + % And now expand that command. + \doignoretext ^^M% + }% +} + +\def\doignoreyyy#1{% + \def\temp{#1}% + \ifx\temp\empty % Nothing found. + \let\next\doignoretextzzz + \else % Found a nested condition, ... + \advance\doignorecount by 1 + \let\next\doignoretextyyy % ..., look for another. + % If we're here, #1 ends with ^^M\ifinfo (for example). + \fi + \next #1% the token \_STOP_ is present just after this macro. +} + +% We have to swallow the remaining "\_STOP_". +% +\def\doignoretextzzz#1{% + \ifnum\doignorecount = 0 % We have just found the outermost @end. + \let\next\enddoignore + \else % Still inside a nested condition. + \advance\doignorecount by -1 + \let\next\doignoretext % Look for the next @end. + \fi + \next +} + +% Finish off ignored text. +{ \obeylines% + % Ignore anything after the last `@end #1'; this matters in verbatim + % environments, where otherwise the newline after an ignored conditional + % would result in a blank line in the output. + \gdef\enddoignore#1^^M{\endgroup\ignorespaces}% +} + + +% @set VAR sets the variable VAR to an empty value. +% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. +% +% Since we want to separate VAR from REST-OF-LINE (which might be +% empty), we can't just use \parsearg; we have to insert a space of our +% own to delimit the rest of the line, and then take it out again if we +% didn't need it. +% We rely on the fact that \parsearg sets \catcode`\ =10. +% +\parseargdef\set{\setyyy#1 \endsetyyy} +\def\setyyy#1 #2\endsetyyy{% + {% + \makevalueexpandable + \def\temp{#2}% + \edef\next{\gdef\makecsname{SET#1}}% + \ifx\temp\empty + \next{}% + \else + \setzzz#2\endsetzzz + \fi + }% +} +% Remove the trailing space \setxxx inserted. +\def\setzzz#1 \endsetzzz{\next{#1}} + +% @clear VAR clears (i.e., unsets) the variable VAR. +% +\parseargdef\clear{% + {% + \makevalueexpandable + \global\expandafter\let\csname SET#1\endcsname=\relax + }% +} + +% @value{foo} gets the text saved in variable foo. +\def\value{\begingroup\makevalueexpandable\valuexxx} +\def\valuexxx#1{\expandablevalue{#1}\endgroup} +{ + \catcode`\- = \active \catcode`\_ = \active + % + \gdef\makevalueexpandable{% + \let\value = \expandablevalue + % We don't want these characters active, ... + \catcode`\-=\other \catcode`\_=\other + % ..., but we might end up with active ones in the argument if + % we're called from @code, as @code{@value{foo-bar_}}, though. + % So \let them to their normal equivalents. + \let-\realdash \let_\normalunderscore + } +} + +% We have this subroutine so that we can handle at least some @value's +% properly in indexes (we call \makevalueexpandable in \indexdummies). +% The command has to be fully expandable (if the variable is set), since +% the result winds up in the index file. This means that if the +% variable's value contains other Texinfo commands, it's almost certain +% it will fail (although perhaps we could fix that with sufficient work +% to do a one-level expansion on the result, instead of complete). +% +\def\expandablevalue#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + {[No value for ``#1'']}% + \message{Variable `#1', used in @value, is not set.}% + \else + \csname SET#1\endcsname + \fi +} + +% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined +% with @set. +% +% To get special treatment of `@end ifset,' call \makeond and the redefine. +% +\makecond{ifset} +\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}} +\def\doifset#1#2{% + {% + \makevalueexpandable + \let\next=\empty + \expandafter\ifx\csname SET#2\endcsname\relax + #1% If not set, redefine \next. + \fi + \expandafter + }\next +} +\def\ifsetfail{\doignore{ifset}} + +% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been +% defined with @set, or has been undefined with @clear. +% +% The `\else' inside the `\doifset' parameter is a trick to reuse the +% above code: if the variable is not set, do nothing, if it is set, +% then redefine \next to \ifclearfail. +% +\makecond{ifclear} +\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}} +\def\ifclearfail{\doignore{ifclear}} + +% @dircategory CATEGORY -- specify a category of the dir file +% which this file should belong to. Ignore this in TeX. +\let\dircategory=\comment + +% @defininfoenclose. +\let\definfoenclose=\comment + + +\message{indexing,} +% Index generation facilities + +% Define \newwrite to be identical to plain tex's \newwrite +% except not \outer, so it can be used within macros and \if's. +\edef\newwrite{\makecsname{ptexnewwrite}} + +% \newindex {foo} defines an index named foo. +% It automatically defines \fooindex such that +% \fooindex ...rest of line... puts an entry in the index foo. +% It also defines \fooindfile to be the number of the output channel for +% the file that accumulates this index. The file's extension is foo. +% The name of an index should be no more than 2 characters long +% for the sake of vms. +% +\def\newindex#1{% + \iflinks + \expandafter\newwrite \csname#1indfile\endcsname + \openout \csname#1indfile\endcsname \jobname.#1 % Open the file + \fi + \expandafter\xdef\csname#1index\endcsname{% % Define @#1index + \noexpand\doindex{#1}} +} + +% @defindex foo == \newindex{foo} +% +\def\defindex{\parsearg\newindex} + +% Define @defcodeindex, like @defindex except put all entries in @code. +% +\def\defcodeindex{\parsearg\newcodeindex} +% +\def\newcodeindex#1{% + \iflinks + \expandafter\newwrite \csname#1indfile\endcsname + \openout \csname#1indfile\endcsname \jobname.#1 + \fi + \expandafter\xdef\csname#1index\endcsname{% + \noexpand\docodeindex{#1}}% +} + + +% @synindex foo bar makes index foo feed into index bar. +% Do this instead of @defindex foo if you don't want it as a separate index. +% +% @syncodeindex foo bar similar, but put all entries made for index foo +% inside @code. +% +\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}} +\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}} + +% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo), +% #3 the target index (bar). +\def\dosynindex#1#2#3{% + % Only do \closeout if we haven't already done it, else we'll end up + % closing the target index. + \expandafter \ifx\csname donesynindex#2\endcsname \undefined + % The \closeout helps reduce unnecessary open files; the limit on the + % Acorn RISC OS is a mere 16 files. + \expandafter\closeout\csname#2indfile\endcsname + \expandafter\let\csname\donesynindex#2\endcsname = 1 + \fi + % redefine \fooindfile: + \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname + \expandafter\let\csname#2indfile\endcsname=\temp + % redefine \fooindex: + \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}% +} + +% Define \doindex, the driver for all \fooindex macros. +% Argument #1 is generated by the calling \fooindex macro, +% and it is "foo", the name of the index. + +% \doindex just uses \parsearg; it calls \doind for the actual work. +% This is because \doind is more useful to call from other macros. + +% There is also \dosubind {index}{topic}{subtopic} +% which makes an entry in a two-level index such as the operation index. + +\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} +\def\singleindexer #1{\doind{\indexname}{#1}} + +% like the previous two, but they put @code around the argument. +\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} +\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} + +% Take care of Texinfo commands that can appear in an index entry. +% Since there are some commands we want to expand, and others we don't, +% we have to laboriously prevent expansion for those that we don't. +% +\def\indexdummies{% + \escapechar = `\\ % use backslash in output files. + \def\@{@}% change to @@ when we switch to @ as escape char in index files. + \def\ {\realbackslash\space }% + % + % Need these in case \tex is in effect and \{ is a \delimiter again. + % But can't use \lbracecmd and \rbracecmd because texindex assumes + % braces and backslashes are used only as delimiters. + \let\{ = \mylbrace + \let\} = \myrbrace + % + % I don't entirely understand this, but when an index entry is + % generated from a macro call, the \endinput which \scanmacro inserts + % causes processing to be prematurely terminated. This is, + % apparently, because \indexsorttmp is fully expanded, and \endinput + % is an expandable command. The redefinition below makes \endinput + % disappear altogether for that purpose -- although logging shows that + % processing continues to some further point. On the other hand, it + % seems \endinput does not hurt in the printed index arg, since that + % is still getting written without apparent harm. + % + % Sample source (mac-idx3.tex, reported by Graham Percival to + % help-texinfo, 22may06): + % @macro funindex {WORD} + % @findex xyz + % @end macro + % ... + % @funindex commtest + % + % The above is not enough to reproduce the bug, but it gives the flavor. + % + % Sample whatsit resulting: + % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}} + % + % So: + \let\endinput = \empty + % + % Do the redefinitions. + \commondummies +} + +% For the aux and toc files, @ is the escape character. So we want to +% redefine everything using @ as the escape character (instead of +% \realbackslash, still used for index files). When everything uses @, +% this will be simpler. +% +\def\atdummies{% + \def\@{@@}% + \def\ {@ }% + \let\{ = \lbraceatcmd + \let\} = \rbraceatcmd + % + % Do the redefinitions. + \commondummies + \otherbackslash +} + +% Called from \indexdummies and \atdummies. +% +\def\commondummies{% + % + % \definedummyword defines \#1 as \string\#1\space, thus effectively + % preventing its expansion. This is used only for control% words, + % not control letters, because the \space would be incorrect for + % control characters, but is needed to separate the control word + % from whatever follows. + % + % For control letters, we have \definedummyletter, which omits the + % space. + % + % These can be used both for control words that take an argument and + % those that do not. If it is followed by {arg} in the input, then + % that will dutifully get written to the index (or wherever). + % + \def\definedummyword ##1{\def##1{\string##1\space}}% + \def\definedummyletter##1{\def##1{\string##1}}% + \let\definedummyaccent\definedummyletter + % + \commondummiesnofonts + % + \definedummyletter\_% + % + % Non-English letters. + \definedummyword\AA + \definedummyword\AE + \definedummyword\L + \definedummyword\OE + \definedummyword\O + \definedummyword\aa + \definedummyword\ae + \definedummyword\l + \definedummyword\oe + \definedummyword\o + \definedummyword\ss + \definedummyword\exclamdown + \definedummyword\questiondown + \definedummyword\ordf + \definedummyword\ordm + % + % Although these internal commands shouldn't show up, sometimes they do. + \definedummyword\bf + \definedummyword\gtr + \definedummyword\hat + \definedummyword\less + \definedummyword\sf + \definedummyword\sl + \definedummyword\tclose + \definedummyword\tt + % + \definedummyword\LaTeX + \definedummyword\TeX + % + % Assorted special characters. + \definedummyword\bullet + \definedummyword\comma + \definedummyword\copyright + \definedummyword\registeredsymbol + \definedummyword\dots + \definedummyword\enddots + \definedummyword\equiv + \definedummyword\error + \definedummyword\euro + \definedummyword\guillemetleft + \definedummyword\guillemetright + \definedummyword\guilsinglleft + \definedummyword\guilsinglright + \definedummyword\expansion + \definedummyword\minus + \definedummyword\pounds + \definedummyword\point + \definedummyword\print + \definedummyword\quotedblbase + \definedummyword\quotedblleft + \definedummyword\quotedblright + \definedummyword\quoteleft + \definedummyword\quoteright + \definedummyword\quotesinglbase + \definedummyword\result + \definedummyword\textdegree + % + % We want to disable all macros so that they are not expanded by \write. + \macrolist + % + \normalturnoffactive + % + % Handle some cases of @value -- where it does not contain any + % (non-fully-expandable) commands. + \makevalueexpandable +} + +% \commondummiesnofonts: common to \commondummies and \indexnofonts. +% +\def\commondummiesnofonts{% + % Control letters and accents. + \definedummyletter\!% + \definedummyaccent\"% + \definedummyaccent\'% + \definedummyletter\*% + \definedummyaccent\,% + \definedummyletter\.% + \definedummyletter\/% + \definedummyletter\:% + \definedummyaccent\=% + \definedummyletter\?% + \definedummyaccent\^% + \definedummyaccent\`% + \definedummyaccent\~% + \definedummyword\u + \definedummyword\v + \definedummyword\H + \definedummyword\dotaccent + \definedummyword\ringaccent + \definedummyword\tieaccent + \definedummyword\ubaraccent + \definedummyword\udotaccent + \definedummyword\dotless + % + % Texinfo font commands. + \definedummyword\b + \definedummyword\i + \definedummyword\r + \definedummyword\sc + \definedummyword\t + % + % Commands that take arguments. + \definedummyword\acronym + \definedummyword\cite + \definedummyword\code + \definedummyword\command + \definedummyword\dfn + \definedummyword\emph + \definedummyword\env + \definedummyword\file + \definedummyword\kbd + \definedummyword\key + \definedummyword\math + \definedummyword\option + \definedummyword\pxref + \definedummyword\ref + \definedummyword\samp + \definedummyword\strong + \definedummyword\tie + \definedummyword\uref + \definedummyword\url + \definedummyword\var + \definedummyword\verb + \definedummyword\w + \definedummyword\xref +} + +% \indexnofonts is used when outputting the strings to sort the index +% by, and when constructing control sequence names. It eliminates all +% control sequences and just writes whatever the best ASCII sort string +% would be for a given command (usually its argument). +% +\def\indexnofonts{% + % Accent commands should become @asis. + \def\definedummyaccent##1{\let##1\asis}% + % We can just ignore other control letters. + \def\definedummyletter##1{\let##1\empty}% + % Hopefully, all control words can become @asis. + \let\definedummyword\definedummyaccent + % + \commondummiesnofonts + % + % Don't no-op \tt, since it isn't a user-level command + % and is used in the definitions of the active chars like <, >, |, etc. + % Likewise with the other plain tex font commands. + %\let\tt=\asis + % + \def\ { }% + \def\@{@}% + % how to handle braces? + \def\_{\normalunderscore}% + % + % Non-English letters. + \def\AA{AA}% + \def\AE{AE}% + \def\L{L}% + \def\OE{OE}% + \def\O{O}% + \def\aa{aa}% + \def\ae{ae}% + \def\l{l}% + \def\oe{oe}% + \def\o{o}% + \def\ss{ss}% + \def\exclamdown{!}% + \def\questiondown{?}% + \def\ordf{a}% + \def\ordm{o}% + % + \def\LaTeX{LaTeX}% + \def\TeX{TeX}% + % + % Assorted special characters. + % (The following {} will end up in the sort string, but that's ok.) + \def\bullet{bullet}% + \def\comma{,}% + \def\copyright{copyright}% + \def\registeredsymbol{R}% + \def\dots{...}% + \def\enddots{...}% + \def\equiv{==}% + \def\error{error}% + \def\euro{euro}% + \def\guillemetleft{<<}% + \def\guillemetright{>>}% + \def\guilsinglleft{<}% + \def\guilsinglright{>}% + \def\expansion{==>}% + \def\minus{-}% + \def\pounds{pounds}% + \def\point{.}% + \def\print{-|}% + \def\quotedblbase{"}% + \def\quotedblleft{"}% + \def\quotedblright{"}% + \def\quoteleft{`}% + \def\quoteright{'}% + \def\quotesinglbase{,}% + \def\result{=>}% + \def\textdegree{degrees}% + % + % We need to get rid of all macros, leaving only the arguments (if present). + % Of course this is not nearly correct, but it is the best we can do for now. + % makeinfo does not expand macros in the argument to @deffn, which ends up + % writing an index entry, and texindex isn't prepared for an index sort entry + % that starts with \. + % + % Since macro invocations are followed by braces, we can just redefine them + % to take a single TeX argument. The case of a macro invocation that + % goes to end-of-line is not handled. + % + \macrolist +} + +\let\indexbackslash=0 %overridden during \printindex. +\let\SETmarginindex=\relax % put index entries in margin (undocumented)? + +% Most index entries go through here, but \dosubind is the general case. +% #1 is the index name, #2 is the entry text. +\def\doind#1#2{\dosubind{#1}{#2}{}} + +% Workhorse for all \fooindexes. +% #1 is name of index, #2 is stuff to put there, #3 is subentry -- +% empty if called from \doind, as we usually are (the main exception +% is with most defuns, which call us directly). +% +\def\dosubind#1#2#3{% + \iflinks + {% + % Store the main index entry text (including the third arg). + \toks0 = {#2}% + % If third arg is present, precede it with a space. + \def\thirdarg{#3}% + \ifx\thirdarg\empty \else + \toks0 = \expandafter{\the\toks0 \space #3}% + \fi + % + \edef\writeto{\csname#1indfile\endcsname}% + % + \safewhatsit\dosubindwrite + }% + \fi +} + +% Write the entry in \toks0 to the index file: +% +\def\dosubindwrite{% + % Put the index entry in the margin if desired. + \ifx\SETmarginindex\relax\else + \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}% + \fi + % + % Remember, we are within a group. + \indexdummies % Must do this here, since \bf, etc expand at this stage + \def\backslashcurfont{\indexbackslash}% \indexbackslash isn't defined now + % so it will be output as is; and it will print as backslash. + % + % Process the index entry with all font commands turned off, to + % get the string to sort by. + {\indexnofonts + \edef\temp{\the\toks0}% need full expansion + \xdef\indexsorttmp{\temp}% + }% + % + % Set up the complete index entry, with both the sort key and + % the original text, including any font commands. We write + % three arguments to \entry to the .?? file (four in the + % subentry case), texindex reduces to two when writing the .??s + % sorted result. + \edef\temp{% + \write\writeto{% + \string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}% + }% + \temp +} + +% Take care of unwanted page breaks/skips around a whatsit: +% +% If a skip is the last thing on the list now, preserve it +% by backing up by \lastskip, doing the \write, then inserting +% the skip again. Otherwise, the whatsit generated by the +% \write or \pdfdest will make \lastskip zero. The result is that +% sequences like this: +% @end defun +% @tindex whatever +% @defun ... +% will have extra space inserted, because the \medbreak in the +% start of the @defun won't see the skip inserted by the @end of +% the previous defun. +% +% But don't do any of this if we're not in vertical mode. We +% don't want to do a \vskip and prematurely end a paragraph. +% +% Avoid page breaks due to these extra skips, too. +% +% But wait, there is a catch there: +% We'll have to check whether \lastskip is zero skip. \ifdim is not +% sufficient for this purpose, as it ignores stretch and shrink parts +% of the skip. The only way seems to be to check the textual +% representation of the skip. +% +% The following is almost like \def\zeroskipmacro{0.0pt} except that +% the ``p'' and ``t'' characters have catcode \other, not 11 (letter). +% +\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname} +% +\newskip\whatsitskip +\newcount\whatsitpenalty +% +% ..., ready, GO: +% +\def\safewhatsit#1{% +\ifhmode + #1% +\else + % \lastskip and \lastpenalty cannot both be nonzero simultaneously. + \whatsitskip = \lastskip + \edef\lastskipmacro{\the\lastskip}% + \whatsitpenalty = \lastpenalty + % + % If \lastskip is nonzero, that means the last item was a + % skip. And since a skip is discardable, that means this + % -\whatsitskip glue we're inserting is preceded by a + % non-discardable item, therefore it is not a potential + % breakpoint, therefore no \nobreak needed. + \ifx\lastskipmacro\zeroskipmacro + \else + \vskip-\whatsitskip + \fi + % + #1% + % + \ifx\lastskipmacro\zeroskipmacro + % If \lastskip was zero, perhaps the last item was a penalty, and + % perhaps it was >=10000, e.g., a \nobreak. In that case, we want + % to re-insert the same penalty (values >10000 are used for various + % signals); since we just inserted a non-discardable item, any + % following glue (such as a \parskip) would be a breakpoint. For example: + % + % @deffn deffn-whatever + % @vindex index-whatever + % Description. + % would allow a break between the index-whatever whatsit + % and the "Description." paragraph. + \ifnum\whatsitpenalty>9999 \penalty\whatsitpenalty \fi + \else + % On the other hand, if we had a nonzero \lastskip, + % this make-up glue would be preceded by a non-discardable item + % (the whatsit from the \write), so we must insert a \nobreak. + \nobreak\vskip\whatsitskip + \fi +\fi +} + +% The index entry written in the file actually looks like +% \entry {sortstring}{page}{topic} +% or +% \entry {sortstring}{page}{topic}{subtopic} +% The texindex program reads in these files and writes files +% containing these kinds of lines: +% \initial {c} +% before the first topic whose initial is c +% \entry {topic}{pagelist} +% for a topic that is used without subtopics +% \primary {topic} +% for the beginning of a topic that is used with subtopics +% \secondary {subtopic}{pagelist} +% for each subtopic. + +% Define the user-accessible indexing commands +% @findex, @vindex, @kindex, @cindex. + +\def\findex {\fnindex} +\def\kindex {\kyindex} +\def\cindex {\cpindex} +\def\vindex {\vrindex} +\def\tindex {\tpindex} +\def\pindex {\pgindex} + +\def\cindexsub {\begingroup\obeylines\cindexsub} +{\obeylines % +\gdef\cindexsub "#1" #2^^M{\endgroup % +\dosubind{cp}{#2}{#1}}} + +% Define the macros used in formatting output of the sorted index material. + +% @printindex causes a particular index (the ??s file) to get printed. +% It does not print any chapter heading (usually an @unnumbered). +% +\parseargdef\printindex{\begingroup + \dobreak \chapheadingskip{10000}% + % + \smallfonts \rm + \tolerance = 9500 + \plainfrenchspacing + \everypar = {}% don't want the \kern\-parindent from indentation suppression. + % + % See if the index file exists and is nonempty. + % Change catcode of @ here so that if the index file contains + % \initial {@} + % as its first line, TeX doesn't complain about mismatched braces + % (because it thinks @} is a control sequence). + \catcode`\@ = 11 + \openin 1 \jobname.#1s + \ifeof 1 + % \enddoublecolumns gets confused if there is no text in the index, + % and it loses the chapter title and the aux file entries for the + % index. The easiest way to prevent this problem is to make sure + % there is some text. + \putwordIndexNonexistent + \else + % + % If the index file exists but is empty, then \openin leaves \ifeof + % false. We have to make TeX try to read something from the file, so + % it can discover if there is anything in it. + \read 1 to \temp + \ifeof 1 + \putwordIndexIsEmpty + \else + % Index files are almost Texinfo source, but we use \ as the escape + % character. It would be better to use @, but that's too big a change + % to make right now. + \def\indexbackslash{\backslashcurfont}% + \catcode`\\ = 0 + \escapechar = `\\ + \begindoublecolumns + \input \jobname.#1s + \enddoublecolumns + \fi + \fi + \closein 1 +\endgroup} + +% These macros are used by the sorted index file itself. +% Change them to control the appearance of the index. + +\def\initial#1{{% + % Some minor font changes for the special characters. + \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt + % + % Remove any glue we may have, we'll be inserting our own. + \removelastskip + % + % We like breaks before the index initials, so insert a bonus. + \nobreak + \vskip 0pt plus 3\baselineskip + \penalty 0 + \vskip 0pt plus -3\baselineskip + % + % Typeset the initial. Making this add up to a whole number of + % baselineskips increases the chance of the dots lining up from column + % to column. It still won't often be perfect, because of the stretch + % we need before each entry, but it's better. + % + % No shrink because it confuses \balancecolumns. + \vskip 1.67\baselineskip plus .5\baselineskip + \leftline{\secbf #1}% + % Do our best not to break after the initial. + \nobreak + \vskip .33\baselineskip plus .1\baselineskip +}} + +% \entry typesets a paragraph consisting of the text (#1), dot leaders, and +% then page number (#2) flushed to the right margin. It is used for index +% and table of contents entries. The paragraph is indented by \leftskip. +% +% A straightforward implementation would start like this: +% \def\entry#1#2{... +% But this frozes the catcodes in the argument, and can cause problems to +% @code, which sets - active. This problem was fixed by a kludge--- +% ``-'' was active throughout whole index, but this isn't really right. +% +% The right solution is to prevent \entry from swallowing the whole text. +% --kasal, 21nov03 +\def\entry{% + \begingroup + % + % Start a new paragraph if necessary, so our assignments below can't + % affect previous text. + \par + % + % Do not fill out the last line with white space. + \parfillskip = 0in + % + % No extra space above this paragraph. + \parskip = 0in + % + % Do not prefer a separate line ending with a hyphen to fewer lines. + \finalhyphendemerits = 0 + % + % \hangindent is only relevant when the entry text and page number + % don't both fit on one line. In that case, bob suggests starting the + % dots pretty far over on the line. Unfortunately, a large + % indentation looks wrong when the entry text itself is broken across + % lines. So we use a small indentation and put up with long leaders. + % + % \hangafter is reset to 1 (which is the value we want) at the start + % of each paragraph, so we need not do anything with that. + \hangindent = 2em + % + % When the entry text needs to be broken, just fill out the first line + % with blank space. + \rightskip = 0pt plus1fil + % + % A bit of stretch before each entry for the benefit of balancing + % columns. + \vskip 0pt plus1pt + % + % Swallow the left brace of the text (first parameter): + \afterassignment\doentry + \let\temp = +} +\def\doentry{% + \bgroup % Instead of the swallowed brace. + \noindent + \aftergroup\finishentry + % And now comes the text of the entry. +} +\def\finishentry#1{% + % #1 is the page number. + % + % The following is kludged to not output a line of dots in the index if + % there are no page numbers. The next person who breaks this will be + % cursed by a Unix daemon. + \setbox\boxA = \hbox{#1}% + \ifdim\wd\boxA = 0pt + \ % + \else + % + % If we must, put the page number on a line of its own, and fill out + % this line with blank space. (The \hfil is overwhelmed with the + % fill leaders glue in \indexdotfill if the page number does fit.) + \hfil\penalty50 + \null\nobreak\indexdotfill % Have leaders before the page number. + % + % The `\ ' here is removed by the implicit \unskip that TeX does as + % part of (the primitive) \par. Without it, a spurious underfull + % \hbox ensues. + \ifpdf + \pdfgettoks#1.% + \ \the\toksA + \else + \ #1% + \fi + \fi + \par + \endgroup +} + +% Like plain.tex's \dotfill, except uses up at least 1 em. +\def\indexdotfill{\cleaders + \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1fill} + +\def\primary #1{\line{#1\hfil}} + +\newskip\secondaryindent \secondaryindent=0.5cm +\def\secondary#1#2{{% + \parfillskip=0in + \parskip=0in + \hangindent=1in + \hangafter=1 + \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill + \ifpdf + \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. + \else + #2 + \fi + \par +}} + +% Define two-column mode, which we use to typeset indexes. +% Adapted from the TeXbook, page 416, which is to say, +% the manmac.tex format used to print the TeXbook itself. +\catcode`\@=11 + +\newbox\partialpage +\newdimen\doublecolumnhsize + +\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns + % Grab any single-column material above us. + \output = {% + % + % Here is a possibility not foreseen in manmac: if we accumulate a + % whole lot of material, we might end up calling this \output + % routine twice in a row (see the doublecol-lose test, which is + % essentially a couple of indexes with @setchapternewpage off). In + % that case we just ship out what is in \partialpage with the normal + % output routine. Generally, \partialpage will be empty when this + % runs and this will be a no-op. See the indexspread.tex test case. + \ifvoid\partialpage \else + \onepageout{\pagecontents\partialpage}% + \fi + % + \global\setbox\partialpage = \vbox{% + % Unvbox the main output page. + \unvbox\PAGE + \kern-\topskip \kern\baselineskip + }% + }% + \eject % run that output routine to set \partialpage + % + % Use the double-column output routine for subsequent pages. + \output = {\doublecolumnout}% + % + % Change the page size parameters. We could do this once outside this + % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 + % format, but then we repeat the same computation. Repeating a couple + % of assignments once per index is clearly meaningless for the + % execution time, so we may as well do it in one place. + % + % First we halve the line length, less a little for the gutter between + % the columns. We compute the gutter based on the line length, so it + % changes automatically with the paper format. The magic constant + % below is chosen so that the gutter has the same value (well, +-<1pt) + % as it did when we hard-coded it. + % + % We put the result in a separate register, \doublecolumhsize, so we + % can restore it in \pagesofar, after \hsize itself has (potentially) + % been clobbered. + % + \doublecolumnhsize = \hsize + \advance\doublecolumnhsize by -.04154\hsize + \divide\doublecolumnhsize by 2 + \hsize = \doublecolumnhsize + % + % Double the \vsize as well. (We don't need a separate register here, + % since nobody clobbers \vsize.) + \vsize = 2\vsize +} + +% The double-column output routine for all double-column pages except +% the last. +% +\def\doublecolumnout{% + \splittopskip=\topskip \splitmaxdepth=\maxdepth + % Get the available space for the double columns -- the normal + % (undoubled) page height minus any material left over from the + % previous page. + \dimen@ = \vsize + \divide\dimen@ by 2 + \advance\dimen@ by -\ht\partialpage + % + % box0 will be the left-hand column, box2 the right. + \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@ + \onepageout\pagesofar + \unvbox255 + \penalty\outputpenalty +} +% +% Re-output the contents of the output page -- any previous material, +% followed by the two boxes we just split, in box0 and box2. +\def\pagesofar{% + \unvbox\partialpage + % + \hsize = \doublecolumnhsize + \wd0=\hsize \wd2=\hsize + \hbox to\pagewidth{\box0\hfil\box2}% +} +% +% All done with double columns. +\def\enddoublecolumns{% + % The following penalty ensures that the page builder is exercised + % _before_ we change the output routine. This is necessary in the + % following situation: + % + % The last section of the index consists only of a single entry. + % Before this section, \pagetotal is less than \pagegoal, so no + % break occurs before the last section starts. However, the last + % section, consisting of \initial and the single \entry, does not + % fit on the page and has to be broken off. Without the following + % penalty the page builder will not be exercised until \eject + % below, and by that time we'll already have changed the output + % routine to the \balancecolumns version, so the next-to-last + % double-column page will be processed with \balancecolumns, which + % is wrong: The two columns will go to the main vertical list, with + % the broken-off section in the recent contributions. As soon as + % the output routine finishes, TeX starts reconsidering the page + % break. The two columns and the broken-off section both fit on the + % page, because the two columns now take up only half of the page + % goal. When TeX sees \eject from below which follows the final + % section, it invokes the new output routine that we've set after + % \balancecolumns below; \onepageout will try to fit the two columns + % and the final section into the vbox of \pageheight (see + % \pagebody), causing an overfull box. + % + % Note that glue won't work here, because glue does not exercise the + % page builder, unlike penalties (see The TeXbook, pp. 280-281). + \penalty0 + % + \output = {% + % Split the last of the double-column material. Leave it on the + % current page, no automatic page break. + \balancecolumns + % + % If we end up splitting too much material for the current page, + % though, there will be another page break right after this \output + % invocation ends. Having called \balancecolumns once, we do not + % want to call it again. Therefore, reset \output to its normal + % definition right away. (We hope \balancecolumns will never be + % called on to balance too much material, but if it is, this makes + % the output somewhat more palatable.) + \global\output = {\onepageout{\pagecontents\PAGE}}% + }% + \eject + \endgroup % started in \begindoublecolumns + % + % \pagegoal was set to the doubled \vsize above, since we restarted + % the current page. We're now back to normal single-column + % typesetting, so reset \pagegoal to the normal \vsize (after the + % \endgroup where \vsize got restored). + \pagegoal = \vsize +} +% +% Called at the end of the double column material. +\def\balancecolumns{% + \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120. + \dimen@ = \ht0 + \advance\dimen@ by \topskip + \advance\dimen@ by-\baselineskip + \divide\dimen@ by 2 % target to split to + %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}% + \splittopskip = \topskip + % Loop until we get a decent breakpoint. + {% + \vbadness = 10000 + \loop + \global\setbox3 = \copy0 + \global\setbox1 = \vsplit3 to \dimen@ + \ifdim\ht3>\dimen@ + \global\advance\dimen@ by 1pt + \repeat + }% + %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}% + \setbox0=\vbox to\dimen@{\unvbox1}% + \setbox2=\vbox to\dimen@{\unvbox3}% + % + \pagesofar +} +\catcode`\@ = \other + + +\message{sectioning,} +% Chapters, sections, etc. + +% \unnumberedno is an oxymoron, of course. But we count the unnumbered +% sections so that we can refer to them unambiguously in the pdf +% outlines by their "section number". We avoid collisions with chapter +% numbers by starting them at 10000. (If a document ever has 10000 +% chapters, we're in trouble anyway, I'm sure.) +\newcount\unnumberedno \unnumberedno = 10000 +\newcount\chapno +\newcount\secno \secno=0 +\newcount\subsecno \subsecno=0 +\newcount\subsubsecno \subsubsecno=0 + +% This counter is funny since it counts through charcodes of letters A, B, ... +\newcount\appendixno \appendixno = `\@ +% +% \def\appendixletter{\char\the\appendixno} +% We do the following ugly conditional instead of the above simple +% construct for the sake of pdftex, which needs the actual +% letter in the expansion, not just typeset. +% +\def\appendixletter{% + \ifnum\appendixno=`A A% + \else\ifnum\appendixno=`B B% + \else\ifnum\appendixno=`C C% + \else\ifnum\appendixno=`D D% + \else\ifnum\appendixno=`E E% + \else\ifnum\appendixno=`F F% + \else\ifnum\appendixno=`G G% + \else\ifnum\appendixno=`H H% + \else\ifnum\appendixno=`I I% + \else\ifnum\appendixno=`J J% + \else\ifnum\appendixno=`K K% + \else\ifnum\appendixno=`L L% + \else\ifnum\appendixno=`M M% + \else\ifnum\appendixno=`N N% + \else\ifnum\appendixno=`O O% + \else\ifnum\appendixno=`P P% + \else\ifnum\appendixno=`Q Q% + \else\ifnum\appendixno=`R R% + \else\ifnum\appendixno=`S S% + \else\ifnum\appendixno=`T T% + \else\ifnum\appendixno=`U U% + \else\ifnum\appendixno=`V V% + \else\ifnum\appendixno=`W W% + \else\ifnum\appendixno=`X X% + \else\ifnum\appendixno=`Y Y% + \else\ifnum\appendixno=`Z Z% + % The \the is necessary, despite appearances, because \appendixletter is + % expanded while writing the .toc file. \char\appendixno is not + % expandable, thus it is written literally, thus all appendixes come out + % with the same letter (or @) in the toc without it. + \else\char\the\appendixno + \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi + \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi} + +% Each @chapter defines these (using marks) as the number+name, number +% and name of the chapter. Page headings and footings can use +% these. @section does likewise. +\def\thischapter{} +\def\thischapternum{} +\def\thischaptername{} +\def\thissection{} +\def\thissectionnum{} +\def\thissectionname{} + +\newcount\absseclevel % used to calculate proper heading level +\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count + +% @raisesections: treat @section as chapter, @subsection as section, etc. +\def\raisesections{\global\advance\secbase by -1} +\let\up=\raisesections % original BFox name + +% @lowersections: treat @chapter as section, @section as subsection, etc. +\def\lowersections{\global\advance\secbase by 1} +\let\down=\lowersections % original BFox name + +% we only have subsub. +\chardef\maxseclevel = 3 +% +% A numbered section within an unnumbered changes to unnumbered too. +% To achive this, remember the "biggest" unnum. sec. we are currently in: +\chardef\unmlevel = \maxseclevel +% +% Trace whether the current chapter is an appendix or not: +% \chapheadtype is "N" or "A", unnumbered chapters are ignored. +\def\chapheadtype{N} + +% Choose a heading macro +% #1 is heading type +% #2 is heading level +% #3 is text for heading +\def\genhead#1#2#3{% + % Compute the abs. sec. level: + \absseclevel=#2 + \advance\absseclevel by \secbase + % Make sure \absseclevel doesn't fall outside the range: + \ifnum \absseclevel < 0 + \absseclevel = 0 + \else + \ifnum \absseclevel > 3 + \absseclevel = 3 + \fi + \fi + % The heading type: + \def\headtype{#1}% + \if \headtype U% + \ifnum \absseclevel < \unmlevel + \chardef\unmlevel = \absseclevel + \fi + \else + % Check for appendix sections: + \ifnum \absseclevel = 0 + \edef\chapheadtype{\headtype}% + \else + \if \headtype A\if \chapheadtype N% + \errmessage{@appendix... within a non-appendix chapter}% + \fi\fi + \fi + % Check for numbered within unnumbered: + \ifnum \absseclevel > \unmlevel + \def\headtype{U}% + \else + \chardef\unmlevel = 3 + \fi + \fi + % Now print the heading: + \if \headtype U% + \ifcase\absseclevel + \unnumberedzzz{#3}% + \or \unnumberedseczzz{#3}% + \or \unnumberedsubseczzz{#3}% + \or \unnumberedsubsubseczzz{#3}% + \fi + \else + \if \headtype A% + \ifcase\absseclevel + \appendixzzz{#3}% + \or \appendixsectionzzz{#3}% + \or \appendixsubseczzz{#3}% + \or \appendixsubsubseczzz{#3}% + \fi + \else + \ifcase\absseclevel + \chapterzzz{#3}% + \or \seczzz{#3}% + \or \numberedsubseczzz{#3}% + \or \numberedsubsubseczzz{#3}% + \fi + \fi + \fi + \suppressfirstparagraphindent +} + +% an interface: +\def\numhead{\genhead N} +\def\apphead{\genhead A} +\def\unnmhead{\genhead U} + +% @chapter, @appendix, @unnumbered. Increment top-level counter, reset +% all lower-level sectioning counters to zero. +% +% Also set \chaplevelprefix, which we prepend to @float sequence numbers +% (e.g., figures), q.v. By default (before any chapter), that is empty. +\let\chaplevelprefix = \empty +% +\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz +\def\chapterzzz#1{% + % section resetting is \global in case the chapter is in a group, such + % as an @include file. + \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 + \global\advance\chapno by 1 + % + % Used for \float. + \gdef\chaplevelprefix{\the\chapno.}% + \resetallfloatnos + % + \message{\putwordChapter\space \the\chapno}% + % + % Write the actual heading. + \chapmacro{#1}{Ynumbered}{\the\chapno}% + % + % So @section and the like are numbered underneath this chapter. + \global\let\section = \numberedsec + \global\let\subsection = \numberedsubsec + \global\let\subsubsection = \numberedsubsubsec +} + +\outer\parseargdef\appendix{\apphead0{#1}} % normally apphead0 calls appendixzzz +\def\appendixzzz#1{% + \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 + \global\advance\appendixno by 1 + \gdef\chaplevelprefix{\appendixletter.}% + \resetallfloatnos + % + \def\appendixnum{\putwordAppendix\space \appendixletter}% + \message{\appendixnum}% + % + \chapmacro{#1}{Yappendix}{\appendixletter}% + % + \global\let\section = \appendixsec + \global\let\subsection = \appendixsubsec + \global\let\subsubsection = \appendixsubsubsec +} + +\outer\parseargdef\unnumbered{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz +\def\unnumberedzzz#1{% + \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 + \global\advance\unnumberedno by 1 + % + % Since an unnumbered has no number, no prefix for figures. + \global\let\chaplevelprefix = \empty + \resetallfloatnos + % + % This used to be simply \message{#1}, but TeX fully expands the + % argument to \message. Therefore, if #1 contained @-commands, TeX + % expanded them. For example, in `@unnumbered The @cite{Book}', TeX + % expanded @cite (which turns out to cause errors because \cite is meant + % to be executed, not expanded). + % + % Anyway, we don't want the fully-expanded definition of @cite to appear + % as a result of the \message, we just want `@cite' itself. We use + % \the<toks register> to achieve this: TeX expands \the<toks> only once, + % simply yielding the contents of <toks register>. (We also do this for + % the toc entries.) + \toks0 = {#1}% + \message{(\the\toks0)}% + % + \chapmacro{#1}{Ynothing}{\the\unnumberedno}% + % + \global\let\section = \unnumberedsec + \global\let\subsection = \unnumberedsubsec + \global\let\subsubsection = \unnumberedsubsubsec +} + +% @centerchap is like @unnumbered, but the heading is centered. +\outer\parseargdef\centerchap{% + % Well, we could do the following in a group, but that would break + % an assumption that \chapmacro is called at the outermost level. + % Thus we are safer this way: --kasal, 24feb04 + \let\centerparametersmaybe = \centerparameters + \unnmhead0{#1}% + \let\centerparametersmaybe = \relax +} + +% @top is like @unnumbered. +\let\top\unnumbered + +% Sections. +\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz +\def\seczzz#1{% + \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 + \sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}% +} + +\outer\parseargdef\appendixsection{\apphead1{#1}} % normally calls appendixsectionzzz +\def\appendixsectionzzz#1{% + \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 + \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}% +} +\let\appendixsec\appendixsection + +\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} % normally calls unnumberedseczzz +\def\unnumberedseczzz#1{% + \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 + \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}% +} + +% Subsections. +\outer\parseargdef\numberedsubsec{\numhead2{#1}} % normally calls numberedsubseczzz +\def\numberedsubseczzz#1{% + \global\subsubsecno=0 \global\advance\subsecno by 1 + \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}% +} + +\outer\parseargdef\appendixsubsec{\apphead2{#1}} % normally calls appendixsubseczzz +\def\appendixsubseczzz#1{% + \global\subsubsecno=0 \global\advance\subsecno by 1 + \sectionheading{#1}{subsec}{Yappendix}% + {\appendixletter.\the\secno.\the\subsecno}% +} + +\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} %normally calls unnumberedsubseczzz +\def\unnumberedsubseczzz#1{% + \global\subsubsecno=0 \global\advance\subsecno by 1 + \sectionheading{#1}{subsec}{Ynothing}% + {\the\unnumberedno.\the\secno.\the\subsecno}% +} + +% Subsubsections. +\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} % normally numberedsubsubseczzz +\def\numberedsubsubseczzz#1{% + \global\advance\subsubsecno by 1 + \sectionheading{#1}{subsubsec}{Ynumbered}% + {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}% +} + +\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} % normally appendixsubsubseczzz +\def\appendixsubsubseczzz#1{% + \global\advance\subsubsecno by 1 + \sectionheading{#1}{subsubsec}{Yappendix}% + {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}% +} + +\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} %normally unnumberedsubsubseczzz +\def\unnumberedsubsubseczzz#1{% + \global\advance\subsubsecno by 1 + \sectionheading{#1}{subsubsec}{Ynothing}% + {\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}% +} + +% These macros control what the section commands do, according +% to what kind of chapter we are in (ordinary, appendix, or unnumbered). +% Define them by default for a numbered chapter. +\let\section = \numberedsec +\let\subsection = \numberedsubsec +\let\subsubsection = \numberedsubsubsec + +% Define @majorheading, @heading and @subheading + +% NOTE on use of \vbox for chapter headings, section headings, and such: +% 1) We use \vbox rather than the earlier \line to permit +% overlong headings to fold. +% 2) \hyphenpenalty is set to 10000 because hyphenation in a +% heading is obnoxious; this forbids it. +% 3) Likewise, headings look best if no \parindent is used, and +% if justification is not attempted. Hence \raggedright. + + +\def\majorheading{% + {\advance\chapheadingskip by 10pt \chapbreak }% + \parsearg\chapheadingzzz +} + +\def\chapheading{\chapbreak \parsearg\chapheadingzzz} +\def\chapheadingzzz#1{% + {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% + \bigskip \par\penalty 200\relax + \suppressfirstparagraphindent +} + +% @heading, @subheading, @subsubheading. +\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{} + \suppressfirstparagraphindent} +\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{} + \suppressfirstparagraphindent} +\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{} + \suppressfirstparagraphindent} + +% These macros generate a chapter, section, etc. heading only +% (including whitespace, linebreaking, etc. around it), +% given all the information in convenient, parsed form. + +%%% Args are the skip and penalty (usually negative) +\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi} + +%%% Define plain chapter starts, and page on/off switching for it +% Parameter controlling skip before chapter headings (if needed) + +\newskip\chapheadingskip + +\def\chapbreak{\dobreak \chapheadingskip {-4000}} +\def\chappager{\par\vfill\supereject} +% Because \domark is called before \chapoddpage, the filler page will +% get the headings for the next chapter, which is wrong. But we don't +% care -- we just disable all headings on the filler page. +\def\chapoddpage{% + \chappager + \ifodd\pageno \else + \begingroup + \evenheadline={\hfil}\evenfootline={\hfil}% + \oddheadline={\hfil}\oddfootline={\hfil}% + \hbox to 0pt{}% + \chappager + \endgroup + \fi +} + +\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} + +\def\CHAPPAGoff{% +\global\let\contentsalignmacro = \chappager +\global\let\pchapsepmacro=\chapbreak +\global\let\pagealignmacro=\chappager} + +\def\CHAPPAGon{% +\global\let\contentsalignmacro = \chappager +\global\let\pchapsepmacro=\chappager +\global\let\pagealignmacro=\chappager +\global\def\HEADINGSon{\HEADINGSsingle}} + +\def\CHAPPAGodd{% +\global\let\contentsalignmacro = \chapoddpage +\global\let\pchapsepmacro=\chapoddpage +\global\let\pagealignmacro=\chapoddpage +\global\def\HEADINGSon{\HEADINGSdouble}} + +\CHAPPAGon + +% Chapter opening. +% +% #1 is the text, #2 is the section type (Ynumbered, Ynothing, +% Yappendix, Yomitfromtoc), #3 the chapter number. +% +% To test against our argument. +\def\Ynothingkeyword{Ynothing} +\def\Yomitfromtockeyword{Yomitfromtoc} +\def\Yappendixkeyword{Yappendix} +% +\def\chapmacro#1#2#3{% + % Insert the first mark before the heading break (see notes for \domark). + \let\prevchapterdefs=\lastchapterdefs + \let\prevsectiondefs=\lastsectiondefs + \gdef\lastsectiondefs{\gdef\thissectionname{}\gdef\thissectionnum{}% + \gdef\thissection{}}% + % + \def\temptype{#2}% + \ifx\temptype\Ynothingkeyword + \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}% + \gdef\thischapter{\thischaptername}}% + \else\ifx\temptype\Yomitfromtockeyword + \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}% + \gdef\thischapter{}}% + \else\ifx\temptype\Yappendixkeyword + \toks0={#1}% + \xdef\lastchapterdefs{% + \gdef\noexpand\thischaptername{\the\toks0}% + \gdef\noexpand\thischapternum{\appendixletter}% + \gdef\noexpand\thischapter{\putwordAppendix{} \noexpand\thischapternum: + \noexpand\thischaptername}% + }% + \else + \toks0={#1}% + \xdef\lastchapterdefs{% + \gdef\noexpand\thischaptername{\the\toks0}% + \gdef\noexpand\thischapternum{\the\chapno}% + \gdef\noexpand\thischapter{\putwordChapter{} \noexpand\thischapternum: + \noexpand\thischaptername}% + }% + \fi\fi\fi + % + % Output the mark. Pass it through \safewhatsit, to take care of + % the preceding space. + \safewhatsit\domark + % + % Insert the chapter heading break. + \pchapsepmacro + % + % Now the second mark, after the heading break. No break points + % between here and the heading. + \let\prevchapterdefs=\lastchapterdefs + \let\prevsectiondefs=\lastsectiondefs + \domark + % + {% + \chapfonts \rm + % + % Have to define \lastsection before calling \donoderef, because the + % xref code eventually uses it. On the other hand, it has to be called + % after \pchapsepmacro, or the headline will change too soon. + \gdef\lastsection{#1}% + % + % Only insert the separating space if we have a chapter/appendix + % number, and don't print the unnumbered ``number''. + \ifx\temptype\Ynothingkeyword + \setbox0 = \hbox{}% + \def\toctype{unnchap}% + \else\ifx\temptype\Yomitfromtockeyword + \setbox0 = \hbox{}% contents like unnumbered, but no toc entry + \def\toctype{omit}% + \else\ifx\temptype\Yappendixkeyword + \setbox0 = \hbox{\putwordAppendix{} #3\enspace}% + \def\toctype{app}% + \else + \setbox0 = \hbox{#3\enspace}% + \def\toctype{numchap}% + \fi\fi\fi + % + % Write the toc entry for this chapter. Must come before the + % \donoderef, because we include the current node name in the toc + % entry, and \donoderef resets it to empty. + \writetocentry{\toctype}{#1}{#3}% + % + % For pdftex, we have to write out the node definition (aka, make + % the pdfdest) after any page break, but before the actual text has + % been typeset. If the destination for the pdf outline is after the + % text, then jumping from the outline may wind up with the text not + % being visible, for instance under high magnification. + \donoderef{#2}% + % + % Typeset the actual heading. + \nobreak % Avoid page breaks at the interline glue. + \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright + \hangindent=\wd0 \centerparametersmaybe + \unhbox0 #1\par}% + }% + \nobreak\bigskip % no page break after a chapter title + \nobreak +} + +% @centerchap -- centered and unnumbered. +\let\centerparametersmaybe = \relax +\def\centerparameters{% + \advance\rightskip by 3\rightskip + \leftskip = \rightskip + \parfillskip = 0pt +} + + +% I don't think this chapter style is supported any more, so I'm not +% updating it with the new noderef stuff. We'll see. --karl, 11aug03. +% +\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} +% +\def\unnchfopen #1{% +\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\nobreak +} +\def\chfopen #1#2{\chapoddpage {\chapfonts +\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% +\par\penalty 5000 % +} +\def\centerchfopen #1{% +\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt + \hfill {\rm #1}\hfill}}\bigskip \par\nobreak +} +\def\CHAPFopen{% + \global\let\chapmacro=\chfopen + \global\let\centerchapmacro=\centerchfopen} + + +% Section titles. These macros combine the section number parts and +% call the generic \sectionheading to do the printing. +% +\newskip\secheadingskip +\def\secheadingbreak{\dobreak \secheadingskip{-1000}} + +% Subsection titles. +\newskip\subsecheadingskip +\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}} + +% Subsubsection titles. +\def\subsubsecheadingskip{\subsecheadingskip} +\def\subsubsecheadingbreak{\subsecheadingbreak} + + +% Print any size, any type, section title. +% +% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is +% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the +% section number. +% +\def\seckeyword{sec} +% +\def\sectionheading#1#2#3#4{% + {% + % Switch to the right set of fonts. + \csname #2fonts\endcsname \rm + % + \def\sectionlevel{#2}% + \def\temptype{#3}% + % + % Insert first mark before the heading break (see notes for \domark). + \let\prevsectiondefs=\lastsectiondefs + \ifx\temptype\Ynothingkeyword + \ifx\sectionlevel\seckeyword + \gdef\lastsectiondefs{\gdef\thissectionname{#1}\gdef\thissectionnum{}% + \gdef\thissection{\thissectionname}}% + \fi + \else\ifx\temptype\Yomitfromtockeyword + % Don't redefine \thissection. + \else\ifx\temptype\Yappendixkeyword + \ifx\sectionlevel\seckeyword + \toks0={#1}% + \xdef\lastsectiondefs{% + \gdef\noexpand\thissectionname{\the\toks0}% + \gdef\noexpand\thissectionnum{#4}% + \gdef\noexpand\thissection{\putwordSection{} \noexpand\thissectionnum: + \noexpand\thissectionname}% + }% + \fi + \else + \ifx\sectionlevel\seckeyword + \toks0={#1}% + \xdef\lastsectiondefs{% + \gdef\noexpand\thissectionname{\the\toks0}% + \gdef\noexpand\thissectionnum{#4}% + \gdef\noexpand\thissection{\putwordSection{} \noexpand\thissectionnum: + \noexpand\thissectionname}% + }% + \fi + \fi\fi\fi + % + % Output the mark. Pass it through \safewhatsit, to take care of + % the preceding space. + \safewhatsit\domark + % + % Insert space above the heading. + \csname #2headingbreak\endcsname + % + % Now the second mark, after the heading break. No break points + % between here and the heading. + \let\prevsectiondefs=\lastsectiondefs + \domark + % + % Only insert the space after the number if we have a section number. + \ifx\temptype\Ynothingkeyword + \setbox0 = \hbox{}% + \def\toctype{unn}% + \gdef\lastsection{#1}% + \else\ifx\temptype\Yomitfromtockeyword + % for @headings -- no section number, don't include in toc, + % and don't redefine \lastsection. + \setbox0 = \hbox{}% + \def\toctype{omit}% + \let\sectionlevel=\empty + \else\ifx\temptype\Yappendixkeyword + \setbox0 = \hbox{#4\enspace}% + \def\toctype{app}% + \gdef\lastsection{#1}% + \else + \setbox0 = \hbox{#4\enspace}% + \def\toctype{num}% + \gdef\lastsection{#1}% + \fi\fi\fi + % + % Write the toc entry (before \donoderef). See comments in \chapmacro. + \writetocentry{\toctype\sectionlevel}{#1}{#4}% + % + % Write the node reference (= pdf destination for pdftex). + % Again, see comments in \chapmacro. + \donoderef{#3}% + % + % Interline glue will be inserted when the vbox is completed. + % That glue will be a valid breakpoint for the page, since it'll be + % preceded by a whatsit (usually from the \donoderef, or from the + % \writetocentry if there was no node). We don't want to allow that + % break, since then the whatsits could end up on page n while the + % section is on page n+1, thus toc/etc. are wrong. Debian bug 276000. + \nobreak + % + % Output the actual section heading. + \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright + \hangindent=\wd0 % zero if no section number + \unhbox0 #1}% + }% + % Add extra space after the heading -- half of whatever came above it. + % Don't allow stretch, though. + \kern .5 \csname #2headingskip\endcsname + % + % Do not let the kern be a potential breakpoint, as it would be if it + % was followed by glue. + \nobreak + % + % We'll almost certainly start a paragraph next, so don't let that + % glue accumulate. (Not a breakpoint because it's preceded by a + % discardable item.) + \vskip-\parskip + % + % This is purely so the last item on the list is a known \penalty > + % 10000. This is so \startdefun can avoid allowing breakpoints after + % section headings. Otherwise, it would insert a valid breakpoint between: + % + % @section sec-whatever + % @deffn def-whatever + \penalty 10001 +} + + +\message{toc,} +% Table of contents. +\newwrite\tocfile + +% Write an entry to the toc file, opening it if necessary. +% Called from @chapter, etc. +% +% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno} +% We append the current node name (if any) and page number as additional +% arguments for the \{chap,sec,...}entry macros which will eventually +% read this. The node name is used in the pdf outlines as the +% destination to jump to. +% +% We open the .toc file for writing here instead of at @setfilename (or +% any other fixed time) so that @contents can be anywhere in the document. +% But if #1 is `omit', then we don't do anything. This is used for the +% table of contents chapter openings themselves. +% +\newif\iftocfileopened +\def\omitkeyword{omit}% +% +\def\writetocentry#1#2#3{% + \edef\writetoctype{#1}% + \ifx\writetoctype\omitkeyword \else + \iftocfileopened\else + \immediate\openout\tocfile = \jobname.toc + \global\tocfileopenedtrue + \fi + % + \iflinks + {\atdummies + \edef\temp{% + \write\tocfile{@#1entry{#2}{#3}{\lastnode}{\noexpand\folio}}}% + \temp + }% + \fi + \fi + % + % Tell \shipout to create a pdf destination on each page, if we're + % writing pdf. These are used in the table of contents. We can't + % just write one on every page because the title pages are numbered + % 1 and 2 (the page numbers aren't printed), and so are the first + % two pages of the document. Thus, we'd have two destinations named + % `1', and two named `2'. + \ifpdf \global\pdfmakepagedesttrue \fi +} + + +% These characters do not print properly in the Computer Modern roman +% fonts, so we must take special care. This is more or less redundant +% with the Texinfo input format setup at the end of this file. +% +\def\activecatcodes{% + \catcode`\"=\active + \catcode`\$=\active + \catcode`\<=\active + \catcode`\>=\active + \catcode`\\=\active + \catcode`\^=\active + \catcode`\_=\active + \catcode`\|=\active + \catcode`\~=\active +} + + +% Read the toc file, which is essentially Texinfo input. +\def\readtocfile{% + \setupdatafile + \activecatcodes + \input \tocreadfilename +} + +\newskip\contentsrightmargin \contentsrightmargin=1in +\newcount\savepageno +\newcount\lastnegativepageno \lastnegativepageno = -1 + +% Prepare to read what we've written to \tocfile. +% +\def\startcontents#1{% + % If @setchapternewpage on, and @headings double, the contents should + % start on an odd page, unlike chapters. Thus, we maintain + % \contentsalignmacro in parallel with \pagealignmacro. + % From: Torbjorn Granlund <tege@matematik.su.se> + \contentsalignmacro + \immediate\closeout\tocfile + % + % Don't need to put `Contents' or `Short Contents' in the headline. + % It is abundantly clear what they are. + \chapmacro{#1}{Yomitfromtoc}{}% + % + \savepageno = \pageno + \begingroup % Set up to handle contents files properly. + \raggedbottom % Worry more about breakpoints than the bottom. + \advance\hsize by -\contentsrightmargin % Don't use the full line length. + % + % Roman numerals for page numbers. + \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi +} + +% redefined for the two-volume lispref. We always output on +% \jobname.toc even if this is redefined. +% +\def\tocreadfilename{\jobname.toc} + +% Normal (long) toc. +% +\def\contents{% + \startcontents{\putwordTOC}% + \openin 1 \tocreadfilename\space + \ifeof 1 \else + \readtocfile + \fi + \vfill \eject + \contentsalignmacro % in case @setchapternewpage odd is in effect + \ifeof 1 \else + \pdfmakeoutlines + \fi + \closein 1 + \endgroup + \lastnegativepageno = \pageno + \global\pageno = \savepageno +} + +% And just the chapters. +\def\summarycontents{% + \startcontents{\putwordShortTOC}% + % + \let\numchapentry = \shortchapentry + \let\appentry = \shortchapentry + \let\unnchapentry = \shortunnchapentry + % We want a true roman here for the page numbers. + \secfonts + \let\rm=\shortcontrm \let\bf=\shortcontbf + \let\sl=\shortcontsl \let\tt=\shortconttt + \rm + \hyphenpenalty = 10000 + \advance\baselineskip by 1pt % Open it up a little. + \def\numsecentry##1##2##3##4{} + \let\appsecentry = \numsecentry + \let\unnsecentry = \numsecentry + \let\numsubsecentry = \numsecentry + \let\appsubsecentry = \numsecentry + \let\unnsubsecentry = \numsecentry + \let\numsubsubsecentry = \numsecentry + \let\appsubsubsecentry = \numsecentry + \let\unnsubsubsecentry = \numsecentry + \openin 1 \tocreadfilename\space + \ifeof 1 \else + \readtocfile + \fi + \closein 1 + \vfill \eject + \contentsalignmacro % in case @setchapternewpage odd is in effect + \endgroup + \lastnegativepageno = \pageno + \global\pageno = \savepageno +} +\let\shortcontents = \summarycontents + +% Typeset the label for a chapter or appendix for the short contents. +% The arg is, e.g., `A' for an appendix, or `3' for a chapter. +% +\def\shortchaplabel#1{% + % This space should be enough, since a single number is .5em, and the + % widest letter (M) is 1em, at least in the Computer Modern fonts. + % But use \hss just in case. + % (This space doesn't include the extra space that gets added after + % the label; that gets put in by \shortchapentry above.) + % + % We'd like to right-justify chapter numbers, but that looks strange + % with appendix letters. And right-justifying numbers and + % left-justifying letters looks strange when there is less than 10 + % chapters. Have to read the whole toc once to know how many chapters + % there are before deciding ... + \hbox to 1em{#1\hss}% +} + +% These macros generate individual entries in the table of contents. +% The first argument is the chapter or section name. +% The last argument is the page number. +% The arguments in between are the chapter number, section number, ... + +% Chapters, in the main contents. +\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}} +% +% Chapters, in the short toc. +% See comments in \dochapentry re vbox and related settings. +\def\shortchapentry#1#2#3#4{% + \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}% +} + +% Appendices, in the main contents. +% Need the word Appendix, and a fixed-size box. +% +\def\appendixbox#1{% + % We use M since it's probably the widest letter. + \setbox0 = \hbox{\putwordAppendix{} M}% + \hbox to \wd0{\putwordAppendix{} #1\hss}} +% +\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}} + +% Unnumbered chapters. +\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}} +\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}} + +% Sections. +\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}} +\let\appsecentry=\numsecentry +\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}} + +% Subsections. +\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}} +\let\appsubsecentry=\numsubsecentry +\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}} + +% And subsubsections. +\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}} +\let\appsubsubsecentry=\numsubsubsecentry +\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}} + +% This parameter controls the indentation of the various levels. +% Same as \defaultparindent. +\newdimen\tocindent \tocindent = 15pt + +% Now for the actual typesetting. In all these, #1 is the text and #2 is the +% page number. +% +% If the toc has to be broken over pages, we want it to be at chapters +% if at all possible; hence the \penalty. +\def\dochapentry#1#2{% + \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip + \begingroup + \chapentryfonts + \tocentry{#1}{\dopageno\bgroup#2\egroup}% + \endgroup + \nobreak\vskip .25\baselineskip plus.1\baselineskip +} + +\def\dosecentry#1#2{\begingroup + \secentryfonts \leftskip=\tocindent + \tocentry{#1}{\dopageno\bgroup#2\egroup}% +\endgroup} + +\def\dosubsecentry#1#2{\begingroup + \subsecentryfonts \leftskip=2\tocindent + \tocentry{#1}{\dopageno\bgroup#2\egroup}% +\endgroup} + +\def\dosubsubsecentry#1#2{\begingroup + \subsubsecentryfonts \leftskip=3\tocindent + \tocentry{#1}{\dopageno\bgroup#2\egroup}% +\endgroup} + +% We use the same \entry macro as for the index entries. +\let\tocentry = \entry + +% Space between chapter (or whatever) number and the title. +\def\labelspace{\hskip1em \relax} + +\def\dopageno#1{{\rm #1}} +\def\doshortpageno#1{{\rm #1}} + +\def\chapentryfonts{\secfonts \rm} +\def\secentryfonts{\textfonts} +\def\subsecentryfonts{\textfonts} +\def\subsubsecentryfonts{\textfonts} + + +\message{environments,} +% @foo ... @end foo. + +% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. +% +% Since these characters are used in examples, it should be an even number of +% \tt widths. Each \tt character is 1en, so two makes it 1em. +% +\def\point{$\star$} +\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} +\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} +\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} +\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}} + +% The @error{} command. +% Adapted from the TeXbook's \boxit. +% +\newbox\errorbox +% +{\tentt \global\dimen0 = 3em}% Width of the box. +\dimen2 = .55pt % Thickness of rules +% The text. (`r' is open on the right, `e' somewhat less so on the left.) +\setbox0 = \hbox{\kern-.75pt \reducedsf error\kern-1.5pt} +% +\setbox\errorbox=\hbox to \dimen0{\hfil + \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. + \advance\hsize by -2\dimen2 % Rules. + \vbox{% + \hrule height\dimen2 + \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. + \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. + \kern3pt\vrule width\dimen2}% Space to right. + \hrule height\dimen2} + \hfil} +% +\def\error{\leavevmode\lower.7ex\copy\errorbox} + +% @tex ... @end tex escapes into raw Tex temporarily. +% One exception: @ is still an escape character, so that @end tex works. +% But \@ or @@ will get a plain tex @ character. + +\envdef\tex{% + \catcode `\\=0 \catcode `\{=1 \catcode `\}=2 + \catcode `\$=3 \catcode `\&=4 \catcode `\#=6 + \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie + \catcode `\%=14 + \catcode `\+=\other + \catcode `\"=\other + \catcode `\|=\other + \catcode `\<=\other + \catcode `\>=\other + \escapechar=`\\ + % + \let\b=\ptexb + \let\bullet=\ptexbullet + \let\c=\ptexc + \let\,=\ptexcomma + \let\.=\ptexdot + \let\dots=\ptexdots + \let\equiv=\ptexequiv + \let\!=\ptexexclam + \let\i=\ptexi + \let\indent=\ptexindent + \let\noindent=\ptexnoindent + \let\{=\ptexlbrace + \let\+=\tabalign + \let\}=\ptexrbrace + \let\/=\ptexslash + \let\*=\ptexstar + \let\t=\ptext + \let\frenchspacing=\plainfrenchspacing + % + \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% + \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}% + \def\@{@}% +} +% There is no need to define \Etex. + +% Define @lisp ... @end lisp. +% @lisp environment forms a group so it can rebind things, +% including the definition of @end lisp (which normally is erroneous). + +% Amount to narrow the margins by for @lisp. +\newskip\lispnarrowing \lispnarrowing=0.4in + +% This is the definition that ^^M gets inside @lisp, @example, and other +% such environments. \null is better than a space, since it doesn't +% have any width. +\def\lisppar{\null\endgraf} + +% This space is always present above and below environments. +\newskip\envskipamount \envskipamount = 0pt + +% Make spacing and below environment symmetrical. We use \parskip here +% to help in doing that, since in @example-like environments \parskip +% is reset to zero; thus the \afterenvbreak inserts no space -- but the +% start of the next paragraph will insert \parskip. +% +\def\aboveenvbreak{{% + % =10000 instead of <10000 because of a special case in \itemzzz and + % \sectionheading, q.v. + \ifnum \lastpenalty=10000 \else + \advance\envskipamount by \parskip + \endgraf + \ifdim\lastskip<\envskipamount + \removelastskip + % it's not a good place to break if the last penalty was \nobreak + % or better ... + \ifnum\lastpenalty<10000 \penalty-50 \fi + \vskip\envskipamount + \fi + \fi +}} + +\let\afterenvbreak = \aboveenvbreak + +% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins; it will +% also clear it, so that its embedded environments do the narrowing again. +\let\nonarrowing=\relax + +% @cartouche ... @end cartouche: draw rectangle w/rounded corners around +% environment contents. +\font\circle=lcircle10 +\newdimen\circthick +\newdimen\cartouter\newdimen\cartinner +\newskip\normbskip\newskip\normpskip\newskip\normlskip +\circthick=\fontdimen8\circle +% +\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth +\def\ctr{{\hskip 6pt\circle\char'010}} +\def\cbl{{\circle\char'012\hskip -6pt}} +\def\cbr{{\hskip 6pt\circle\char'011}} +\def\carttop{\hbox to \cartouter{\hskip\lskip + \ctl\leaders\hrule height\circthick\hfil\ctr + \hskip\rskip}} +\def\cartbot{\hbox to \cartouter{\hskip\lskip + \cbl\leaders\hrule height\circthick\hfil\cbr + \hskip\rskip}} +% +\newskip\lskip\newskip\rskip + +\envdef\cartouche{% + \ifhmode\par\fi % can't be in the midst of a paragraph. + \startsavinginserts + \lskip=\leftskip \rskip=\rightskip + \leftskip=0pt\rightskip=0pt % we want these *outside*. + \cartinner=\hsize \advance\cartinner by-\lskip + \advance\cartinner by-\rskip + \cartouter=\hsize + \advance\cartouter by 18.4pt % allow for 3pt kerns on either + % side, and for 6pt waste from + % each corner char, and rule thickness + \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip + % Flag to tell @lisp, etc., not to narrow margin. + \let\nonarrowing = t% + \vbox\bgroup + \baselineskip=0pt\parskip=0pt\lineskip=0pt + \carttop + \hbox\bgroup + \hskip\lskip + \vrule\kern3pt + \vbox\bgroup + \kern3pt + \hsize=\cartinner + \baselineskip=\normbskip + \lineskip=\normlskip + \parskip=\normpskip + \vskip -\parskip + \comment % For explanation, see the end of \def\group. +} +\def\Ecartouche{% + \ifhmode\par\fi + \kern3pt + \egroup + \kern3pt\vrule + \hskip\rskip + \egroup + \cartbot + \egroup + \checkinserts +} + + +% This macro is called at the beginning of all the @example variants, +% inside a group. +\def\nonfillstart{% + \aboveenvbreak + \hfuzz = 12pt % Don't be fussy + \sepspaces % Make spaces be word-separators rather than space tokens. + \let\par = \lisppar % don't ignore blank lines + \obeylines % each line of input is a line of output + \parskip = 0pt + \parindent = 0pt + \emergencystretch = 0pt % don't try to avoid overfull boxes + \ifx\nonarrowing\relax + \advance \leftskip by \lispnarrowing + \exdentamount=\lispnarrowing + \else + \let\nonarrowing = \relax + \fi + \let\exdent=\nofillexdent +} + +% If you want all examples etc. small: @set dispenvsize small. +% If you want even small examples the full size: @set dispenvsize nosmall. +% This affects the following displayed environments: +% @example, @display, @format, @lisp +% +\def\smallword{small} +\def\nosmallword{nosmall} +\let\SETdispenvsize\relax +\def\setnormaldispenv{% + \ifx\SETdispenvsize\smallword + % end paragraph for sake of leading, in case document has no blank + % line. This is redundant with what happens in \aboveenvbreak, but + % we need to do it before changing the fonts, and it's inconvenient + % to change the fonts afterward. + \ifnum \lastpenalty=10000 \else \endgraf \fi + \smallexamplefonts \rm + \fi +} +\def\setsmalldispenv{% + \ifx\SETdispenvsize\nosmallword + \else + \ifnum \lastpenalty=10000 \else \endgraf \fi + \smallexamplefonts \rm + \fi +} + +% We often define two environments, @foo and @smallfoo. +% Let's do it by one command: +\def\makedispenv #1#2{ + \expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2} + \expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2} + \expandafter\let\csname E#1\endcsname \afterenvbreak + \expandafter\let\csname Esmall#1\endcsname \afterenvbreak +} + +% Define two synonyms: +\def\maketwodispenvs #1#2#3{ + \makedispenv{#1}{#3} + \makedispenv{#2}{#3} +} + +% @lisp: indented, narrowed, typewriter font; @example: same as @lisp. +% +% @smallexample and @smalllisp: use smaller fonts. +% Originally contributed by Pavel@xerox. +% +\maketwodispenvs {lisp}{example}{% + \nonfillstart + \tt\quoteexpand + \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special. + \gobble % eat return +} +% @display/@smalldisplay: same as @lisp except keep current font. +% +\makedispenv {display}{% + \nonfillstart + \gobble +} + +% @format/@smallformat: same as @display except don't narrow margins. +% +\makedispenv{format}{% + \let\nonarrowing = t% + \nonfillstart + \gobble +} + +% @flushleft: same as @format, but doesn't obey \SETdispenvsize. +\envdef\flushleft{% + \let\nonarrowing = t% + \nonfillstart + \gobble +} +\let\Eflushleft = \afterenvbreak + +% @flushright. +% +\envdef\flushright{% + \let\nonarrowing = t% + \nonfillstart + \advance\leftskip by 0pt plus 1fill + \gobble +} +\let\Eflushright = \afterenvbreak + + +% @quotation does normal linebreaking (hence we can't use \nonfillstart) +% and narrows the margins. We keep \parskip nonzero in general, since +% we're doing normal filling. So, when using \aboveenvbreak and +% \afterenvbreak, temporarily make \parskip 0. +% +\envdef\quotation{% + {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip + \parindent=0pt + % + % @cartouche defines \nonarrowing to inhibit narrowing at next level down. + \ifx\nonarrowing\relax + \advance\leftskip by \lispnarrowing + \advance\rightskip by \lispnarrowing + \exdentamount = \lispnarrowing + \else + \let\nonarrowing = \relax + \fi + \parsearg\quotationlabel +} + +% We have retained a nonzero parskip for the environment, since we're +% doing normal filling. +% +\def\Equotation{% + \par + \ifx\quotationauthor\undefined\else + % indent a bit. + \leftline{\kern 2\leftskip \sl ---\quotationauthor}% + \fi + {\parskip=0pt \afterenvbreak}% +} + +% If we're given an argument, typeset it in bold with a colon after. +\def\quotationlabel#1{% + \def\temp{#1}% + \ifx\temp\empty \else + {\bf #1: }% + \fi +} + + +% LaTeX-like @verbatim...@end verbatim and @verb{<char>...<char>} +% If we want to allow any <char> as delimiter, +% we need the curly braces so that makeinfo sees the @verb command, eg: +% `@verbx...x' would look like the '@verbx' command. --janneke@gnu.org +% +% [Knuth]: Donald Ervin Knuth, 1996. The TeXbook. +% +% [Knuth] p.344; only we need to do the other characters Texinfo sets +% active too. Otherwise, they get lost as the first character on a +% verbatim line. +\def\dospecials{% + \do\ \do\\\do\{\do\}\do\$\do\&% + \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~% + \do\<\do\>\do\|\do\@\do+\do\"% +} +% +% [Knuth] p. 380 +\def\uncatcodespecials{% + \def\do##1{\catcode`##1=\other}\dospecials} +% +% [Knuth] pp. 380,381,391 +% Disable Spanish ligatures ?` and !` of \tt font +\begingroup + \catcode`\`=\active\gdef`{\relax\lq} +\endgroup +% +% Setup for the @verb command. +% +% Eight spaces for a tab +\begingroup + \catcode`\^^I=\active + \gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }} +\endgroup +% +\def\setupverb{% + \tt % easiest (and conventionally used) font for verbatim + \def\par{\leavevmode\endgraf}% + \catcode`\`=\active + \tabeightspaces + % Respect line breaks, + % print special symbols as themselves, and + % make each space count + % must do in this order: + \obeylines \uncatcodespecials \sepspaces +} + +% Setup for the @verbatim environment +% +% Real tab expansion +\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount +% +\def\starttabbox{\setbox0=\hbox\bgroup} + +% Allow an option to not replace quotes with a regular directed right +% quote/apostrophe (char 0x27), but instead use the undirected quote +% from cmtt (char 0x0d). The undirected quote is ugly, so don't make it +% the default, but it works for pasting with more pdf viewers (at least +% evince), the lilypond developers report. xpdf does work with the +% regular 0x27. +% +\def\codequoteright{% + \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax + \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax + '% + \else \char'15 \fi + \else \char'15 \fi +} +% +% and a similar option for the left quote char vs. a grave accent. +% Modern fonts display ASCII 0x60 as a grave accent, so some people like +% the code environments to do likewise. +% +\def\codequoteleft{% + \expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax + \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax + `% + \else \char'22 \fi + \else \char'22 \fi +} +% +\begingroup + \catcode`\^^I=\active + \gdef\tabexpand{% + \catcode`\^^I=\active + \def^^I{\leavevmode\egroup + \dimen0=\wd0 % the width so far, or since the previous tab + \divide\dimen0 by\tabw + \multiply\dimen0 by\tabw % compute previous multiple of \tabw + \advance\dimen0 by\tabw % advance to next multiple of \tabw + \wd0=\dimen0 \box0 \starttabbox + }% + } + \catcode`\'=\active + \gdef\rquoteexpand{\catcode\rquoteChar=\active \def'{\codequoteright}}% + % + \catcode`\`=\active + \gdef\lquoteexpand{\catcode\lquoteChar=\active \def`{\codequoteleft}}% + % + \gdef\quoteexpand{\rquoteexpand \lquoteexpand}% +\endgroup + +% start the verbatim environment. +\def\setupverbatim{% + \let\nonarrowing = t% + \nonfillstart + % Easiest (and conventionally used) font for verbatim + \tt + \def\par{\leavevmode\egroup\box0\endgraf}% + \catcode`\`=\active + \tabexpand + \quoteexpand + % Respect line breaks, + % print special symbols as themselves, and + % make each space count + % must do in this order: + \obeylines \uncatcodespecials \sepspaces + \everypar{\starttabbox}% +} + +% Do the @verb magic: verbatim text is quoted by unique +% delimiter characters. Before first delimiter expect a +% right brace, after last delimiter expect closing brace: +% +% \def\doverb'{'<char>#1<char>'}'{#1} +% +% [Knuth] p. 382; only eat outer {} +\begingroup + \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other + \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next] +\endgroup +% +\def\verb{\begingroup\setupverb\doverb} +% +% +% Do the @verbatim magic: define the macro \doverbatim so that +% the (first) argument ends when '@end verbatim' is reached, ie: +% +% \def\doverbatim#1@end verbatim{#1} +% +% For Texinfo it's a lot easier than for LaTeX, +% because texinfo's \verbatim doesn't stop at '\end{verbatim}': +% we need not redefine '\', '{' and '}'. +% +% Inspired by LaTeX's verbatim command set [latex.ltx] +% +\begingroup + \catcode`\ =\active + \obeylines % + % ignore everything up to the first ^^M, that's the newline at the end + % of the @verbatim input line itself. Otherwise we get an extra blank + % line in the output. + \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}% + % We really want {...\end verbatim} in the body of the macro, but + % without the active space; thus we have to use \xdef and \gobble. +\endgroup +% +\envdef\verbatim{% + \setupverbatim\doverbatim +} +\let\Everbatim = \afterenvbreak + + +% @verbatiminclude FILE - insert text of file in verbatim environment. +% +\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude} +% +\def\doverbatiminclude#1{% + {% + \makevalueexpandable + \setupverbatim + \input #1 + \afterenvbreak + }% +} + +% @copying ... @end copying. +% Save the text away for @insertcopying later. +% +% We save the uninterpreted tokens, rather than creating a box. +% Saving the text in a box would be much easier, but then all the +% typesetting commands (@smallbook, font changes, etc.) have to be done +% beforehand -- and a) we want @copying to be done first in the source +% file; b) letting users define the frontmatter in as flexible order as +% possible is very desirable. +% +\def\copying{\checkenv{}\begingroup\scanargctxt\docopying} +\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}} +% +\def\insertcopying{% + \begingroup + \parindent = 0pt % paragraph indentation looks wrong on title page + \scanexp\copyingtext + \endgroup +} + + +\message{defuns,} +% @defun etc. + +\newskip\defbodyindent \defbodyindent=.4in +\newskip\defargsindent \defargsindent=50pt +\newskip\deflastargmargin \deflastargmargin=18pt +\newcount\defunpenalty + +% Start the processing of @deffn: +\def\startdefun{% + \ifnum\lastpenalty<10000 + \medbreak + \defunpenalty=10003 % Will keep this @deffn together with the + % following @def command, see below. + \else + % If there are two @def commands in a row, we'll have a \nobreak, + % which is there to keep the function description together with its + % header. But if there's nothing but headers, we need to allow a + % break somewhere. Check specifically for penalty 10002, inserted + % by \printdefunline, instead of 10000, since the sectioning + % commands also insert a nobreak penalty, and we don't want to allow + % a break between a section heading and a defun. + % + % As a minor refinement, we avoid "club" headers by signalling + % with penalty of 10003 after the very first @deffn in the + % sequence (see above), and penalty of 10002 after any following + % @def command. + \ifnum\lastpenalty=10002 \penalty2000 \else \defunpenalty=10002 \fi + % + % Similarly, after a section heading, do not allow a break. + % But do insert the glue. + \medskip % preceded by discardable penalty, so not a breakpoint + \fi + % + \parindent=0in + \advance\leftskip by \defbodyindent + \exdentamount=\defbodyindent +} + +\def\dodefunx#1{% + % First, check whether we are in the right environment: + \checkenv#1% + % + % As above, allow line break if we have multiple x headers in a row. + % It's not a great place, though. + \ifnum\lastpenalty=10002 \penalty3000 \else \defunpenalty=10002 \fi + % + % And now, it's time to reuse the body of the original defun: + \expandafter\gobbledefun#1% +} +\def\gobbledefun#1\startdefun{} + +% \printdefunline \deffnheader{text} +% +\def\printdefunline#1#2{% + \begingroup + % call \deffnheader: + #1#2 \endheader + % common ending: + \interlinepenalty = 10000 + \advance\rightskip by 0pt plus 1fil + \endgraf + \nobreak\vskip -\parskip + \penalty\defunpenalty % signal to \startdefun and \dodefunx + % Some of the @defun-type tags do not enable magic parentheses, + % rendering the following check redundant. But we don't optimize. + \checkparencounts + \endgroup +} + +\def\Edefun{\endgraf\medbreak} + +% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn; +% the only thing remainnig is to define \deffnheader. +% +\def\makedefun#1{% + \expandafter\let\csname E#1\endcsname = \Edefun + \edef\temp{\noexpand\domakedefun + \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}% + \temp +} + +% \domakedefun \deffn \deffnx \deffnheader +% +% Define \deffn and \deffnx, without parameters. +% \deffnheader has to be defined explicitly. +% +\def\domakedefun#1#2#3{% + \envdef#1{% + \startdefun + \parseargusing\activeparens{\printdefunline#3}% + }% + \def#2{\dodefunx#1}% + \def#3% +} + +%%% Untyped functions: + +% @deffn category name args +\makedefun{deffn}{\deffngeneral{}} + +% @deffn category class name args +\makedefun{defop}#1 {\defopon{#1\ \putwordon}} + +% \defopon {category on}class name args +\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } + +% \deffngeneral {subind}category name args +% +\def\deffngeneral#1#2 #3 #4\endheader{% + % Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}. + \dosubind{fn}{\code{#3}}{#1}% + \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}% +} + +%%% Typed functions: + +% @deftypefn category type name args +\makedefun{deftypefn}{\deftypefngeneral{}} + +% @deftypeop category class type name args +\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}} + +% \deftypeopon {category on}class type name args +\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } + +% \deftypefngeneral {subind}category type name args +% +\def\deftypefngeneral#1#2 #3 #4 #5\endheader{% + \dosubind{fn}{\code{#4}}{#1}% + \defname{#2}{#3}{#4}\defunargs{#5\unskip}% +} + +%%% Typed variables: + +% @deftypevr category type var args +\makedefun{deftypevr}{\deftypecvgeneral{}} + +% @deftypecv category class type var args +\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}} + +% \deftypecvof {category of}class type var args +\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} } + +% \deftypecvgeneral {subind}category type var args +% +\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{% + \dosubind{vr}{\code{#4}}{#1}% + \defname{#2}{#3}{#4}\defunargs{#5\unskip}% +} + +%%% Untyped variables: + +% @defvr category var args +\makedefun{defvr}#1 {\deftypevrheader{#1} {} } + +% @defcv category class var args +\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}} + +% \defcvof {category of}class var args +\def\defcvof#1#2 {\deftypecvof{#1}#2 {} } + +%%% Type: +% @deftp category name args +\makedefun{deftp}#1 #2 #3\endheader{% + \doind{tp}{\code{#2}}% + \defname{#1}{}{#2}\defunargs{#3\unskip}% +} + +% Remaining @defun-like shortcuts: +\makedefun{defun}{\deffnheader{\putwordDeffunc} } +\makedefun{defmac}{\deffnheader{\putwordDefmac} } +\makedefun{defspec}{\deffnheader{\putwordDefspec} } +\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} } +\makedefun{defvar}{\defvrheader{\putwordDefvar} } +\makedefun{defopt}{\defvrheader{\putwordDefopt} } +\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} } +\makedefun{defmethod}{\defopon\putwordMethodon} +\makedefun{deftypemethod}{\deftypeopon\putwordMethodon} +\makedefun{defivar}{\defcvof\putwordInstanceVariableof} +\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof} + +% \defname, which formats the name of the @def (not the args). +% #1 is the category, such as "Function". +% #2 is the return type, if any. +% #3 is the function name. +% +% We are followed by (but not passed) the arguments, if any. +% +\def\defname#1#2#3{% + % Get the values of \leftskip and \rightskip as they were outside the @def... + \advance\leftskip by -\defbodyindent + % + % How we'll format the type name. Putting it in brackets helps + % distinguish it from the body text that may end up on the next line + % just below it. + \def\temp{#1}% + \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi} + % + % Figure out line sizes for the paragraph shape. + % The first line needs space for \box0; but if \rightskip is nonzero, + % we need only space for the part of \box0 which exceeds it: + \dimen0=\hsize \advance\dimen0 by -\wd0 \advance\dimen0 by \rightskip + % The continuations: + \dimen2=\hsize \advance\dimen2 by -\defargsindent + % (plain.tex says that \dimen1 should be used only as global.) + \parshape 2 0in \dimen0 \defargsindent \dimen2 + % + % Put the type name to the right margin. + \noindent + \hbox to 0pt{% + \hfil\box0 \kern-\hsize + % \hsize has to be shortened this way: + \kern\leftskip + % Intentionally do not respect \rightskip, since we need the space. + }% + % + % Allow all lines to be underfull without complaint: + \tolerance=10000 \hbadness=10000 + \exdentamount=\defbodyindent + {% + % defun fonts. We use typewriter by default (used to be bold) because: + % . we're printing identifiers, they should be in tt in principle. + % . in languages with many accents, such as Czech or French, it's + % common to leave accents off identifiers. The result looks ok in + % tt, but exceedingly strange in rm. + % . we don't want -- and --- to be treated as ligatures. + % . this still does not fix the ?` and !` ligatures, but so far no + % one has made identifiers using them :). + \df \tt + \def\temp{#2}% return value type + \ifx\temp\empty\else \tclose{\temp} \fi + #3% output function name + }% + {\rm\enskip}% hskip 0.5 em of \tenrm + % + \boldbrax + % arguments will be output next, if any. +} + +% Print arguments in slanted roman (not ttsl), inconsistently with using +% tt for the name. This is because literal text is sometimes needed in +% the argument list (groff manual), and ttsl and tt are not very +% distinguishable. Prevent hyphenation at `-' chars. +% +\def\defunargs#1{% + % use sl by default (not ttsl), + % tt for the names. + \df \sl \hyphenchar\font=0 + % + % On the other hand, if an argument has two dashes (for instance), we + % want a way to get ttsl. Let's try @var for that. + \let\var=\ttslanted + #1% + \sl\hyphenchar\font=45 +} + +% We want ()&[] to print specially on the defun line. +% +\def\activeparens{% + \catcode`\(=\active \catcode`\)=\active + \catcode`\[=\active \catcode`\]=\active + \catcode`\&=\active +} + +% Make control sequences which act like normal parenthesis chars. +\let\lparen = ( \let\rparen = ) + +% Be sure that we always have a definition for `(', etc. For example, +% if the fn name has parens in it, \boldbrax will not be in effect yet, +% so TeX would otherwise complain about undefined control sequence. +{ + \activeparens + \global\let(=\lparen \global\let)=\rparen + \global\let[=\lbrack \global\let]=\rbrack + \global\let& = \& + + \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} + \gdef\magicamp{\let&=\amprm} +} + +\newcount\parencount + +% If we encounter &foo, then turn on ()-hacking afterwards +\newif\ifampseen +\def\amprm#1 {\ampseentrue{\bf\ }} + +\def\parenfont{% + \ifampseen + % At the first level, print parens in roman, + % otherwise use the default font. + \ifnum \parencount=1 \rm \fi + \else + % The \sf parens (in \boldbrax) actually are a little bolder than + % the contained text. This is especially needed for [ and ] . + \sf + \fi +} +\def\infirstlevel#1{% + \ifampseen + \ifnum\parencount=1 + #1% + \fi + \fi +} +\def\bfafterword#1 {#1 \bf} + +\def\opnr{% + \global\advance\parencount by 1 + {\parenfont(}% + \infirstlevel \bfafterword +} +\def\clnr{% + {\parenfont)}% + \infirstlevel \sl + \global\advance\parencount by -1 +} + +\newcount\brackcount +\def\lbrb{% + \global\advance\brackcount by 1 + {\bf[}% +} +\def\rbrb{% + {\bf]}% + \global\advance\brackcount by -1 +} + +\def\checkparencounts{% + \ifnum\parencount=0 \else \badparencount \fi + \ifnum\brackcount=0 \else \badbrackcount \fi +} +% these should not use \errmessage; the glibc manual, at least, actually +% has such constructs (when documenting function pointers). +\def\badparencount{% + \message{Warning: unbalanced parentheses in @def...}% + \global\parencount=0 +} +\def\badbrackcount{% + \message{Warning: unbalanced square brackets in @def...}% + \global\brackcount=0 +} + + +\message{macros,} +% @macro. + +% To do this right we need a feature of e-TeX, \scantokens, +% which we arrange to emulate with a temporary file in ordinary TeX. +\ifx\eTeXversion\undefined + \newwrite\macscribble + \def\scantokens#1{% + \toks0={#1}% + \immediate\openout\macscribble=\jobname.tmp + \immediate\write\macscribble{\the\toks0}% + \immediate\closeout\macscribble + \input \jobname.tmp + } +\fi + +\def\scanmacro#1{% + \begingroup + \newlinechar`\^^M + \let\xeatspaces\eatspaces + % Undo catcode changes of \startcontents and \doprintindex + % When called from @insertcopying or (short)caption, we need active + % backslash to get it printed correctly. Previously, we had + % \catcode`\\=\other instead. We'll see whether a problem appears + % with macro expansion. --kasal, 19aug04 + \catcode`\@=0 \catcode`\\=\active \escapechar=`\@ + % ... and \example + \spaceisspace + % + % Append \endinput to make sure that TeX does not see the ending newline. + % I've verified that it is necessary both for e-TeX and for ordinary TeX + % --kasal, 29nov03 + \scantokens{#1\endinput}% + \endgroup +} + +\def\scanexp#1{% + \edef\temp{\noexpand\scanmacro{#1}}% + \temp +} + +\newcount\paramno % Count of parameters +\newtoks\macname % Macro name +\newif\ifrecursive % Is it recursive? + +% List of all defined macros in the form +% \definedummyword\macro1\definedummyword\macro2... +% Currently is also contains all @aliases; the list can be split +% if there is a need. +\def\macrolist{} + +% Add the macro to \macrolist +\def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname} +\def\addtomacrolistxxx#1{% + \toks0 = \expandafter{\macrolist\definedummyword#1}% + \xdef\macrolist{\the\toks0}% +} + +% Utility routines. +% This does \let #1 = #2, with \csnames; that is, +% \let \csname#1\endcsname = \csname#2\endcsname +% (except of course we have to play expansion games). +% +\def\cslet#1#2{% + \expandafter\let + \csname#1\expandafter\endcsname + \csname#2\endcsname +} + +% Trim leading and trailing spaces off a string. +% Concepts from aro-bend problem 15 (see CTAN). +{\catcode`\@=11 +\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }} +\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@} +\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @} +\def\unbrace#1{#1} +\unbrace{\gdef\trim@@@ #1 } #2@{#1} +} + +% Trim a single trailing ^^M off a string. +{\catcode`\^^M=\other \catcode`\Q=3% +\gdef\eatcr #1{\eatcra #1Q^^MQ}% +\gdef\eatcra#1^^MQ{\eatcrb#1Q}% +\gdef\eatcrb#1Q#2Q{#1}% +} + +% Macro bodies are absorbed as an argument in a context where +% all characters are catcode 10, 11 or 12, except \ which is active +% (as in normal texinfo). It is necessary to change the definition of \. + +% Non-ASCII encodings make 8-bit characters active, so un-activate +% them to avoid their expansion. Must do this non-globally, to +% confine the change to the current group. + +% It's necessary to have hard CRs when the macro is executed. This is +% done by making ^^M (\endlinechar) catcode 12 when reading the macro +% body, and then making it the \newlinechar in \scanmacro. + +\def\scanctxt{% + \catcode`\"=\other + \catcode`\+=\other + \catcode`\<=\other + \catcode`\>=\other + \catcode`\@=\other + \catcode`\^=\other + \catcode`\_=\other + \catcode`\|=\other + \catcode`\~=\other + \ifx\declaredencoding\ascii \else \setnonasciicharscatcodenonglobal\other \fi +} + +\def\scanargctxt{% + \scanctxt + \catcode`\\=\other + \catcode`\^^M=\other +} + +\def\macrobodyctxt{% + \scanctxt + \catcode`\{=\other + \catcode`\}=\other + \catcode`\^^M=\other + \usembodybackslash +} + +\def\macroargctxt{% + \scanctxt + \catcode`\\=\other +} + +% \mbodybackslash is the definition of \ in @macro bodies. +% It maps \foo\ => \csname macarg.foo\endcsname => #N +% where N is the macro parameter number. +% We define \csname macarg.\endcsname to be \realbackslash, so +% \\ in macro replacement text gets you a backslash. + +{\catcode`@=0 @catcode`@\=@active + @gdef@usembodybackslash{@let\=@mbodybackslash} + @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname} +} +\expandafter\def\csname macarg.\endcsname{\realbackslash} + +\def\macro{\recursivefalse\parsearg\macroxxx} +\def\rmacro{\recursivetrue\parsearg\macroxxx} + +\def\macroxxx#1{% + \getargs{#1}% now \macname is the macname and \argl the arglist + \ifx\argl\empty % no arguments + \paramno=0% + \else + \expandafter\parsemargdef \argl;% + \fi + \if1\csname ismacro.\the\macname\endcsname + \message{Warning: redefining \the\macname}% + \else + \expandafter\ifx\csname \the\macname\endcsname \relax + \else \errmessage{Macro name \the\macname\space already defined}\fi + \global\cslet{macsave.\the\macname}{\the\macname}% + \global\expandafter\let\csname ismacro.\the\macname\endcsname=1% + \addtomacrolist{\the\macname}% + \fi + \begingroup \macrobodyctxt + \ifrecursive \expandafter\parsermacbody + \else \expandafter\parsemacbody + \fi} + +\parseargdef\unmacro{% + \if1\csname ismacro.#1\endcsname + \global\cslet{#1}{macsave.#1}% + \global\expandafter\let \csname ismacro.#1\endcsname=0% + % Remove the macro name from \macrolist: + \begingroup + \expandafter\let\csname#1\endcsname \relax + \let\definedummyword\unmacrodo + \xdef\macrolist{\macrolist}% + \endgroup + \else + \errmessage{Macro #1 not defined}% + \fi +} + +% Called by \do from \dounmacro on each macro. The idea is to omit any +% macro definitions that have been changed to \relax. +% +\def\unmacrodo#1{% + \ifx #1\relax + % remove this + \else + \noexpand\definedummyword \noexpand#1% + \fi +} + +% This makes use of the obscure feature that if the last token of a +% <parameter list> is #, then the preceding argument is delimited by +% an opening brace, and that opening brace is not consumed. +\def\getargs#1{\getargsxxx#1{}} +\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs} +\def\getmacname #1 #2\relax{\macname={#1}} +\def\getmacargs#1{\def\argl{#1}} + +% Parse the optional {params} list. Set up \paramno and \paramlist +% so \defmacro knows what to do. Define \macarg.blah for each blah +% in the params list, to be ##N where N is the position in that list. +% That gets used by \mbodybackslash (above). + +% We need to get `macro parameter char #' into several definitions. +% The technique used is stolen from LaTeX: let \hash be something +% unexpandable, insert that wherever you need a #, and then redefine +% it to # just before using the token list produced. +% +% The same technique is used to protect \eatspaces till just before +% the macro is used. + +\def\parsemargdef#1;{\paramno=0\def\paramlist{}% + \let\hash\relax\let\xeatspaces\relax\parsemargdefxxx#1,;,} +\def\parsemargdefxxx#1,{% + \if#1;\let\next=\relax + \else \let\next=\parsemargdefxxx + \advance\paramno by 1% + \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname + {\xeatspaces{\hash\the\paramno}}% + \edef\paramlist{\paramlist\hash\the\paramno,}% + \fi\next} + +% These two commands read recursive and nonrecursive macro bodies. +% (They're different since rec and nonrec macros end differently.) + +\long\def\parsemacbody#1@end macro% +{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% +\long\def\parsermacbody#1@end rmacro% +{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% + +% This defines the macro itself. There are six cases: recursive and +% nonrecursive macros of zero, one, and many arguments. +% Much magic with \expandafter here. +% \xdef is used so that macro definitions will survive the file +% they're defined in; @include reads the file inside a group. +\def\defmacro{% + \let\hash=##% convert placeholders to macro parameter chars + \ifrecursive + \ifcase\paramno + % 0 + \expandafter\xdef\csname\the\macname\endcsname{% + \noexpand\scanmacro{\temp}}% + \or % 1 + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \noexpand\braceorline + \expandafter\noexpand\csname\the\macname xxx\endcsname}% + \expandafter\xdef\csname\the\macname xxx\endcsname##1{% + \egroup\noexpand\scanmacro{\temp}}% + \else % many + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \noexpand\csname\the\macname xx\endcsname}% + \expandafter\xdef\csname\the\macname xx\endcsname##1{% + \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% + \expandafter\expandafter + \expandafter\xdef + \expandafter\expandafter + \csname\the\macname xxx\endcsname + \paramlist{\egroup\noexpand\scanmacro{\temp}}% + \fi + \else + \ifcase\paramno + % 0 + \expandafter\xdef\csname\the\macname\endcsname{% + \noexpand\norecurse{\the\macname}% + \noexpand\scanmacro{\temp}\egroup}% + \or % 1 + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \noexpand\braceorline + \expandafter\noexpand\csname\the\macname xxx\endcsname}% + \expandafter\xdef\csname\the\macname xxx\endcsname##1{% + \egroup + \noexpand\norecurse{\the\macname}% + \noexpand\scanmacro{\temp}\egroup}% + \else % many + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \expandafter\noexpand\csname\the\macname xx\endcsname}% + \expandafter\xdef\csname\the\macname xx\endcsname##1{% + \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% + \expandafter\expandafter + \expandafter\xdef + \expandafter\expandafter + \csname\the\macname xxx\endcsname + \paramlist{% + \egroup + \noexpand\norecurse{\the\macname}% + \noexpand\scanmacro{\temp}\egroup}% + \fi + \fi} + +\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}} + +% \braceorline decides whether the next nonwhitespace character is a +% {. If so it reads up to the closing }, if not, it reads the whole +% line. Whatever was read is then fed to the next control sequence +% as an argument (by \parsebrace or \parsearg) +\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx} +\def\braceorlinexxx{% + \ifx\nchar\bgroup\else + \expandafter\parsearg + \fi \macnamexxx} + + +% @alias. +% We need some trickery to remove the optional spaces around the equal +% sign. Just make them active and then expand them all to nothing. +\def\alias{\parseargusing\obeyspaces\aliasxxx} +\def\aliasxxx #1{\aliasyyy#1\relax} +\def\aliasyyy #1=#2\relax{% + {% + \expandafter\let\obeyedspace=\empty + \addtomacrolist{#1}% + \xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}% + }% + \next +} + + +\message{cross references,} + +\newwrite\auxfile +\newif\ifhavexrefs % True if xref values are known. +\newif\ifwarnedxrefs % True if we warned once that they aren't known. + +% @inforef is relatively simple. +\def\inforef #1{\inforefzzz #1,,,,**} +\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, + node \samp{\ignorespaces#1{}}} + +% @node's only job in TeX is to define \lastnode, which is used in +% cross-references. The @node line might or might not have commas, and +% might or might not have spaces before the first comma, like: +% @node foo , bar , ... +% We don't want such trailing spaces in the node name. +% +\parseargdef\node{\checkenv{}\donode #1 ,\finishnodeparse} +% +% also remove a trailing comma, in case of something like this: +% @node Help-Cross, , , Cross-refs +\def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse} +\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}} + +\let\nwnode=\node +\let\lastnode=\empty + +% Write a cross-reference definition for the current node. #1 is the +% type (Ynumbered, Yappendix, Ynothing). +% +\def\donoderef#1{% + \ifx\lastnode\empty\else + \setref{\lastnode}{#1}% + \global\let\lastnode=\empty + \fi +} + +% @anchor{NAME} -- define xref target at arbitrary point. +% +\newcount\savesfregister +% +\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi} +\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi} +\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces} + +% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an +% anchor), which consists of three parts: +% 1) NAME-title - the current sectioning name taken from \lastsection, +% or the anchor name. +% 2) NAME-snt - section number and type, passed as the SNT arg, or +% empty for anchors. +% 3) NAME-pg - the page number. +% +% This is called from \donoderef, \anchor, and \dofloat. In the case of +% floats, there is an additional part, which is not written here: +% 4) NAME-lof - the text as it should appear in a @listoffloats. +% +\def\setref#1#2{% + \pdfmkdest{#1}% + \iflinks + {% + \atdummies % preserve commands, but don't expand them + \edef\writexrdef##1##2{% + \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef + ##1}{##2}}% these are parameters of \writexrdef + }% + \toks0 = \expandafter{\lastsection}% + \immediate \writexrdef{title}{\the\toks0 }% + \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc. + \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, during \shipout + }% + \fi +} + +% @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is +% the node name, #2 the name of the Info cross-reference, #3 the printed +% node name, #4 the name of the Info file, #5 the name of the printed +% manual. All but the node name can be omitted. +% +\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} +\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} +\def\ref#1{\xrefX[#1,,,,,,,]} +\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup + \unsepspaces + \def\printedmanual{\ignorespaces #5}% + \def\printedrefname{\ignorespaces #3}% + \setbox1=\hbox{\printedmanual\unskip}% + \setbox0=\hbox{\printedrefname\unskip}% + \ifdim \wd0 = 0pt + % No printed node name was explicitly given. + \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax + % Use the node name inside the square brackets. + \def\printedrefname{\ignorespaces #1}% + \else + % Use the actual chapter/section title appear inside + % the square brackets. Use the real section title if we have it. + \ifdim \wd1 > 0pt + % It is in another manual, so we don't have it. + \def\printedrefname{\ignorespaces #1}% + \else + \ifhavexrefs + % We know the real title if we have the xref values. + \def\printedrefname{\refx{#1-title}{}}% + \else + % Otherwise just copy the Info node name. + \def\printedrefname{\ignorespaces #1}% + \fi% + \fi + \fi + \fi + % + % Make link in pdf output. + \ifpdf + \leavevmode + \getfilename{#4}% + {\indexnofonts + \turnoffactive + % See comments at \activebackslashdouble. + {\activebackslashdouble \xdef\pdfxrefdest{#1}% + \backslashparens\pdfxrefdest}% + % + \ifnum\filenamelength>0 + \startlink attr{/Border [0 0 0]}% + goto file{\the\filename.pdf} name{\pdfxrefdest}% + \else + \startlink attr{/Border [0 0 0]}% + goto name{\pdfmkpgn{\pdfxrefdest}}% + \fi + }% + \setcolor{\linkcolor}% + \fi + % + % Float references are printed completely differently: "Figure 1.2" + % instead of "[somenode], p.3". We distinguish them by the + % LABEL-title being set to a magic string. + {% + % Have to otherify everything special to allow the \csname to + % include an _ in the xref name, etc. + \indexnofonts + \turnoffactive + \expandafter\global\expandafter\let\expandafter\Xthisreftitle + \csname XR#1-title\endcsname + }% + \iffloat\Xthisreftitle + % If the user specified the print name (third arg) to the ref, + % print it instead of our usual "Figure 1.2". + \ifdim\wd0 = 0pt + \refx{#1-snt}{}% + \else + \printedrefname + \fi + % + % if the user also gave the printed manual name (fifth arg), append + % "in MANUALNAME". + \ifdim \wd1 > 0pt + \space \putwordin{} \cite{\printedmanual}% + \fi + \else + % node/anchor (non-float) references. + % + % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not + % insert empty discretionaries after hyphens, which means that it will + % not find a line break at a hyphen in a node names. Since some manuals + % are best written with fairly long node names, containing hyphens, this + % is a loss. Therefore, we give the text of the node name again, so it + % is as if TeX is seeing it for the first time. + \ifdim \wd1 > 0pt + \putwordSection{} ``\printedrefname'' \putwordin{} \cite{\printedmanual}% + \else + % _ (for example) has to be the character _ for the purposes of the + % control sequence corresponding to the node, but it has to expand + % into the usual \leavevmode...\vrule stuff for purposes of + % printing. So we \turnoffactive for the \refx-snt, back on for the + % printing, back off for the \refx-pg. + {\turnoffactive + % Only output a following space if the -snt ref is nonempty; for + % @unnumbered and @anchor, it won't be. + \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% + \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi + }% + % output the `[mynode]' via a macro so it can be overridden. + \xrefprintnodename\printedrefname + % + % But we always want a comma and a space: + ,\space + % + % output the `page 3'. + \turnoffactive \putwordpage\tie\refx{#1-pg}{}% + \fi + \fi + \endlink +\endgroup} + +% This macro is called from \xrefX for the `[nodename]' part of xref +% output. It's a separate macro only so it can be changed more easily, +% since square brackets don't work well in some documents. Particularly +% one that Bob is working on :). +% +\def\xrefprintnodename#1{[#1]} + +% Things referred to by \setref. +% +\def\Ynothing{} +\def\Yomitfromtoc{} +\def\Ynumbered{% + \ifnum\secno=0 + \putwordChapter@tie \the\chapno + \else \ifnum\subsecno=0 + \putwordSection@tie \the\chapno.\the\secno + \else \ifnum\subsubsecno=0 + \putwordSection@tie \the\chapno.\the\secno.\the\subsecno + \else + \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno + \fi\fi\fi +} +\def\Yappendix{% + \ifnum\secno=0 + \putwordAppendix@tie @char\the\appendixno{}% + \else \ifnum\subsecno=0 + \putwordSection@tie @char\the\appendixno.\the\secno + \else \ifnum\subsubsecno=0 + \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno + \else + \putwordSection@tie + @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno + \fi\fi\fi +} + +% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. +% If its value is nonempty, SUFFIX is output afterward. +% +\def\refx#1#2{% + {% + \indexnofonts + \otherbackslash + \expandafter\global\expandafter\let\expandafter\thisrefX + \csname XR#1\endcsname + }% + \ifx\thisrefX\relax + % If not defined, say something at least. + \angleleft un\-de\-fined\angleright + \iflinks + \ifhavexrefs + \message{\linenumber Undefined cross reference `#1'.}% + \else + \ifwarnedxrefs\else + \global\warnedxrefstrue + \message{Cross reference values unknown; you must run TeX again.}% + \fi + \fi + \fi + \else + % It's defined, so just use it. + \thisrefX + \fi + #2% Output the suffix in any case. +} + +% This is the macro invoked by entries in the aux file. Usually it's +% just a \def (we prepend XR to the control sequence name to avoid +% collisions). But if this is a float type, we have more work to do. +% +\def\xrdef#1#2{% + {% The node name might contain 8-bit characters, which in our current + % implementation are changed to commands like @'e. Don't let these + % mess up the control sequence name. + \indexnofonts + \turnoffactive + \xdef\safexrefname{#1}% + }% + % + \expandafter\gdef\csname XR\safexrefname\endcsname{#2}% remember this xref + % + % Was that xref control sequence that we just defined for a float? + \expandafter\iffloat\csname XR\safexrefname\endcsname + % it was a float, and we have the (safe) float type in \iffloattype. + \expandafter\let\expandafter\floatlist + \csname floatlist\iffloattype\endcsname + % + % Is this the first time we've seen this float type? + \expandafter\ifx\floatlist\relax + \toks0 = {\do}% yes, so just \do + \else + % had it before, so preserve previous elements in list. + \toks0 = \expandafter{\floatlist\do}% + \fi + % + % Remember this xref in the control sequence \floatlistFLOATTYPE, + % for later use in \listoffloats. + \expandafter\xdef\csname floatlist\iffloattype\endcsname{\the\toks0 + {\safexrefname}}% + \fi +} + +% Read the last existing aux file, if any. No error if none exists. +% +\def\tryauxfile{% + \openin 1 \jobname.aux + \ifeof 1 \else + \readdatafile{aux}% + \global\havexrefstrue + \fi + \closein 1 +} + +\def\setupdatafile{% + \catcode`\^^@=\other + \catcode`\^^A=\other + \catcode`\^^B=\other + \catcode`\^^C=\other + \catcode`\^^D=\other + \catcode`\^^E=\other + \catcode`\^^F=\other + \catcode`\^^G=\other + \catcode`\^^H=\other + \catcode`\^^K=\other + \catcode`\^^L=\other + \catcode`\^^N=\other + \catcode`\^^P=\other + \catcode`\^^Q=\other + \catcode`\^^R=\other + \catcode`\^^S=\other + \catcode`\^^T=\other + \catcode`\^^U=\other + \catcode`\^^V=\other + \catcode`\^^W=\other + \catcode`\^^X=\other + \catcode`\^^Z=\other + \catcode`\^^[=\other + \catcode`\^^\=\other + \catcode`\^^]=\other + \catcode`\^^^=\other + \catcode`\^^_=\other + % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc. + % in xref tags, i.e., node names. But since ^^e4 notation isn't + % supported in the main text, it doesn't seem desirable. Furthermore, + % that is not enough: for node names that actually contain a ^ + % character, we would end up writing a line like this: 'xrdef {'hat + % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first + % argument, and \hat is not an expandable control sequence. It could + % all be worked out, but why? Either we support ^^ or we don't. + % + % The other change necessary for this was to define \auxhat: + % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter + % and then to call \auxhat in \setq. + % + \catcode`\^=\other + % + % Special characters. Should be turned off anyway, but... + \catcode`\~=\other + \catcode`\[=\other + \catcode`\]=\other + \catcode`\"=\other + \catcode`\_=\other + \catcode`\|=\other + \catcode`\<=\other + \catcode`\>=\other + \catcode`\$=\other + \catcode`\#=\other + \catcode`\&=\other + \catcode`\%=\other + \catcode`+=\other % avoid \+ for paranoia even though we've turned it off + % + % This is to support \ in node names and titles, since the \ + % characters end up in a \csname. It's easier than + % leaving it active and making its active definition an actual \ + % character. What I don't understand is why it works in the *value* + % of the xrdef. Seems like it should be a catcode12 \, and that + % should not typeset properly. But it works, so I'm moving on for + % now. --karl, 15jan04. + \catcode`\\=\other + % + % Make the characters 128-255 be printing characters. + {% + \count1=128 + \def\loop{% + \catcode\count1=\other + \advance\count1 by 1 + \ifnum \count1<256 \loop \fi + }% + }% + % + % @ is our escape character in .aux files, and we need braces. + \catcode`\{=1 + \catcode`\}=2 + \catcode`\@=0 +} + +\def\readdatafile#1{% +\begingroup + \setupdatafile + \input\jobname.#1 +\endgroup} + + +\message{insertions,} +% including footnotes. + +\newcount \footnoteno + +% The trailing space in the following definition for supereject is +% vital for proper filling; pages come out unaligned when you do a +% pagealignmacro call if that space before the closing brace is +% removed. (Generally, numeric constants should always be followed by a +% space to prevent strange expansion errors.) +\def\supereject{\par\penalty -20000\footnoteno =0 } + +% @footnotestyle is meaningful for info output only. +\let\footnotestyle=\comment + +{\catcode `\@=11 +% +% Auto-number footnotes. Otherwise like plain. +\gdef\footnote{% + \let\indent=\ptexindent + \let\noindent=\ptexnoindent + \global\advance\footnoteno by \@ne + \edef\thisfootno{$^{\the\footnoteno}$}% + % + % In case the footnote comes at the end of a sentence, preserve the + % extra spacing after we do the footnote number. + \let\@sf\empty + \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\ptexslash\fi + % + % Remove inadvertent blank space before typesetting the footnote number. + \unskip + \thisfootno\@sf + \dofootnote +}% + +% Don't bother with the trickery in plain.tex to not require the +% footnote text as a parameter. Our footnotes don't need to be so general. +% +% Oh yes, they do; otherwise, @ifset (and anything else that uses +% \parseargline) fails inside footnotes because the tokens are fixed when +% the footnote is read. --karl, 16nov96. +% +\gdef\dofootnote{% + \insert\footins\bgroup + % We want to typeset this text as a normal paragraph, even if the + % footnote reference occurs in (for example) a display environment. + % So reset some parameters. + \hsize=\pagewidth + \interlinepenalty\interfootnotelinepenalty + \splittopskip\ht\strutbox % top baseline for broken footnotes + \splitmaxdepth\dp\strutbox + \floatingpenalty\@MM + \leftskip\z@skip + \rightskip\z@skip + \spaceskip\z@skip + \xspaceskip\z@skip + \parindent\defaultparindent + % + \smallfonts \rm + % + % Because we use hanging indentation in footnotes, a @noindent appears + % to exdent this text, so make it be a no-op. makeinfo does not use + % hanging indentation so @noindent can still be needed within footnote + % text after an @example or the like (not that this is good style). + \let\noindent = \relax + % + % Hang the footnote text off the number. Use \everypar in case the + % footnote extends for more than one paragraph. + \everypar = {\hang}% + \textindent{\thisfootno}% + % + % Don't crash into the line above the footnote text. Since this + % expands into a box, it must come within the paragraph, lest it + % provide a place where TeX can split the footnote. + \footstrut + \futurelet\next\fo@t +} +}%end \catcode `\@=11 + +% In case a @footnote appears in a vbox, save the footnote text and create +% the real \insert just after the vbox finished. Otherwise, the insertion +% would be lost. +% Similarily, if a @footnote appears inside an alignment, save the footnote +% text to a box and make the \insert when a row of the table is finished. +% And the same can be done for other insert classes. --kasal, 16nov03. + +% Replace the \insert primitive by a cheating macro. +% Deeper inside, just make sure that the saved insertions are not spilled +% out prematurely. +% +\def\startsavinginserts{% + \ifx \insert\ptexinsert + \let\insert\saveinsert + \else + \let\checkinserts\relax + \fi +} + +% This \insert replacement works for both \insert\footins{foo} and +% \insert\footins\bgroup foo\egroup, but it doesn't work for \insert27{foo}. +% +\def\saveinsert#1{% + \edef\next{\noexpand\savetobox \makeSAVEname#1}% + \afterassignment\next + % swallow the left brace + \let\temp = +} +\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}} +\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1} + +\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi} + +\def\placesaveins#1{% + \ptexinsert \csname\expandafter\gobblesave\string#1\endcsname + {\box#1}% +} + +% eat @SAVE -- beware, all of them have catcode \other: +{ + \def\dospecials{\do S\do A\do V\do E} \uncatcodespecials % ;-) + \gdef\gobblesave @SAVE{} +} + +% initialization: +\def\newsaveins #1{% + \edef\next{\noexpand\newsaveinsX \makeSAVEname#1}% + \next +} +\def\newsaveinsX #1{% + \csname newbox\endcsname #1% + \expandafter\def\expandafter\checkinserts\expandafter{\checkinserts + \checksaveins #1}% +} + +% initialize: +\let\checkinserts\empty +\newsaveins\footins +\newsaveins\margin + + +% @image. We use the macros from epsf.tex to support this. +% If epsf.tex is not installed and @image is used, we complain. +% +% Check for and read epsf.tex up front. If we read it only at @image +% time, we might be inside a group, and then its definitions would get +% undone and the next image would fail. +\openin 1 = epsf.tex +\ifeof 1 \else + % Do not bother showing banner with epsf.tex v2.7k (available in + % doc/epsf.tex and on ctan). + \def\epsfannounce{\toks0 = }% + \input epsf.tex +\fi +\closein 1 +% +% We will only complain once about lack of epsf.tex. +\newif\ifwarnednoepsf +\newhelp\noepsfhelp{epsf.tex must be installed for images to + work. It is also included in the Texinfo distribution, or you can get + it from ftp://tug.org/tex/epsf.tex.} +% +\def\image#1{% + \ifx\epsfbox\undefined + \ifwarnednoepsf \else + \errhelp = \noepsfhelp + \errmessage{epsf.tex not found, images will be ignored}% + \global\warnednoepsftrue + \fi + \else + \imagexxx #1,,,,,\finish + \fi +} +% +% Arguments to @image: +% #1 is (mandatory) image filename; we tack on .eps extension. +% #2 is (optional) width, #3 is (optional) height. +% #4 is (ignored optional) html alt text. +% #5 is (ignored optional) extension. +% #6 is just the usual extra ignored arg for parsing this stuff. +\newif\ifimagevmode +\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup + \catcode`\^^M = 5 % in case we're inside an example + \normalturnoffactive % allow _ et al. in names + % If the image is by itself, center it. + \ifvmode + \imagevmodetrue + \nobreak\bigskip + % Usually we'll have text after the image which will insert + % \parskip glue, so insert it here too to equalize the space + % above and below. + \nobreak\vskip\parskip + \nobreak + \line\bgroup + \fi + % + % Output the image. + \ifpdf + \dopdfimage{#1}{#2}{#3}% + \else + % \epsfbox itself resets \epsf?size at each figure. + \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi + \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi + \epsfbox{#1.eps}% + \fi + % + \ifimagevmode \egroup \bigbreak \fi % space after the image +\endgroup} + + +% @float FLOATTYPE,LABEL,LOC ... @end float for displayed figures, tables, +% etc. We don't actually implement floating yet, we always include the +% float "here". But it seemed the best name for the future. +% +\envparseargdef\float{\eatcommaspace\eatcommaspace\dofloat#1, , ,\finish} + +% There may be a space before second and/or third parameter; delete it. +\def\eatcommaspace#1, {#1,} + +% #1 is the optional FLOATTYPE, the text label for this float, typically +% "Figure", "Table", "Example", etc. Can't contain commas. If omitted, +% this float will not be numbered and cannot be referred to. +% +% #2 is the optional xref label. Also must be present for the float to +% be referable. +% +% #3 is the optional positioning argument; for now, it is ignored. It +% will somehow specify the positions allowed to float to (here, top, bottom). +% +% We keep a separate counter for each FLOATTYPE, which we reset at each +% chapter-level command. +\let\resetallfloatnos=\empty +% +\def\dofloat#1,#2,#3,#4\finish{% + \let\thiscaption=\empty + \let\thisshortcaption=\empty + % + % don't lose footnotes inside @float. + % + % BEWARE: when the floats start float, we have to issue warning whenever an + % insert appears inside a float which could possibly float. --kasal, 26may04 + % + \startsavinginserts + % + % We can't be used inside a paragraph. + \par + % + \vtop\bgroup + \def\floattype{#1}% + \def\floatlabel{#2}% + \def\floatloc{#3}% we do nothing with this yet. + % + \ifx\floattype\empty + \let\safefloattype=\empty + \else + {% + % the floattype might have accents or other special characters, + % but we need to use it in a control sequence name. + \indexnofonts + \turnoffactive + \xdef\safefloattype{\floattype}% + }% + \fi + % + % If label is given but no type, we handle that as the empty type. + \ifx\floatlabel\empty \else + % We want each FLOATTYPE to be numbered separately (Figure 1, + % Table 1, Figure 2, ...). (And if no label, no number.) + % + \expandafter\getfloatno\csname\safefloattype floatno\endcsname + \global\advance\floatno by 1 + % + {% + % This magic value for \lastsection is output by \setref as the + % XREFLABEL-title value. \xrefX uses it to distinguish float + % labels (which have a completely different output format) from + % node and anchor labels. And \xrdef uses it to construct the + % lists of floats. + % + \edef\lastsection{\floatmagic=\safefloattype}% + \setref{\floatlabel}{Yfloat}% + }% + \fi + % + % start with \parskip glue, I guess. + \vskip\parskip + % + % Don't suppress indentation if a float happens to start a section. + \restorefirstparagraphindent +} + +% we have these possibilities: +% @float Foo,lbl & @caption{Cap}: Foo 1.1: Cap +% @float Foo,lbl & no caption: Foo 1.1 +% @float Foo & @caption{Cap}: Foo: Cap +% @float Foo & no caption: Foo +% @float ,lbl & Caption{Cap}: 1.1: Cap +% @float ,lbl & no caption: 1.1 +% @float & @caption{Cap}: Cap +% @float & no caption: +% +\def\Efloat{% + \let\floatident = \empty + % + % In all cases, if we have a float type, it comes first. + \ifx\floattype\empty \else \def\floatident{\floattype}\fi + % + % If we have an xref label, the number comes next. + \ifx\floatlabel\empty \else + \ifx\floattype\empty \else % if also had float type, need tie first. + \appendtomacro\floatident{\tie}% + \fi + % the number. + \appendtomacro\floatident{\chaplevelprefix\the\floatno}% + \fi + % + % Start the printed caption with what we've constructed in + % \floatident, but keep it separate; we need \floatident again. + \let\captionline = \floatident + % + \ifx\thiscaption\empty \else + \ifx\floatident\empty \else + \appendtomacro\captionline{: }% had ident, so need a colon between + \fi + % + % caption text. + \appendtomacro\captionline{\scanexp\thiscaption}% + \fi + % + % If we have anything to print, print it, with space before. + % Eventually this needs to become an \insert. + \ifx\captionline\empty \else + \vskip.5\parskip + \captionline + % + % Space below caption. + \vskip\parskip + \fi + % + % If have an xref label, write the list of floats info. Do this + % after the caption, to avoid chance of it being a breakpoint. + \ifx\floatlabel\empty \else + % Write the text that goes in the lof to the aux file as + % \floatlabel-lof. Besides \floatident, we include the short + % caption if specified, else the full caption if specified, else nothing. + {% + \atdummies + % + % since we read the caption text in the macro world, where ^^M + % is turned into a normal character, we have to scan it back, so + % we don't write the literal three characters "^^M" into the aux file. + \scanexp{% + \xdef\noexpand\gtemp{% + \ifx\thisshortcaption\empty + \thiscaption + \else + \thisshortcaption + \fi + }% + }% + \immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident + \ifx\gtemp\empty \else : \gtemp \fi}}% + }% + \fi + \egroup % end of \vtop + % + % place the captured inserts + % + % BEWARE: when the floats start floating, we have to issue warning + % whenever an insert appears inside a float which could possibly + % float. --kasal, 26may04 + % + \checkinserts +} + +% Append the tokens #2 to the definition of macro #1, not expanding either. +% +\def\appendtomacro#1#2{% + \expandafter\def\expandafter#1\expandafter{#1#2}% +} + +% @caption, @shortcaption +% +\def\caption{\docaption\thiscaption} +\def\shortcaption{\docaption\thisshortcaption} +\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption} +\def\defcaption#1#2{\egroup \def#1{#2}} + +% The parameter is the control sequence identifying the counter we are +% going to use. Create it if it doesn't exist and assign it to \floatno. +\def\getfloatno#1{% + \ifx#1\relax + % Haven't seen this figure type before. + \csname newcount\endcsname #1% + % + % Remember to reset this floatno at the next chap. + \expandafter\gdef\expandafter\resetallfloatnos + \expandafter{\resetallfloatnos #1=0 }% + \fi + \let\floatno#1% +} + +% \setref calls this to get the XREFLABEL-snt value. We want an @xref +% to the FLOATLABEL to expand to "Figure 3.1". We call \setref when we +% first read the @float command. +% +\def\Yfloat{\floattype@tie \chaplevelprefix\the\floatno}% + +% Magic string used for the XREFLABEL-title value, so \xrefX can +% distinguish floats from other xref types. +\def\floatmagic{!!float!!} + +% #1 is the control sequence we are passed; we expand into a conditional +% which is true if #1 represents a float ref. That is, the magic +% \lastsection value which we \setref above. +% +\def\iffloat#1{\expandafter\doiffloat#1==\finish} +% +% #1 is (maybe) the \floatmagic string. If so, #2 will be the +% (safe) float type for this float. We set \iffloattype to #2. +% +\def\doiffloat#1=#2=#3\finish{% + \def\temp{#1}% + \def\iffloattype{#2}% + \ifx\temp\floatmagic +} + +% @listoffloats FLOATTYPE - print a list of floats like a table of contents. +% +\parseargdef\listoffloats{% + \def\floattype{#1}% floattype + {% + % the floattype might have accents or other special characters, + % but we need to use it in a control sequence name. + \indexnofonts + \turnoffactive + \xdef\safefloattype{\floattype}% + }% + % + % \xrdef saves the floats as a \do-list in \floatlistSAFEFLOATTYPE. + \expandafter\ifx\csname floatlist\safefloattype\endcsname \relax + \ifhavexrefs + % if the user said @listoffloats foo but never @float foo. + \message{\linenumber No `\safefloattype' floats to list.}% + \fi + \else + \begingroup + \leftskip=\tocindent % indent these entries like a toc + \let\do=\listoffloatsdo + \csname floatlist\safefloattype\endcsname + \endgroup + \fi +} + +% This is called on each entry in a list of floats. We're passed the +% xref label, in the form LABEL-title, which is how we save it in the +% aux file. We strip off the -title and look up \XRLABEL-lof, which +% has the text we're supposed to typeset here. +% +% Figures without xref labels will not be included in the list (since +% they won't appear in the aux file). +% +\def\listoffloatsdo#1{\listoffloatsdoentry#1\finish} +\def\listoffloatsdoentry#1-title\finish{{% + % Can't fully expand XR#1-lof because it can contain anything. Just + % pass the control sequence. On the other hand, XR#1-pg is just the + % page number, and we want to fully expand that so we can get a link + % in pdf output. + \toksA = \expandafter{\csname XR#1-lof\endcsname}% + % + % use the same \entry macro we use to generate the TOC and index. + \edef\writeentry{\noexpand\entry{\the\toksA}{\csname XR#1-pg\endcsname}}% + \writeentry +}} + + +\message{localization,} + +% @documentlanguage is usually given very early, just after +% @setfilename. If done too late, it may not override everything +% properly. Single argument is the language (de) or locale (de_DE) +% abbreviation. It would be nice if we could set up a hyphenation file. +% +{ + \catcode`\_ = \active + \globaldefs=1 +\parseargdef\documentlanguage{\begingroup + \let_=\normalunderscore % normal _ character for filenames + \tex % read txi-??.tex file in plain TeX. + % Read the file by the name they passed if it exists. + \openin 1 txi-#1.tex + \ifeof 1 + \documentlanguagetrywithoutunderscore{#1_\finish}% + \else + \input txi-#1.tex + \fi + \closein 1 + \endgroup +\endgroup} +} +% +% If they passed de_DE, and txi-de_DE.tex doesn't exist, +% try txi-de.tex. +% +\def\documentlanguagetrywithoutunderscore#1_#2\finish{% + \openin 1 txi-#1.tex + \ifeof 1 + \errhelp = \nolanghelp + \errmessage{Cannot read language file txi-#1.tex}% + \else + \input txi-#1.tex + \fi + \closein 1 +} +% +\newhelp\nolanghelp{The given language definition file cannot be found or +is empty. Maybe you need to install it? In the current directory +should work if nowhere else does.} + +% Set the catcode of characters 128 through 255 to the specified number. +% +\def\setnonasciicharscatcode#1{% + \count255=128 + \loop\ifnum\count255<256 + \global\catcode\count255=#1\relax + \advance\count255 by 1 + \repeat +} + +\def\setnonasciicharscatcodenonglobal#1{% + \count255=128 + \loop\ifnum\count255<256 + \catcode\count255=#1\relax + \advance\count255 by 1 + \repeat +} + +% @documentencoding sets the definition of non-ASCII characters +% according to the specified encoding. +% +\parseargdef\documentencoding{% + % Encoding being declared for the document. + \def\declaredencoding{\csname #1.enc\endcsname}% + % + % Supported encodings: names converted to tokens in order to be able + % to compare them with \ifx. + \def\ascii{\csname US-ASCII.enc\endcsname}% + \def\latnine{\csname ISO-8859-15.enc\endcsname}% + \def\latone{\csname ISO-8859-1.enc\endcsname}% + \def\lattwo{\csname ISO-8859-2.enc\endcsname}% + \def\utfeight{\csname UTF-8.enc\endcsname}% + % + \ifx \declaredencoding \ascii + \asciichardefs + % + \else \ifx \declaredencoding \lattwo + \setnonasciicharscatcode\active + \lattwochardefs + % + \else \ifx \declaredencoding \latone + \setnonasciicharscatcode\active + \latonechardefs + % + \else \ifx \declaredencoding \latnine + \setnonasciicharscatcode\active + \latninechardefs + % + \else \ifx \declaredencoding \utfeight + \setnonasciicharscatcode\active + \utfeightchardefs + % + \else + \message{Unknown document encoding #1, ignoring.}% + % + \fi % utfeight + \fi % latnine + \fi % latone + \fi % lattwo + \fi % ascii +} + +% A message to be logged when using a character that isn't available +% the default font encoding (OT1). +% +\def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}} + +% Take account of \c (plain) vs. \, (Texinfo) difference. +\def\cedilla#1{\ifx\c\ptexc\c{#1}\else\,{#1}\fi} + +% First, make active non-ASCII characters in order for them to be +% correctly categorized when TeX reads the replacement text of +% macros containing the character definitions. +\setnonasciicharscatcode\active +% +% Latin1 (ISO-8859-1) character definitions. +\def\latonechardefs{% + \gdef^^a0{~} + \gdef^^a1{\exclamdown} + \gdef^^a2{\missingcharmsg{CENT SIGN}} + \gdef^^a3{{\pounds}} + \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} + \gdef^^a5{\missingcharmsg{YEN SIGN}} + \gdef^^a6{\missingcharmsg{BROKEN BAR}} + \gdef^^a7{\S} + \gdef^^a8{\"{}} + \gdef^^a9{\copyright} + \gdef^^aa{\ordf} + \gdef^^ab{\missingcharmsg{LEFT-POINTING DOUBLE ANGLE QUOTATION MARK}} + \gdef^^ac{$\lnot$} + \gdef^^ad{\-} + \gdef^^ae{\registeredsymbol} + \gdef^^af{\={}} + % + \gdef^^b0{\textdegree} + \gdef^^b1{$\pm$} + \gdef^^b2{$^2$} + \gdef^^b3{$^3$} + \gdef^^b4{\'{}} + \gdef^^b5{$\mu$} + \gdef^^b6{\P} + % + \gdef^^b7{$^.$} + \gdef^^b8{\cedilla\ } + \gdef^^b9{$^1$} + \gdef^^ba{\ordm} + % + \gdef^^bb{\missingcharmsg{RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK}} + \gdef^^bc{$1\over4$} + \gdef^^bd{$1\over2$} + \gdef^^be{$3\over4$} + \gdef^^bf{\questiondown} + % + \gdef^^c0{\`A} + \gdef^^c1{\'A} + \gdef^^c2{\^A} + \gdef^^c3{\~A} + \gdef^^c4{\"A} + \gdef^^c5{\ringaccent A} + \gdef^^c6{\AE} + \gdef^^c7{\cedilla C} + \gdef^^c8{\`E} + \gdef^^c9{\'E} + \gdef^^ca{\^E} + \gdef^^cb{\"E} + \gdef^^cc{\`I} + \gdef^^cd{\'I} + \gdef^^ce{\^I} + \gdef^^cf{\"I} + % + \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER ETH}} + \gdef^^d1{\~N} + \gdef^^d2{\`O} + \gdef^^d3{\'O} + \gdef^^d4{\^O} + \gdef^^d5{\~O} + \gdef^^d6{\"O} + \gdef^^d7{$\times$} + \gdef^^d8{\O} + \gdef^^d9{\`U} + \gdef^^da{\'U} + \gdef^^db{\^U} + \gdef^^dc{\"U} + \gdef^^dd{\'Y} + \gdef^^de{\missingcharmsg{LATIN CAPITAL LETTER THORN}} + \gdef^^df{\ss} + % + \gdef^^e0{\`a} + \gdef^^e1{\'a} + \gdef^^e2{\^a} + \gdef^^e3{\~a} + \gdef^^e4{\"a} + \gdef^^e5{\ringaccent a} + \gdef^^e6{\ae} + \gdef^^e7{\cedilla c} + \gdef^^e8{\`e} + \gdef^^e9{\'e} + \gdef^^ea{\^e} + \gdef^^eb{\"e} + \gdef^^ec{\`{\dotless i}} + \gdef^^ed{\'{\dotless i}} + \gdef^^ee{\^{\dotless i}} + \gdef^^ef{\"{\dotless i}} + % + \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER ETH}} + \gdef^^f1{\~n} + \gdef^^f2{\`o} + \gdef^^f3{\'o} + \gdef^^f4{\^o} + \gdef^^f5{\~o} + \gdef^^f6{\"o} + \gdef^^f7{$\div$} + \gdef^^f8{\o} + \gdef^^f9{\`u} + \gdef^^fa{\'u} + \gdef^^fb{\^u} + \gdef^^fc{\"u} + \gdef^^fd{\'y} + \gdef^^fe{\missingcharmsg{LATIN SMALL LETTER THORN}} + \gdef^^ff{\"y} +} + +% Latin9 (ISO-8859-15) encoding character definitions. +\def\latninechardefs{% + % Encoding is almost identical to Latin1. + \latonechardefs + % + \gdef^^a4{\euro} + \gdef^^a6{\v S} + \gdef^^a8{\v s} + \gdef^^b4{\v Z} + \gdef^^b8{\v z} + \gdef^^bc{\OE} + \gdef^^bd{\oe} + \gdef^^be{\"Y} +} + +% Latin2 (ISO-8859-2) character definitions. +\def\lattwochardefs{% + \gdef^^a0{~} + \gdef^^a1{\missingcharmsg{LATIN CAPITAL LETTER A WITH OGONEK}} + \gdef^^a2{\u{}} + \gdef^^a3{\L} + \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} + \gdef^^a5{\v L} + \gdef^^a6{\'S} + \gdef^^a7{\S} + \gdef^^a8{\"{}} + \gdef^^a9{\v S} + \gdef^^aa{\cedilla S} + \gdef^^ab{\v T} + \gdef^^ac{\'Z} + \gdef^^ad{\-} + \gdef^^ae{\v Z} + \gdef^^af{\dotaccent Z} + % + \gdef^^b0{\textdegree} + \gdef^^b1{\missingcharmsg{LATIN SMALL LETTER A WITH OGONEK}} + \gdef^^b2{\missingcharmsg{OGONEK}} + \gdef^^b3{\l} + \gdef^^b4{\'{}} + \gdef^^b5{\v l} + \gdef^^b6{\'s} + \gdef^^b7{\v{}} + \gdef^^b8{\cedilla\ } + \gdef^^b9{\v s} + \gdef^^ba{\cedilla s} + \gdef^^bb{\v t} + \gdef^^bc{\'z} + \gdef^^bd{\H{}} + \gdef^^be{\v z} + \gdef^^bf{\dotaccent z} + % + \gdef^^c0{\'R} + \gdef^^c1{\'A} + \gdef^^c2{\^A} + \gdef^^c3{\u A} + \gdef^^c4{\"A} + \gdef^^c5{\'L} + \gdef^^c6{\'C} + \gdef^^c7{\cedilla C} + \gdef^^c8{\v C} + \gdef^^c9{\'E} + \gdef^^ca{\missingcharmsg{LATIN CAPITAL LETTER E WITH OGONEK}} + \gdef^^cb{\"E} + \gdef^^cc{\v E} + \gdef^^cd{\'I} + \gdef^^ce{\^I} + \gdef^^cf{\v D} + % + \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER D WITH STROKE}} + \gdef^^d1{\'N} + \gdef^^d2{\v N} + \gdef^^d3{\'O} + \gdef^^d4{\^O} + \gdef^^d5{\H O} + \gdef^^d6{\"O} + \gdef^^d7{$\times$} + \gdef^^d8{\v R} + \gdef^^d9{\ringaccent U} + \gdef^^da{\'U} + \gdef^^db{\H U} + \gdef^^dc{\"U} + \gdef^^dd{\'Y} + \gdef^^de{\cedilla T} + \gdef^^df{\ss} + % + \gdef^^e0{\'r} + \gdef^^e1{\'a} + \gdef^^e2{\^a} + \gdef^^e3{\u a} + \gdef^^e4{\"a} + \gdef^^e5{\'l} + \gdef^^e6{\'c} + \gdef^^e7{\cedilla c} + \gdef^^e8{\v c} + \gdef^^e9{\'e} + \gdef^^ea{\missingcharmsg{LATIN SMALL LETTER E WITH OGONEK}} + \gdef^^eb{\"e} + \gdef^^ec{\v e} + \gdef^^ed{\'\i} + \gdef^^ee{\^\i} + \gdef^^ef{\v d} + % + \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER D WITH STROKE}} + \gdef^^f1{\'n} + \gdef^^f2{\v n} + \gdef^^f3{\'o} + \gdef^^f4{\^o} + \gdef^^f5{\H o} + \gdef^^f6{\"o} + \gdef^^f7{$\div$} + \gdef^^f8{\v r} + \gdef^^f9{\ringaccent u} + \gdef^^fa{\'u} + \gdef^^fb{\H u} + \gdef^^fc{\"u} + \gdef^^fd{\'y} + \gdef^^fe{\cedilla t} + \gdef^^ff{\dotaccent{}} +} + +% UTF-8 character definitions. +% +% This code to support UTF-8 is based on LaTeX's utf8.def, with some +% changes for Texinfo conventions. It is included here under the GPL by +% permission from Frank Mittelbach and the LaTeX team. +% +\newcount\countUTFx +\newcount\countUTFy +\newcount\countUTFz + +\gdef\UTFviiiTwoOctets#1#2{\expandafter + \UTFviiiDefined\csname u8:#1\string #2\endcsname} +% +\gdef\UTFviiiThreeOctets#1#2#3{\expandafter + \UTFviiiDefined\csname u8:#1\string #2\string #3\endcsname} +% +\gdef\UTFviiiFourOctets#1#2#3#4{\expandafter + \UTFviiiDefined\csname u8:#1\string #2\string #3\string #4\endcsname} + +\gdef\UTFviiiDefined#1{% + \ifx #1\relax + \message{\linenumber Unicode char \string #1 not defined for Texinfo}% + \else + \expandafter #1% + \fi +} + +\begingroup + \catcode`\~13 + \catcode`\"12 + + \def\UTFviiiLoop{% + \global\catcode\countUTFx\active + \uccode`\~\countUTFx + \uppercase\expandafter{\UTFviiiTmp}% + \advance\countUTFx by 1 + \ifnum\countUTFx < \countUTFy + \expandafter\UTFviiiLoop + \fi} + + \countUTFx = "C2 + \countUTFy = "E0 + \def\UTFviiiTmp{% + \xdef~{\noexpand\UTFviiiTwoOctets\string~}} + \UTFviiiLoop + + \countUTFx = "E0 + \countUTFy = "F0 + \def\UTFviiiTmp{% + \xdef~{\noexpand\UTFviiiThreeOctets\string~}} + \UTFviiiLoop + + \countUTFx = "F0 + \countUTFy = "F4 + \def\UTFviiiTmp{% + \xdef~{\noexpand\UTFviiiFourOctets\string~}} + \UTFviiiLoop +\endgroup + +\begingroup + \catcode`\"=12 + \catcode`\<=12 + \catcode`\.=12 + \catcode`\,=12 + \catcode`\;=12 + \catcode`\!=12 + \catcode`\~=13 + + \gdef\DeclareUnicodeCharacter#1#2{% + \countUTFz = "#1\relax + \wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}% + \begingroup + \parseXMLCharref + \def\UTFviiiTwoOctets##1##2{% + \csname u8:##1\string ##2\endcsname}% + \def\UTFviiiThreeOctets##1##2##3{% + \csname u8:##1\string ##2\string ##3\endcsname}% + \def\UTFviiiFourOctets##1##2##3##4{% + \csname u8:##1\string ##2\string ##3\string ##4\endcsname}% + \expandafter\expandafter\expandafter\expandafter + \expandafter\expandafter\expandafter + \gdef\UTFviiiTmp{#2}% + \endgroup} + + \gdef\parseXMLCharref{% + \ifnum\countUTFz < "A0\relax + \errhelp = \EMsimple + \errmessage{Cannot define Unicode char value < 00A0}% + \else\ifnum\countUTFz < "800\relax + \parseUTFviiiA,% + \parseUTFviiiB C\UTFviiiTwoOctets.,% + \else\ifnum\countUTFz < "10000\relax + \parseUTFviiiA;% + \parseUTFviiiA,% + \parseUTFviiiB E\UTFviiiThreeOctets.{,;}% + \else + \parseUTFviiiA;% + \parseUTFviiiA,% + \parseUTFviiiA!% + \parseUTFviiiB F\UTFviiiFourOctets.{!,;}% + \fi\fi\fi + } + + \gdef\parseUTFviiiA#1{% + \countUTFx = \countUTFz + \divide\countUTFz by 64 + \countUTFy = \countUTFz + \multiply\countUTFz by 64 + \advance\countUTFx by -\countUTFz + \advance\countUTFx by 128 + \uccode `#1\countUTFx + \countUTFz = \countUTFy} + + \gdef\parseUTFviiiB#1#2#3#4{% + \advance\countUTFz by "#10\relax + \uccode `#3\countUTFz + \uppercase{\gdef\UTFviiiTmp{#2#3#4}}} +\endgroup + +\def\utfeightchardefs{% + \DeclareUnicodeCharacter{00A0}{\tie} + \DeclareUnicodeCharacter{00A1}{\exclamdown} + \DeclareUnicodeCharacter{00A3}{\pounds} + \DeclareUnicodeCharacter{00A8}{\"{ }} + \DeclareUnicodeCharacter{00A9}{\copyright} + \DeclareUnicodeCharacter{00AA}{\ordf} + \DeclareUnicodeCharacter{00AB}{\guillemetleft} + \DeclareUnicodeCharacter{00AD}{\-} + \DeclareUnicodeCharacter{00AE}{\registeredsymbol} + \DeclareUnicodeCharacter{00AF}{\={ }} + + \DeclareUnicodeCharacter{00B0}{\ringaccent{ }} + \DeclareUnicodeCharacter{00B4}{\'{ }} + \DeclareUnicodeCharacter{00B8}{\cedilla{ }} + \DeclareUnicodeCharacter{00BA}{\ordm} + \DeclareUnicodeCharacter{00BB}{\guillemetright} + \DeclareUnicodeCharacter{00BF}{\questiondown} + + \DeclareUnicodeCharacter{00C0}{\`A} + \DeclareUnicodeCharacter{00C1}{\'A} + \DeclareUnicodeCharacter{00C2}{\^A} + \DeclareUnicodeCharacter{00C3}{\~A} + \DeclareUnicodeCharacter{00C4}{\"A} + \DeclareUnicodeCharacter{00C5}{\AA} + \DeclareUnicodeCharacter{00C6}{\AE} + \DeclareUnicodeCharacter{00C7}{\cedilla{C}} + \DeclareUnicodeCharacter{00C8}{\`E} + \DeclareUnicodeCharacter{00C9}{\'E} + \DeclareUnicodeCharacter{00CA}{\^E} + \DeclareUnicodeCharacter{00CB}{\"E} + \DeclareUnicodeCharacter{00CC}{\`I} + \DeclareUnicodeCharacter{00CD}{\'I} + \DeclareUnicodeCharacter{00CE}{\^I} + \DeclareUnicodeCharacter{00CF}{\"I} + + \DeclareUnicodeCharacter{00D1}{\~N} + \DeclareUnicodeCharacter{00D2}{\`O} + \DeclareUnicodeCharacter{00D3}{\'O} + \DeclareUnicodeCharacter{00D4}{\^O} + \DeclareUnicodeCharacter{00D5}{\~O} + \DeclareUnicodeCharacter{00D6}{\"O} + \DeclareUnicodeCharacter{00D8}{\O} + \DeclareUnicodeCharacter{00D9}{\`U} + \DeclareUnicodeCharacter{00DA}{\'U} + \DeclareUnicodeCharacter{00DB}{\^U} + \DeclareUnicodeCharacter{00DC}{\"U} + \DeclareUnicodeCharacter{00DD}{\'Y} + \DeclareUnicodeCharacter{00DF}{\ss} + + \DeclareUnicodeCharacter{00E0}{\`a} + \DeclareUnicodeCharacter{00E1}{\'a} + \DeclareUnicodeCharacter{00E2}{\^a} + \DeclareUnicodeCharacter{00E3}{\~a} + \DeclareUnicodeCharacter{00E4}{\"a} + \DeclareUnicodeCharacter{00E5}{\aa} + \DeclareUnicodeCharacter{00E6}{\ae} + \DeclareUnicodeCharacter{00E7}{\cedilla{c}} + \DeclareUnicodeCharacter{00E8}{\`e} + \DeclareUnicodeCharacter{00E9}{\'e} + \DeclareUnicodeCharacter{00EA}{\^e} + \DeclareUnicodeCharacter{00EB}{\"e} + \DeclareUnicodeCharacter{00EC}{\`{\dotless{i}}} + \DeclareUnicodeCharacter{00ED}{\'{\dotless{i}}} + \DeclareUnicodeCharacter{00EE}{\^{\dotless{i}}} + \DeclareUnicodeCharacter{00EF}{\"{\dotless{i}}} + + \DeclareUnicodeCharacter{00F1}{\~n} + \DeclareUnicodeCharacter{00F2}{\`o} + \DeclareUnicodeCharacter{00F3}{\'o} + \DeclareUnicodeCharacter{00F4}{\^o} + \DeclareUnicodeCharacter{00F5}{\~o} + \DeclareUnicodeCharacter{00F6}{\"o} + \DeclareUnicodeCharacter{00F8}{\o} + \DeclareUnicodeCharacter{00F9}{\`u} + \DeclareUnicodeCharacter{00FA}{\'u} + \DeclareUnicodeCharacter{00FB}{\^u} + \DeclareUnicodeCharacter{00FC}{\"u} + \DeclareUnicodeCharacter{00FD}{\'y} + \DeclareUnicodeCharacter{00FF}{\"y} + + \DeclareUnicodeCharacter{0100}{\=A} + \DeclareUnicodeCharacter{0101}{\=a} + \DeclareUnicodeCharacter{0102}{\u{A}} + \DeclareUnicodeCharacter{0103}{\u{a}} + \DeclareUnicodeCharacter{0106}{\'C} + \DeclareUnicodeCharacter{0107}{\'c} + \DeclareUnicodeCharacter{0108}{\^C} + \DeclareUnicodeCharacter{0109}{\^c} + \DeclareUnicodeCharacter{010A}{\dotaccent{C}} + \DeclareUnicodeCharacter{010B}{\dotaccent{c}} + \DeclareUnicodeCharacter{010C}{\v{C}} + \DeclareUnicodeCharacter{010D}{\v{c}} + \DeclareUnicodeCharacter{010E}{\v{D}} + + \DeclareUnicodeCharacter{0112}{\=E} + \DeclareUnicodeCharacter{0113}{\=e} + \DeclareUnicodeCharacter{0114}{\u{E}} + \DeclareUnicodeCharacter{0115}{\u{e}} + \DeclareUnicodeCharacter{0116}{\dotaccent{E}} + \DeclareUnicodeCharacter{0117}{\dotaccent{e}} + \DeclareUnicodeCharacter{011A}{\v{E}} + \DeclareUnicodeCharacter{011B}{\v{e}} + \DeclareUnicodeCharacter{011C}{\^G} + \DeclareUnicodeCharacter{011D}{\^g} + \DeclareUnicodeCharacter{011E}{\u{G}} + \DeclareUnicodeCharacter{011F}{\u{g}} + + \DeclareUnicodeCharacter{0120}{\dotaccent{G}} + \DeclareUnicodeCharacter{0121}{\dotaccent{g}} + \DeclareUnicodeCharacter{0124}{\^H} + \DeclareUnicodeCharacter{0125}{\^h} + \DeclareUnicodeCharacter{0128}{\~I} + \DeclareUnicodeCharacter{0129}{\~{\dotless{i}}} + \DeclareUnicodeCharacter{012A}{\=I} + \DeclareUnicodeCharacter{012B}{\={\dotless{i}}} + \DeclareUnicodeCharacter{012C}{\u{I}} + \DeclareUnicodeCharacter{012D}{\u{\dotless{i}}} + + \DeclareUnicodeCharacter{0130}{\dotaccent{I}} + \DeclareUnicodeCharacter{0131}{\dotless{i}} + \DeclareUnicodeCharacter{0132}{IJ} + \DeclareUnicodeCharacter{0133}{ij} + \DeclareUnicodeCharacter{0134}{\^J} + \DeclareUnicodeCharacter{0135}{\^{\dotless{j}}} + \DeclareUnicodeCharacter{0139}{\'L} + \DeclareUnicodeCharacter{013A}{\'l} + + \DeclareUnicodeCharacter{0141}{\L} + \DeclareUnicodeCharacter{0142}{\l} + \DeclareUnicodeCharacter{0143}{\'N} + \DeclareUnicodeCharacter{0144}{\'n} + \DeclareUnicodeCharacter{0147}{\v{N}} + \DeclareUnicodeCharacter{0148}{\v{n}} + \DeclareUnicodeCharacter{014C}{\=O} + \DeclareUnicodeCharacter{014D}{\=o} + \DeclareUnicodeCharacter{014E}{\u{O}} + \DeclareUnicodeCharacter{014F}{\u{o}} + + \DeclareUnicodeCharacter{0150}{\H{O}} + \DeclareUnicodeCharacter{0151}{\H{o}} + \DeclareUnicodeCharacter{0152}{\OE} + \DeclareUnicodeCharacter{0153}{\oe} + \DeclareUnicodeCharacter{0154}{\'R} + \DeclareUnicodeCharacter{0155}{\'r} + \DeclareUnicodeCharacter{0158}{\v{R}} + \DeclareUnicodeCharacter{0159}{\v{r}} + \DeclareUnicodeCharacter{015A}{\'S} + \DeclareUnicodeCharacter{015B}{\'s} + \DeclareUnicodeCharacter{015C}{\^S} + \DeclareUnicodeCharacter{015D}{\^s} + \DeclareUnicodeCharacter{015E}{\cedilla{S}} + \DeclareUnicodeCharacter{015F}{\cedilla{s}} + + \DeclareUnicodeCharacter{0160}{\v{S}} + \DeclareUnicodeCharacter{0161}{\v{s}} + \DeclareUnicodeCharacter{0162}{\cedilla{t}} + \DeclareUnicodeCharacter{0163}{\cedilla{T}} + \DeclareUnicodeCharacter{0164}{\v{T}} + + \DeclareUnicodeCharacter{0168}{\~U} + \DeclareUnicodeCharacter{0169}{\~u} + \DeclareUnicodeCharacter{016A}{\=U} + \DeclareUnicodeCharacter{016B}{\=u} + \DeclareUnicodeCharacter{016C}{\u{U}} + \DeclareUnicodeCharacter{016D}{\u{u}} + \DeclareUnicodeCharacter{016E}{\ringaccent{U}} + \DeclareUnicodeCharacter{016F}{\ringaccent{u}} + + \DeclareUnicodeCharacter{0170}{\H{U}} + \DeclareUnicodeCharacter{0171}{\H{u}} + \DeclareUnicodeCharacter{0174}{\^W} + \DeclareUnicodeCharacter{0175}{\^w} + \DeclareUnicodeCharacter{0176}{\^Y} + \DeclareUnicodeCharacter{0177}{\^y} + \DeclareUnicodeCharacter{0178}{\"Y} + \DeclareUnicodeCharacter{0179}{\'Z} + \DeclareUnicodeCharacter{017A}{\'z} + \DeclareUnicodeCharacter{017B}{\dotaccent{Z}} + \DeclareUnicodeCharacter{017C}{\dotaccent{z}} + \DeclareUnicodeCharacter{017D}{\v{Z}} + \DeclareUnicodeCharacter{017E}{\v{z}} + + \DeclareUnicodeCharacter{01C4}{D\v{Z}} + \DeclareUnicodeCharacter{01C5}{D\v{z}} + \DeclareUnicodeCharacter{01C6}{d\v{z}} + \DeclareUnicodeCharacter{01C7}{LJ} + \DeclareUnicodeCharacter{01C8}{Lj} + \DeclareUnicodeCharacter{01C9}{lj} + \DeclareUnicodeCharacter{01CA}{NJ} + \DeclareUnicodeCharacter{01CB}{Nj} + \DeclareUnicodeCharacter{01CC}{nj} + \DeclareUnicodeCharacter{01CD}{\v{A}} + \DeclareUnicodeCharacter{01CE}{\v{a}} + \DeclareUnicodeCharacter{01CF}{\v{I}} + + \DeclareUnicodeCharacter{01D0}{\v{\dotless{i}}} + \DeclareUnicodeCharacter{01D1}{\v{O}} + \DeclareUnicodeCharacter{01D2}{\v{o}} + \DeclareUnicodeCharacter{01D3}{\v{U}} + \DeclareUnicodeCharacter{01D4}{\v{u}} + + \DeclareUnicodeCharacter{01E2}{\={\AE}} + \DeclareUnicodeCharacter{01E3}{\={\ae}} + \DeclareUnicodeCharacter{01E6}{\v{G}} + \DeclareUnicodeCharacter{01E7}{\v{g}} + \DeclareUnicodeCharacter{01E8}{\v{K}} + \DeclareUnicodeCharacter{01E9}{\v{k}} + + \DeclareUnicodeCharacter{01F0}{\v{\dotless{j}}} + \DeclareUnicodeCharacter{01F1}{DZ} + \DeclareUnicodeCharacter{01F2}{Dz} + \DeclareUnicodeCharacter{01F3}{dz} + \DeclareUnicodeCharacter{01F4}{\'G} + \DeclareUnicodeCharacter{01F5}{\'g} + \DeclareUnicodeCharacter{01F8}{\`N} + \DeclareUnicodeCharacter{01F9}{\`n} + \DeclareUnicodeCharacter{01FC}{\'{\AE}} + \DeclareUnicodeCharacter{01FD}{\'{\ae}} + \DeclareUnicodeCharacter{01FE}{\'{\O}} + \DeclareUnicodeCharacter{01FF}{\'{\o}} + + \DeclareUnicodeCharacter{021E}{\v{H}} + \DeclareUnicodeCharacter{021F}{\v{h}} + + \DeclareUnicodeCharacter{0226}{\dotaccent{A}} + \DeclareUnicodeCharacter{0227}{\dotaccent{a}} + \DeclareUnicodeCharacter{0228}{\cedilla{E}} + \DeclareUnicodeCharacter{0229}{\cedilla{e}} + \DeclareUnicodeCharacter{022E}{\dotaccent{O}} + \DeclareUnicodeCharacter{022F}{\dotaccent{o}} + + \DeclareUnicodeCharacter{0232}{\=Y} + \DeclareUnicodeCharacter{0233}{\=y} + \DeclareUnicodeCharacter{0237}{\dotless{j}} + + \DeclareUnicodeCharacter{1E02}{\dotaccent{B}} + \DeclareUnicodeCharacter{1E03}{\dotaccent{b}} + \DeclareUnicodeCharacter{1E04}{\udotaccent{B}} + \DeclareUnicodeCharacter{1E05}{\udotaccent{b}} + \DeclareUnicodeCharacter{1E06}{\ubaraccent{B}} + \DeclareUnicodeCharacter{1E07}{\ubaraccent{b}} + \DeclareUnicodeCharacter{1E0A}{\dotaccent{D}} + \DeclareUnicodeCharacter{1E0B}{\dotaccent{d}} + \DeclareUnicodeCharacter{1E0C}{\udotaccent{D}} + \DeclareUnicodeCharacter{1E0D}{\udotaccent{d}} + \DeclareUnicodeCharacter{1E0E}{\ubaraccent{D}} + \DeclareUnicodeCharacter{1E0F}{\ubaraccent{d}} + + \DeclareUnicodeCharacter{1E1E}{\dotaccent{F}} + \DeclareUnicodeCharacter{1E1F}{\dotaccent{f}} + + \DeclareUnicodeCharacter{1E20}{\=G} + \DeclareUnicodeCharacter{1E21}{\=g} + \DeclareUnicodeCharacter{1E22}{\dotaccent{H}} + \DeclareUnicodeCharacter{1E23}{\dotaccent{h}} + \DeclareUnicodeCharacter{1E24}{\udotaccent{H}} + \DeclareUnicodeCharacter{1E25}{\udotaccent{h}} + \DeclareUnicodeCharacter{1E26}{\"H} + \DeclareUnicodeCharacter{1E27}{\"h} + + \DeclareUnicodeCharacter{1E30}{\'K} + \DeclareUnicodeCharacter{1E31}{\'k} + \DeclareUnicodeCharacter{1E32}{\udotaccent{K}} + \DeclareUnicodeCharacter{1E33}{\udotaccent{k}} + \DeclareUnicodeCharacter{1E34}{\ubaraccent{K}} + \DeclareUnicodeCharacter{1E35}{\ubaraccent{k}} + \DeclareUnicodeCharacter{1E36}{\udotaccent{L}} + \DeclareUnicodeCharacter{1E37}{\udotaccent{l}} + \DeclareUnicodeCharacter{1E3A}{\ubaraccent{L}} + \DeclareUnicodeCharacter{1E3B}{\ubaraccent{l}} + \DeclareUnicodeCharacter{1E3E}{\'M} + \DeclareUnicodeCharacter{1E3F}{\'m} + + \DeclareUnicodeCharacter{1E40}{\dotaccent{M}} + \DeclareUnicodeCharacter{1E41}{\dotaccent{m}} + \DeclareUnicodeCharacter{1E42}{\udotaccent{M}} + \DeclareUnicodeCharacter{1E43}{\udotaccent{m}} + \DeclareUnicodeCharacter{1E44}{\dotaccent{N}} + \DeclareUnicodeCharacter{1E45}{\dotaccent{n}} + \DeclareUnicodeCharacter{1E46}{\udotaccent{N}} + \DeclareUnicodeCharacter{1E47}{\udotaccent{n}} + \DeclareUnicodeCharacter{1E48}{\ubaraccent{N}} + \DeclareUnicodeCharacter{1E49}{\ubaraccent{n}} + + \DeclareUnicodeCharacter{1E54}{\'P} + \DeclareUnicodeCharacter{1E55}{\'p} + \DeclareUnicodeCharacter{1E56}{\dotaccent{P}} + \DeclareUnicodeCharacter{1E57}{\dotaccent{p}} + \DeclareUnicodeCharacter{1E58}{\dotaccent{R}} + \DeclareUnicodeCharacter{1E59}{\dotaccent{r}} + \DeclareUnicodeCharacter{1E5A}{\udotaccent{R}} + \DeclareUnicodeCharacter{1E5B}{\udotaccent{r}} + \DeclareUnicodeCharacter{1E5E}{\ubaraccent{R}} + \DeclareUnicodeCharacter{1E5F}{\ubaraccent{r}} + + \DeclareUnicodeCharacter{1E60}{\dotaccent{S}} + \DeclareUnicodeCharacter{1E61}{\dotaccent{s}} + \DeclareUnicodeCharacter{1E62}{\udotaccent{S}} + \DeclareUnicodeCharacter{1E63}{\udotaccent{s}} + \DeclareUnicodeCharacter{1E6A}{\dotaccent{T}} + \DeclareUnicodeCharacter{1E6B}{\dotaccent{t}} + \DeclareUnicodeCharacter{1E6C}{\udotaccent{T}} + \DeclareUnicodeCharacter{1E6D}{\udotaccent{t}} + \DeclareUnicodeCharacter{1E6E}{\ubaraccent{T}} + \DeclareUnicodeCharacter{1E6F}{\ubaraccent{t}} + + \DeclareUnicodeCharacter{1E7C}{\~V} + \DeclareUnicodeCharacter{1E7D}{\~v} + \DeclareUnicodeCharacter{1E7E}{\udotaccent{V}} + \DeclareUnicodeCharacter{1E7F}{\udotaccent{v}} + + \DeclareUnicodeCharacter{1E80}{\`W} + \DeclareUnicodeCharacter{1E81}{\`w} + \DeclareUnicodeCharacter{1E82}{\'W} + \DeclareUnicodeCharacter{1E83}{\'w} + \DeclareUnicodeCharacter{1E84}{\"W} + \DeclareUnicodeCharacter{1E85}{\"w} + \DeclareUnicodeCharacter{1E86}{\dotaccent{W}} + \DeclareUnicodeCharacter{1E87}{\dotaccent{w}} + \DeclareUnicodeCharacter{1E88}{\udotaccent{W}} + \DeclareUnicodeCharacter{1E89}{\udotaccent{w}} + \DeclareUnicodeCharacter{1E8A}{\dotaccent{X}} + \DeclareUnicodeCharacter{1E8B}{\dotaccent{x}} + \DeclareUnicodeCharacter{1E8C}{\"X} + \DeclareUnicodeCharacter{1E8D}{\"x} + \DeclareUnicodeCharacter{1E8E}{\dotaccent{Y}} + \DeclareUnicodeCharacter{1E8F}{\dotaccent{y}} + + \DeclareUnicodeCharacter{1E90}{\^Z} + \DeclareUnicodeCharacter{1E91}{\^z} + \DeclareUnicodeCharacter{1E92}{\udotaccent{Z}} + \DeclareUnicodeCharacter{1E93}{\udotaccent{z}} + \DeclareUnicodeCharacter{1E94}{\ubaraccent{Z}} + \DeclareUnicodeCharacter{1E95}{\ubaraccent{z}} + \DeclareUnicodeCharacter{1E96}{\ubaraccent{h}} + \DeclareUnicodeCharacter{1E97}{\"t} + \DeclareUnicodeCharacter{1E98}{\ringaccent{w}} + \DeclareUnicodeCharacter{1E99}{\ringaccent{y}} + + \DeclareUnicodeCharacter{1EA0}{\udotaccent{A}} + \DeclareUnicodeCharacter{1EA1}{\udotaccent{a}} + + \DeclareUnicodeCharacter{1EB8}{\udotaccent{E}} + \DeclareUnicodeCharacter{1EB9}{\udotaccent{e}} + \DeclareUnicodeCharacter{1EBC}{\~E} + \DeclareUnicodeCharacter{1EBD}{\~e} + + \DeclareUnicodeCharacter{1ECA}{\udotaccent{I}} + \DeclareUnicodeCharacter{1ECB}{\udotaccent{i}} + \DeclareUnicodeCharacter{1ECC}{\udotaccent{O}} + \DeclareUnicodeCharacter{1ECD}{\udotaccent{o}} + + \DeclareUnicodeCharacter{1EE4}{\udotaccent{U}} + \DeclareUnicodeCharacter{1EE5}{\udotaccent{u}} + + \DeclareUnicodeCharacter{1EF2}{\`Y} + \DeclareUnicodeCharacter{1EF3}{\`y} + \DeclareUnicodeCharacter{1EF4}{\udotaccent{Y}} + + \DeclareUnicodeCharacter{1EF8}{\~Y} + \DeclareUnicodeCharacter{1EF9}{\~y} + + \DeclareUnicodeCharacter{2013}{--} + \DeclareUnicodeCharacter{2014}{---} + \DeclareUnicodeCharacter{2018}{\quoteleft} + \DeclareUnicodeCharacter{2019}{\quoteright} + \DeclareUnicodeCharacter{201A}{\quotesinglbase} + \DeclareUnicodeCharacter{201C}{\quotedblleft} + \DeclareUnicodeCharacter{201D}{\quotedblright} + \DeclareUnicodeCharacter{201E}{\quotedblbase} + \DeclareUnicodeCharacter{2022}{\bullet} + \DeclareUnicodeCharacter{2026}{\dots} + \DeclareUnicodeCharacter{2039}{\guilsinglleft} + \DeclareUnicodeCharacter{203A}{\guilsinglright} + \DeclareUnicodeCharacter{20AC}{\euro} + + \DeclareUnicodeCharacter{2192}{\expansion} + \DeclareUnicodeCharacter{21D2}{\result} + + \DeclareUnicodeCharacter{2212}{\minus} + \DeclareUnicodeCharacter{2217}{\point} + \DeclareUnicodeCharacter{2261}{\equiv} +}% end of \utfeightchardefs + + +% US-ASCII character definitions. +\def\asciichardefs{% nothing need be done + \relax +} + +% Make non-ASCII characters printable again for compatibility with +% existing Texinfo documents that may use them, even without declaring a +% document encoding. +% +\setnonasciicharscatcode \other + + +\message{formatting,} + +\newdimen\defaultparindent \defaultparindent = 15pt + +\chapheadingskip = 15pt plus 4pt minus 2pt +\secheadingskip = 12pt plus 3pt minus 2pt +\subsecheadingskip = 9pt plus 2pt minus 2pt + +% Prevent underfull vbox error messages. +\vbadness = 10000 + +% Don't be so finicky about underfull hboxes, either. +\hbadness = 2000 + +% Following George Bush, get rid of widows and orphans. +\widowpenalty=10000 +\clubpenalty=10000 + +% Use TeX 3.0's \emergencystretch to help line breaking, but if we're +% using an old version of TeX, don't do anything. We want the amount of +% stretch added to depend on the line length, hence the dependence on +% \hsize. We call this whenever the paper size is set. +% +\def\setemergencystretch{% + \ifx\emergencystretch\thisisundefined + % Allow us to assign to \emergencystretch anyway. + \def\emergencystretch{\dimen0}% + \else + \emergencystretch = .15\hsize + \fi +} + +% Parameters in order: 1) textheight; 2) textwidth; +% 3) voffset; 4) hoffset; 5) binding offset; 6) topskip; +% 7) physical page height; 8) physical page width. +% +% We also call \setleading{\textleading}, so the caller should define +% \textleading. The caller should also set \parskip. +% +\def\internalpagesizes#1#2#3#4#5#6#7#8{% + \voffset = #3\relax + \topskip = #6\relax + \splittopskip = \topskip + % + \vsize = #1\relax + \advance\vsize by \topskip + \outervsize = \vsize + \advance\outervsize by 2\topandbottommargin + \pageheight = \vsize + % + \hsize = #2\relax + \outerhsize = \hsize + \advance\outerhsize by 0.5in + \pagewidth = \hsize + % + \normaloffset = #4\relax + \bindingoffset = #5\relax + % + \ifpdf + \pdfpageheight #7\relax + \pdfpagewidth #8\relax + % if we don't reset these, they will remain at "1 true in" of + % whatever layout pdftex was dumped with. + \pdfhorigin = 1 true in + \pdfvorigin = 1 true in + \fi + % + \setleading{\textleading} + % + \parindent = \defaultparindent + \setemergencystretch +} + +% @letterpaper (the default). +\def\letterpaper{{\globaldefs = 1 + \parskip = 3pt plus 2pt minus 1pt + \textleading = 13.2pt + % + % If page is nothing but text, make it come out even. + \internalpagesizes{607.2pt}{6in}% that's 46 lines + {\voffset}{.25in}% + {\bindingoffset}{36pt}% + {11in}{8.5in}% +}} + +% Use @smallbook to reset parameters for 7x9.25 trim size. +\def\smallbook{{\globaldefs = 1 + \parskip = 2pt plus 1pt + \textleading = 12pt + % + \internalpagesizes{7.5in}{5in}% + {-.2in}{0in}% + {\bindingoffset}{16pt}% + {9.25in}{7in}% + % + \lispnarrowing = 0.3in + \tolerance = 700 + \hfuzz = 1pt + \contentsrightmargin = 0pt + \defbodyindent = .5cm +}} + +% Use @smallerbook to reset parameters for 6x9 trim size. +% (Just testing, parameters still in flux.) +\def\smallerbook{{\globaldefs = 1 + \parskip = 1.5pt plus 1pt + \textleading = 12pt + % + \internalpagesizes{7.4in}{4.8in}% + {-.2in}{-.4in}% + {0pt}{14pt}% + {9in}{6in}% + % + \lispnarrowing = 0.25in + \tolerance = 700 + \hfuzz = 1pt + \contentsrightmargin = 0pt + \defbodyindent = .4cm +}} + +% Use @afourpaper to print on European A4 paper. +\def\afourpaper{{\globaldefs = 1 + \parskip = 3pt plus 2pt minus 1pt + \textleading = 13.2pt + % + % Double-side printing via postscript on Laserjet 4050 + % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm. + % To change the settings for a different printer or situation, adjust + % \normaloffset until the front-side and back-side texts align. Then + % do the same for \bindingoffset. You can set these for testing in + % your texinfo source file like this: + % @tex + % \global\normaloffset = -6mm + % \global\bindingoffset = 10mm + % @end tex + \internalpagesizes{673.2pt}{160mm}% that's 51 lines + {\voffset}{\hoffset}% + {\bindingoffset}{44pt}% + {297mm}{210mm}% + % + \tolerance = 700 + \hfuzz = 1pt + \contentsrightmargin = 0pt + \defbodyindent = 5mm +}} + +% Use @afivepaper to print on European A5 paper. +% From romildo@urano.iceb.ufop.br, 2 July 2000. +% He also recommends making @example and @lisp be small. +\def\afivepaper{{\globaldefs = 1 + \parskip = 2pt plus 1pt minus 0.1pt + \textleading = 12.5pt + % + \internalpagesizes{160mm}{120mm}% + {\voffset}{\hoffset}% + {\bindingoffset}{8pt}% + {210mm}{148mm}% + % + \lispnarrowing = 0.2in + \tolerance = 800 + \hfuzz = 1.2pt + \contentsrightmargin = 0pt + \defbodyindent = 2mm + \tableindent = 12mm +}} + +% A specific text layout, 24x15cm overall, intended for A4 paper. +\def\afourlatex{{\globaldefs = 1 + \afourpaper + \internalpagesizes{237mm}{150mm}% + {\voffset}{4.6mm}% + {\bindingoffset}{7mm}% + {297mm}{210mm}% + % + % Must explicitly reset to 0 because we call \afourpaper. + \globaldefs = 0 +}} + +% Use @afourwide to print on A4 paper in landscape format. +\def\afourwide{{\globaldefs = 1 + \afourpaper + \internalpagesizes{241mm}{165mm}% + {\voffset}{-2.95mm}% + {\bindingoffset}{7mm}% + {297mm}{210mm}% + \globaldefs = 0 +}} + +% @pagesizes TEXTHEIGHT[,TEXTWIDTH] +% Perhaps we should allow setting the margins, \topskip, \parskip, +% and/or leading, also. Or perhaps we should compute them somehow. +% +\parseargdef\pagesizes{\pagesizesyyy #1,,\finish} +\def\pagesizesyyy#1,#2,#3\finish{{% + \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi + \globaldefs = 1 + % + \parskip = 3pt plus 2pt minus 1pt + \setleading{\textleading}% + % + \dimen0 = #1\relax + \advance\dimen0 by \voffset + % + \dimen2 = \hsize + \advance\dimen2 by \normaloffset + % + \internalpagesizes{#1}{\hsize}% + {\voffset}{\normaloffset}% + {\bindingoffset}{44pt}% + {\dimen0}{\dimen2}% +}} + +% Set default to letter. +% +\letterpaper + + +\message{and turning on texinfo input format.} + +% Define macros to output various characters with catcode for normal text. +\catcode`\"=\other +\catcode`\~=\other +\catcode`\^=\other +\catcode`\_=\other +\catcode`\|=\other +\catcode`\<=\other +\catcode`\>=\other +\catcode`\+=\other +\catcode`\$=\other +\def\normaldoublequote{"} +\def\normaltilde{~} +\def\normalcaret{^} +\def\normalunderscore{_} +\def\normalverticalbar{|} +\def\normalless{<} +\def\normalgreater{>} +\def\normalplus{+} +\def\normaldollar{$}%$ font-lock fix + +% This macro is used to make a character print one way in \tt +% (where it can probably be output as-is), and another way in other fonts, +% where something hairier probably needs to be done. +% +% #1 is what to print if we are indeed using \tt; #2 is what to print +% otherwise. Since all the Computer Modern typewriter fonts have zero +% interword stretch (and shrink), and it is reasonable to expect all +% typewriter fonts to have this, we can check that font parameter. +% +\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi} + +% Same as above, but check for italic font. Actually this also catches +% non-italic slanted fonts since it is impossible to distinguish them from +% italic fonts. But since this is only used by $ and it uses \sl anyway +% this is not a problem. +\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi} + +% Turn off all special characters except @ +% (and those which the user can use as if they were ordinary). +% Most of these we simply print from the \tt font, but for some, we can +% use math or other variants that look better in normal text. + +\catcode`\"=\active +\def\activedoublequote{{\tt\char34}} +\let"=\activedoublequote +\catcode`\~=\active +\def~{{\tt\char126}} +\chardef\hat=`\^ +\catcode`\^=\active +\def^{{\tt \hat}} + +\catcode`\_=\active +\def_{\ifusingtt\normalunderscore\_} +\let\realunder=_ +% Subroutine for the previous macro. +\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em } + +\catcode`\|=\active +\def|{{\tt\char124}} +\chardef \less=`\< +\catcode`\<=\active +\def<{{\tt \less}} +\chardef \gtr=`\> +\catcode`\>=\active +\def>{{\tt \gtr}} +\catcode`\+=\active +\def+{{\tt \char 43}} +\catcode`\$=\active +\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix + +% If a .fmt file is being used, characters that might appear in a file +% name cannot be active until we have parsed the command line. +% So turn them off again, and have \everyjob (or @setfilename) turn them on. +% \otherifyactive is called near the end of this file. +\def\otherifyactive{\catcode`+=\other \catcode`\_=\other} + +% Used sometimes to turn off (effectively) the active characters even after +% parsing them. +\def\turnoffactive{% + \normalturnoffactive + \otherbackslash +} + +\catcode`\@=0 + +% \backslashcurfont outputs one backslash character in current font, +% as in \char`\\. +\global\chardef\backslashcurfont=`\\ +\global\let\rawbackslashxx=\backslashcurfont % let existing .??s files work + +% \realbackslash is an actual character `\' with catcode other, and +% \doublebackslash is two of them (for the pdf outlines). +{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}} + +% In texinfo, backslash is an active character; it prints the backslash +% in fixed width font. +\catcode`\\=\active +@def@normalbackslash{{@tt@backslashcurfont}} +% On startup, @fixbackslash assigns: +% @let \ = @normalbackslash + +% \rawbackslash defines an active \ to do \backslashcurfont. +% \otherbackslash defines an active \ to be a literal `\' character with +% catcode other. +@gdef@rawbackslash{@let\=@backslashcurfont} +@gdef@otherbackslash{@let\=@realbackslash} + +% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of +% the literal character `\'. +% +@def@normalturnoffactive{% + @let\=@normalbackslash + @let"=@normaldoublequote + @let~=@normaltilde + @let^=@normalcaret + @let_=@normalunderscore + @let|=@normalverticalbar + @let<=@normalless + @let>=@normalgreater + @let+=@normalplus + @let$=@normaldollar %$ font-lock fix + @unsepspaces +} + +% Make _ and + \other characters, temporarily. +% This is canceled by @fixbackslash. +@otherifyactive + +% If a .fmt file is being used, we don't want the `\input texinfo' to show up. +% That is what \eatinput is for; after that, the `\' should revert to printing +% a backslash. +% +@gdef@eatinput input texinfo{@fixbackslash} +@global@let\ = @eatinput + +% On the other hand, perhaps the file did not have a `\input texinfo'. Then +% the first `\' in the file would cause an error. This macro tries to fix +% that, assuming it is called before the first `\' could plausibly occur. +% Also turn back on active characters that might appear in the input +% file name, in case not using a pre-dumped format. +% +@gdef@fixbackslash{% + @ifx\@eatinput @let\ = @normalbackslash @fi + @catcode`+=@active + @catcode`@_=@active +} + +% Say @foo, not \foo, in error messages. +@escapechar = `@@ + +% These look ok in all fonts, so just make them not special. +@catcode`@& = @other +@catcode`@# = @other +@catcode`@% = @other + + +@c Local variables: +@c eval: (add-hook 'write-file-hooks 'time-stamp) +@c page-delimiter: "^\\\\message" +@c time-stamp-start: "def\\\\texinfoversion{" +@c time-stamp-format: "%:y-%02m-%02d.%02H" +@c time-stamp-end: "}" +@c End: + +@c vim:sw=2: + +@ignore + arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115 +@end ignore diff --git a/doc/uiserver.texi b/doc/uiserver.texi new file mode 100644 index 0000000..f3cd8ad --- /dev/null +++ b/doc/uiserver.texi @@ -0,0 +1,612 @@ +@c uiserver.texi -*- mode: texinfo; coding: latin-1; -*- +@c Specification of the UI server protocol. +@c To be included by gpgme.texi + +@node UI Server Protocol +@appendix The GnuPG UI Server Protocol +@cindex UI server +@cindex user interface server + + +This section specifies the protocol used between clients and a User +Interface Server (UI server). This protocol helps to build a system +where all cryptographic operations are done by a server and the server +is responsible for all dialogs. Although @acronym{GPGME} has no direct +support for this protocol it is believed that servers will utilize the +@acronym{GPGME} library; thus having the specification included in this +manual is an appropriate choice. This protocol should be referenced as +`The GnuPG UI Server Protocol'. + +@noindent +A server needs to implement these commands:@footnote{In all examples we +assume that the connection has already been established; see the Assuan +manual for details.} + +@menu +* UI Server Encrypt:: Encrypt a message. +* UI Server Sign:: Sign a message. +* UI Server Decrypt:: Decrypt a message. +* UI Server Verify:: Verify a message. +* UI Server Set Input Files:: Specifying the input files to operate on. +* UI Server Sign/Encrypt Files:: Encrypting and signing files. +* UI Server Verify/Decrypt Files:: Decrypting and verifying files. +* UI Server Import/Export Keys:: Managing certificates. +* UI Server Checksum Files:: Create and verify checksums for files. +* Miscellaneous UI Server Commands:: Commands not related to a specific operation. +@end menu + + + +@node UI Server Encrypt +@section UI Server: Encrypt a Message + +Before encryption can be done the recipients must be set using the +command: + +@deffn Command RECIPIENT @var{string} + +Set the recipient for the encryption. @var{string} is an RFC-2822 +recipient name ("mailbox" as per section 3.4). This command may or may +not check the recipient for validity right away; if it does not all +recipients are expected to be checked at the time of the @code{ENCRYPT} +command. All @code{RECIPIENT} commands are cumulative until a +successful @code{ENCRYPT} command or until a @code{RESET} command. +Linefeeds are obviously not allowed in @var{string} and should be folded +into spaces (which are equivalent). +@end deffn + +@noindent +To tell the server the source and destination of the data, the next two +commands are to be used: + +@deffn Command INPUT FD=@var{n} +Set the file descriptor for the message to be encrypted to @var{n}. The +message send to the server is binary encoded. + +GpgOL is a Windows only program, thus @var{n} is not a libc file +descriptor but a regular system handle. Given that the Assuan +connection works over a socket, it is not possible to use regular +inheritance to make the file descriptor available to the server. +Thus @code{DuplicateHandle} needs to be used to duplicate a handle +to the server process. This is the reason that the server needs to +implement the @code{GETINFO pid} command. Sending this command a second +time replaces the file descriptor set by the last one. +@c If @var{n} is not given, this commands uses the +@c %last file descriptor passed to the application. +@c %@xref{fun-assuan_sendfd, ,the assuan_sendfd function,assuan,the +@c %Libassuan manual}, on how to do descriptor passing. +@end deffn + +@deffn Command OUTPUT FD=@var{n} +Set the file descriptor to be used for the output (i.e. the encrypted +message) to @var{n}. For OpenPGP, the output needs to be ASCII armored; +for CMS, the output needs to be Base-64 encoded. For details on the +file descriptor, see the @code{INPUT} command. +@end deffn + +@noindent +The setting of the recipients, the data source and destination may +happen in any order, even intermixed. If this has been done the actual +encryption operation is called using: + +@deffn Command ENCRYPT -@w{}-protocol=@var{name} + +This command reads the plaintext from the file descriptor set by the +@code{INPUT} command, encrypts it and writes the ciphertext to the file +descriptor set by the @code{OUTPUT} command. The server may (and +should) overlap reading and writing. The recipients used for the +encryption are all the recipients set so far. If any recipient is not +usable the server should take appropriate measures to notify the user +about the problem and may cancel the operation by returning an error +code. The used file descriptors are void after this command; the +recipient list is only cleared if the server returns success. + +@noindent +Because GpgOL uses a streaming mode of operation the server is not +allowed to auto select the protocol and must obey to the mandatory +@var{protocol} parameter: + +@table @code +@item OpenPGP +Use the OpenPGP protocol (RFC-2440). +@item CMS +Use the CMS (PKCS#7) protocol (RFC-3852). +@end table + +@end deffn + +To support automagically selection of the protocol depending on the +selected keys, the server MAY implement the command: + +@deffn Command PREP_ENCRYPT [-@w{}-protocol=@var{name}] [-@w{}-expect-sign] + +This commands considers all recipients set so far and decides whether it +is able to take input and start the actual encryption. This is kind of +a dry-run @command{ENCRYPT} without requiring or using the input and +output file descriptors. The server shall cache the result of any user +selection to avoid asking this again when the actual @command{ENCRYPT} +command is send. The @option{--protocol} option is optional; if it is +not given, the server should allow the user to select the protocol to be +used based on the recipients given or by any other means. + +If @option{--expect-sign} is given the server should expect that the +message will also be signed and use this hint to present a unified +recipient and signer selection dialog if possible and desired. A +selected signer should then be cached for the expected SIGN command +(which is expected in the same session but possible on another +connection). + +If this command is given again before a successful @command{ENCRYPT} +command, the second one takes effect. + +Before sending the OK response the server shall tell the client the +protocol to be used (either the one given by the argument or the one +selected by the user) by means of a status line: +@end deffn + +@deffn {Status line} PROTOCOL @var{name} +Advise the client to use the protocol @var{name} for the +@command{ENCRYPT} command. The valid protocol names are listed under +the description of the @command{ENCRYPT} command. The server shall emit +exactly one PROTOCOL status line. +@end deffn + +@noindent +Here is an example of a complete encryption sequence; client lines are +indicated by a @sc{c:}, server responses by @sc{c:}: + +@smallexample +@group + @clnt RESET + @srvr OK + @clnt RECIPIENT foo@@example.net + @srvr OK + @clnt RECIPIENT bar@@example.com + @srvr OK + @clnt PREP_ENCRYPT + @srvr S PROTOCOL OpenPGP + @srvr OK + @clnt INPUT FD=17 + @srvr OK + @clnt OUTPUT FD=18 + @srvr OK + @clnt ENCRYPT + @srvr OK +@end group +@end smallexample + + + +@node UI Server Sign +@section UI Server: Sign a Message + +The server needs to implement opaque signing as well as detached +signing. Due to the nature of OpenPGP messages it is always required to +send the entire message to the server; sending just the hash is not +possible. The following two commands are required to set the input and +output file descriptors: + +@deffn Command INPUT FD=@var{n} +Set the file descriptor for the message to be signed to @var{n}. The +message send to the server is binary encoded. For details on the file +descriptor, see the description of @code{INPUT} in the @code{ENCRYPT} +section. +@end deffn + +@deffn Command OUTPUT FD=@var{n} +Set the file descriptor to be used for the output. The output is either +the complete signed message or in case of a detached signature just that +detached signature. For OpenPGP, the output needs to be ASCII armored; +for CMS, the output needs to be Base-64 encoded. For details on the +file descriptor, see the @code{INPUT} command. +@end deffn + +@noindent +To allow the server the selection of a non-default signing key the +client may optionally use the @code{SENDER} command, see @ref{command +SENDER}. + +@noindent +The signing operation is then initiated by: + +@deffn Command SIGN -@w{}-protocol=@var{name} [-@w{}-detached] +Sign the data set with the @code{INPUT} command and write it to the sink +set by OUTPUT. @var{name} is the signing protocol used for the +message. For a description of the allowed protocols see the +@code{ENCRYPT} command. With option @code{--detached} given, a detached +signature is created; this is actually the usual way the command is +used. +@end deffn + +@noindent +The client expects the server to send at least this status information +before the final OK response: + +@deffn {Status line} MICALG @var{string} +The @var{string} represents the hash algorithm used to create the +signature. It is used with MOSS style signature messages and defined by +PGP/MIME (RFC-3156) and S/MIME (RFC-3851). The GPGME library has a +supporting function @code{gpgme_hash_algo_name} to return the algorithm +name as a string. This string needs to be lowercased and for OpenPGP +prefixed with "@code{pgp-}". +@end deffn + + + +@node UI Server Decrypt +@section UI Server: Decrypt a Message + +Decryption may include the verification of OpenPGP messages. This is +due to the often used combined signing/encryption modus of OpenPGP. The +client may pass an option to the server to inhibit the signature +verification. The following two commands are required to set the input +and output file descriptors: + +@deffn Command INPUT FD=@var{n} +Set the file descriptor for the message to be decrypted to @var{n}. The +message send to the server is either binary encoded or --- in the case +of OpenPGP --- ASCII armored. For details on the file descriptor, see +the description of @code{INPUT} in the @code{ENCRYPT} section. +@end deffn + +@deffn Command OUTPUT FD=@var{n} +Set the file descriptor to be used for the output. The output is binary +encoded. For details on the file descriptor, see the description of +@code{INPUT} in the @code{ENCRYPT} section. +@end deffn + +@noindent +The decryption is started with the command: + +@deffn Command DECRYPT -@w{}-protocol=@var{name} [-@w{}-no-verify] +@var{name} is the encryption protocol used for the message. For a +description of the allowed protocols see the @code{ENCRYPT} command. +This argument is mandatory. If the option @option{--no-verify} is given, +the server should not try to verify a signature, in case the input data +is an OpenPGP combined message. +@end deffn + + +@node UI Server Verify +@section UI Server: Verify a Message + +The server needs to support the verification of opaque signatures as +well as detached signatures. The kind of input sources controls what +kind message is to be verified. + +@deffn Command MESSAGE FD=@var{n} +This command is used with detached signatures to set the file descriptor +for the signed data to @var{n}. The data is binary encoded (used +verbatim). For details on the file descriptor, see the description of +@code{INPUT} in the @code{ENCRYPT} section. +@end deffn + +@deffn Command INPUT FD=@var{n} +Set the file descriptor for the opaque message or the signature part of +a detached signature to @var{n}. The message send to the server is +either binary encoded or -- in the case of OpenPGP -- ASCII armored. +For details on the file descriptor, see the description of @code{INPUT} +in the @code{ENCRYPT} section. +@end deffn + +@deffn Command OUTPUT FD=@var{n} +Set the file descriptor to be used for the output. The output is binary +encoded and only used for opaque signatures. For details on the file +descriptor, see the description of @code{INPUT} in the @code{ENCRYPT} +section. +@end deffn + +@noindent +The verification is then started using: + +@deffn Command VERIFY -@w{}-protocol=@var{name} [-@w{}-silent] +@var{name} is the signing protocol used for the message. For a +description of the allowed protocols see the @code{ENCRYPT} command. +This argument is mandatory. Depending on the combination of +@code{MESSAGE} @code{INPUT} and @code{OUTPUT} commands, the server needs +to select the appropriate verification mode: + +@table @asis +@item MESSAGE and INPUT +This indicates a detached signature. Output data is not applicable. +@item INPUT +This indicates an opaque signature. As no output command has been given, +the server is only required to check the signature. +@item INPUT and OUTPUT +This indicates an opaque signature. The server shall write the signed +data to the file descriptor set by the output command. This data shall +even be written if the signatures can't be verified. +@end table +@end deffn + +With @option{--silent} the server shall not display any dialog; this is +for example used by the client to get the content of opaque signed +messages. The client expects the server to send at least this status +information before the final OK response: + +@deffn {Status line} SIGSTATUS @var{flag} @var{displaystring} +Returns the status for the signature and a short string explaining the +status. Valid values for @var{flag} are: + +@table @code +@item none +The message has a signature but it could not not be verified due to a +missing key. +@item green +The signature is fully valid. +@item yellow +The signature is valid but additional information was shown regarding the +validity of the key. +@item red +The signature is not valid. +@end table + +@var{displaystring} is a percent-and-plus-encoded string with a short +human readable description of the status. For example + +@smallexample +S SIGSTATUS green Good+signature+from+Keith+Moon+<keith@@example.net> +@end smallexample + +Note that this string needs to fit into an Assuan line and should be +short enough to be displayed as short one-liner on the clients window. +As usual the encoding of this string is UTF-8 and it should be send in +its translated form. + +The server shall send one status line for every signature found on the +message. + + +@end deffn + + +@node UI Server Set Input Files +@section UI Server: Specifying the input files to operate on. + +All file related UI server commands operate on a number of input files +or directories, specified by one or more @code{FILE} commands: + +@deffn Command FILE @var{name} [--continued] +Add the file or directory @var{name} to the list of pathnames to be +processed by the server. The parameter @var{name} must be an absolute +path name (including the drive letter) and is percent espaced (in +particular, the characters %, = and white space characters are always +escaped). The option @code{--continued} is present for all but the +last @code{FILE} command. +@end deffn + + +@node UI Server Sign/Encrypt Files +@section UI Server: Encrypting and signing files. + +First, the input files need to be specified by one or more +@code{FILE} commands. Afterwards, the actual operation is requested: + +@deffn Command ENCRYPT_FILES --nohup +@deffnx Command SIGN_FILES --nohup +@deffnx Command ENCRYPT_SIGN_FILES --nohup +Request that the files specified by @code{FILE} are encrypted and/or +signed. The command selects the default action. The UI server may +allow the user to change this default afterwards interactively, and +even abort the operation or complete it only on some of the selected +files and directories. + +What it means to encrypt or sign a file or directory is specific to +the preferences of the user, the functionality the UI server provides, +and the selected protocol. Typically, for each input file a new file +is created under the original filename plus a protocol specific +extension (like @code{.gpg} or @code{.sig}), which contain the +encrypted/signed file or a detached signature. For directories, the +server may offer multiple options to the user (for example ignore or +process recursively). + +The @code{ENCRYPT_SIGN_FILES} command requests a combined sign and +encrypt operation. It may not be available for all protocols (for +example, it is available for OpenPGP but not for CMS). + +The option @code{--nohup} is mandatory. It is currently unspecified +what should happen if @code{--nohup} is not present. Because +@code{--nohup} is present, the server always returns @code{OK} +promptly, and completes the operation asynchronously. +@end deffn + + +@node UI Server Verify/Decrypt Files +@section UI Server: Decrypting and verifying files. + +First, the input files need to be specified by one or more +@code{FILE} commands. Afterwards, the actual operation is requested: + +@deffn Command DECRYPT_FILES --nohup +@deffnx Command VERIFY_FILES --nohup +@deffnx Command DECRYPT_VERIFY_FILES --nohup +Request that the files specified by @code{FILE} are decrypted and/or +verified. The command selects the default action. The UI server may +allow the user to change this default afterwards interactively, and +even abort the operation or complete it only on some of the selected +files and directories. + +What it means to decrypt or verify a file or directory is specific to +the preferences of the user, the functionality the UI server provides, +and the selected protocol. Typically, for decryption, a new file is +created for each input file under the original filename minus a +protocol specific extension (like @code{.gpg}) which contains the +original plaintext. For verification a status is displayed for each +signed input file, indicating if it is signed, and if yes, if the +signature is valid. For files that are signed and encrypted, the +@code{VERIFY} command transiently decrypts the file to verify the +enclosed signature. For directories, the server may offer multiple +options to the user (for example ignore or process recursively). + +The option @code{--nohup} is mandatory. It is currently unspecified +what should happen if @code{--nohup} is not present. Because +@code{--nohup} is present, the server always returns @code{OK} +promptly, and completes the operation asynchronously. +@end deffn + + +@node UI Server Import/Export Keys +@section UI Server: Managing certificates. + +First, the input files need to be specified by one or more +@code{FILE} commands. Afterwards, the actual operation is requested: + +@deffn Command IMPORT_FILES --nohup +Request that the certificates contained in the files specified by +@code{FILE} are imported into the local certificate databases. + +For directories, the server may offer multiple options to the user +(for example ignore or process recursively). + +The option @code{--nohup} is mandatory. It is currently unspecified +what should happen if @code{--nohup} is not present. Because +@code{--nohup} is present, the server always returns @code{OK} +promptly, and completes the operation asynchronously. +@end deffn + +FIXME: It may be nice to support an @code{EXPORT} command as well, +which is enabled by the context menu of the background of a directory. + + +@node UI Server Checksum Files +@section UI Server: Create and verify checksums for files. + +First, the input files need to be specified by one or more +@code{FILE} commands. Afterwards, the actual operation is requested: + +@deffn Command CHECKSUM_CREATE_FILES --nohup +Request that checksums are created for the files specifed by +@code{FILE}. The choice of checksum algorithm and the destination +storage and format for the created checksums depend on the preferences +of the user and the functionality provided by the UI server. For +directories, the server may offer multiple options to the user (for +example ignore or process recursively). + +The option @code{--nohup} is mandatory. It is currently unspecified +what should happen if @code{--nohup} is not present. Because +@code{--nohup} is present, the server always returns @code{OK} +promptly, and completes the operation asynchronously. +@end deffn + + +@deffn Command CHECKSUM_VERIFY_FILES --nohup +Request that checksums are created for the files specifed by +@code{FILE} and verified against previously created and stored +checksums. The choice of checksum algorithm and the source storage +and format for previously created checksums depend on the preferences +of the user and the functionality provided by the UI server. For +directories, the server may offer multiple options to the user (for +example ignore or process recursively). + +If the source storage of previously created checksums is available to +the user through the Windows shell, this command may also accept such +checksum files as @code{FILE} arguments. In this case, the UI server +should instead verify the checksum of the referenced files as if they +were given as INPUT files. + +The option @code{--nohup} is mandatory. It is currently unspecified +what should happen if @code{--nohup} is not present. Because +@code{--nohup} is present, the server always returns @code{OK} +promptly, and completes the operation asynchronously. +@end deffn + + + + +@c +@c M I S C E L L A N E O U S C O M M A N D S +@c +@node Miscellaneous UI Server Commands +@section Miscellaneous UI Server Commands + +The server needs to implement the following commands which are not +related to a specific command: + +@deffn Command GETINFO @var{what} +This is a multi purpose command, commonly used to return a variety of +information. The required subcommands as described by the @var{what} +parameter are: + +@table @code +@item pid +Return the process id of the server in decimal notation using an Assuan +data line. +@end table +@end deffn + + +@noindent +To allow the server to pop up the windows in the correct relation to the +client, the client is advised to tell the server by sending the option: + +@deffn {Command option} window-id @var{number} +The @var{number} represents the native window ID of the clients current +window. On Windows systems this is a windows handle (@code{HWND}) and +on X11 systems it is the @code{X Window ID}. The number needs to be +given as a hexadecimal value so that it is easier to convey pointer +values (e.g. @code{HWND}). +@end deffn + + +@noindent +A client may want to fire up the certificate manager of the server. To +do this it uses the Assuan command: + +@deffn Command START_KEYMANAGER +The server shall pop up the main window of the key manager (aka +certificate manager). The client expects that the key manager is brought +into the foregound and that this command immediatley returns (does not +wait until the key manager has been fully brought up). +@end deffn + +@noindent +A client may want to fire up the configuration dialog of the server. To +do this it uses the Assuan command: + +@deffn Command START_CONFDIALOG +The server shall pop up its configuration dialog. The client expects +that this dialog is brought into the foregound and that this command +immediatley returns (i.e. it does not wait until the dialog has been +fully brought up). +@end deffn + +@anchor{command SENDER} +@noindent +When doing an operation on a mail, it is useful to let the server know +the address of the sender: + +@deffn Command SENDER [-@w{}-info] [-@w{}-protocol=@var{name}] @var{email} +@var{email} is the plain ASCII encoded address ("addr-spec" as per +RFC-2822) enclosed in angle brackets. The address set with this command +is valid until a successful completion of the operation or until a +@code{RESET} command. A second command overrides the effect of the +first one; if @var{email} is not given and @option{--info} is not used, +the server shall use the default signing key. + +If option @option{--info} is not given, the server shall also suggest a +protocol to use for signing. The client may use this suggested protocol +on its own discretion. The same status line as with PREP_ENCRYPT is +used for this. + +The option @option{--protocol} may be used to give the server a hint on +which signing protocol should be preferred. +@end deffn + +@noindent +To allow the UI-server to visually identify a running operation or to +associate operations the server MAY support the command: + +@deffn Command SESSION @var{number} [@var{string}] +The @var{number} is an arbitrary value, a server may use to associate +simultaneous running sessions. It is a 32 bit unsigned integer with +@code{0} as a special value indicating that no session association shall +be done. + +If @var{string} is given, the server may use this as the title of a +window or, in the case of an email operation, to extract the sender's +address. The string may contain spaces; thus no plus-escaping is used. + +This command may be used at any time and overrides the effect of the +last command. A @code{RESET} undoes the effect of this command. + +@end deffn diff --git a/doc/version.texi b/doc/version.texi new file mode 100644 index 0000000..3e9775f --- /dev/null +++ b/doc/version.texi @@ -0,0 +1,4 @@ +@set UPDATED 2 May 2012 +@set UPDATED-MONTH May 2012 +@set EDITION 1.3.2 +@set VERSION 1.3.2 |